NAME¶
Config::Model::Manual::ModelCreationIntroduction - Introduction to model
creation with Config::Model
VERSION¶
version 2.061
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.
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))
- •
- 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
will be 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 will use the configuration file
- 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
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.
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 will
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).
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::Display" for the"Display"
subsection
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'
},
},
]
}
The"Xorg::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.
Model analysis¶
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.
Model declaration¶
Configuration class declaration¶
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'
}
]
}
];
Configuration class declaration (easier way)¶
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"
Common attributes for all elements¶
This first set of attributes will help 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 will be shown
to the user no matter what. hidden elements will be explained with the
warp notion.
- •
- "status": is "obsolete", "deprecated" or
"standard" (default). Using a deprecated element will issue a
warning. Using an obsolete element will raise an exception.
See "Configuration_class" in Config::Model for details.
Simple leaf elements¶
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):
- 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 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".
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.
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' ]
}
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 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.
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.
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 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"):
{
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 will have to think about 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 will be shown in
the wizard. hidden elements will be 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 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"
- •
- 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.
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 will try to load
"Config::Model::Backend::Foo". (The class name is constructed with
"ucfirst($backend_name)")
"read_config" can also have custom parameters that will 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 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:
read_config => [ { backend => 'custom' ,
class => 'ProcessRead' ,
config_dir => '/etc/foo',
file => 'foo.conf',
auto_create => 1,
} ],
Writing configuration files¶
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.
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
Syntax migration example¶
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:
{
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:
- 1.
- Configuration is stored in old file "/etc/my_cfg/bar.conf"
- 2.
- 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.
- 3.
- Config::Model tries the second backend which succeeds and load
configuration data in the configuration tree
- 4.
- Config::Model writes data back from configuration tree using
"write_config" backend which writes
"/etc/my_cfg/example.pl"
- 5.
- 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.
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) 2014 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999