Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::Manual:UsereContributedePerlaDocumenodelCreationIntroduction(3)

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

VERSION
       version 2.140

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:

       o   Curly braces	"{ ... }" contain a dictionary of key, value pairs (a
	   "hash" in Perl land))

       o   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:

       o   A model defines one or more configuration class

       o   At least one	class is required to define the	configuration tree
	   root

       o   Each	class contains several elements. An element can	be:

	   o   A leaf to represent one configuration parameter

	   o   A list of hash of leaves	to represent several parameter

	   o   A node to hold a	node of	a configuration	tree

	   o   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):

       o   A boolean leaf for "pdiff" (1 if not	specified)

       o   An integer leaf for "max_wait" (10 seconds unless specified
	   otherwise)

       o   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:

       o   "Xorg" (root	class)

       o   "Xorg::Device"

       o   "Xorg::Screen"

       o   "Xorg::Screen::Option" for the Screen options

       o   "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 :

       o   Find	the structure of the configuration tree

       o   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:

       o   The structure is translated into configuration classes

       o   Configuration parameters are	translated into	elements

       o   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:

       o   name: mandatory name	of the class

       o   class_description: Description of the configuration class.

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

       o   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:

       o   "description": full length description of the attribute

       o   "summary": one line summary of the above description

       o   "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.

       o   "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:

       o   a type "hash" parameter

       o   the hash key	is a string

       o   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:

       o   type	(set to	"node")

       o   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:

       o   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
       o   More	complex	models:	Config::Model::Manual::ModelCreationAdvanced

       o   Config::Model::Manual::ModelForUpgrade: Writing a model for
	   configuration upgrades

       o   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-2020	by Dominique Dumont.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

perl v5.32.0		   Config::Model::Manual::ModelCreationIntroduction(3)

NAME | VERSION | Introduction | Some definitions | What is a configuration tree? | What is a model? | Model analysis | Model declaration | Configuration wizard | Reading configuration files | SEE ALSO | Feedback welcome | AUTHORS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::Manual::ModelCreationIntroduction&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help