Config::Model::Manual::ModelCreationIntroduction man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

Config::Model::Manual:UsereConfig::Model::Manual::ModelCreationIntroduction(3)

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

VERSION
       version 1.235

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 "experience") 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.

       ·   "experience": By using the experience parameter, you can change the
	   experience level of each element. Possible experience levels are
	   "master", "advanced" and "beginner" (default).

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

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::AutoRead.

       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::AutoRead.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::AutoRead 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::AutoRead 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>

perl v5.14.1		   Config::Model::Manual::ModelCreationIntroduction(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net