.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Config::Model::Manual::ModelCreationIntroduction 3pm" .TH Config::Model::Manual::ModelCreationIntroduction 3pm "2017-05-14" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Config::Model::Manual::ModelCreationIntroduction \- Introduction to model creation with Config::Model .SH "VERSION" .IX Header "VERSION" version 2.097 .SH "Introduction" .IX Header "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. .PP 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 \s-1JSON\s0 structure. The only thing you need to know are: .IP "\(bu" 4 Curly braces \f(CW\*(C`{ ... }\*(C'\fR contain a dictionary of key, value pairs (a \&\f(CW\*(C`hash\*(C'\fR in Perl land)) .IP "\(bu" 4 Square brackets \f(CW\*(C`[ ... ]\*(C'\fR contain a list of items (\f(CW\*(C`array\*(C'\fR or \&\f(CW\*(C`list\*(C'\fR in Perl land) .SH "Some definitions" .IX Header "Some definitions" .IP "configuration file" 4 .IX Item "configuration file" Text file where configuration data are stored. This configuration file is used by an application \*(-- the \fItarget application\fR .IP "configuration tree" 4 .IX Item "configuration tree" The semantic content of the configuration file stored in a tree representation .IP "configuration model" 4 .IX Item "configuration model" Structure and constraints of the configuration tree. Like a schema for the configuration tree .IP "target application" 4 .IX Item "target application" The application that uses the configuration file. The application can be of type \f(CW\*(C`system\*(C'\fR (i.e. the configuration file is located in \&\f(CW\*(C`/etc\*(C'\fR), \f(CW\*(C`user\*(C'\fR (i.e. the configuration file is located in a user directory like \f(CW\*(C`~/.config\*(C'\fR) or \f(CW\*(C`application\*(C'\fR (the configuration file is in or below the current directory) .IP "end user" 4 .IX Item "end user" User of the target application .IP "application developer" 4 .IX Item "application developer" Target application developer .IP "model developer" 4 .IX Item "model developer" People developing the configuration model. Not necessarily the application developer .SH "What is a configuration tree?" .IX Header "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 \s-1XML,\s0 Apache) or not so obvious (\f(CW\*(C`Xorg\*(C'\fR syntax, \&\s-1INI\s0 syntax). .PP For some files like \f(CW\*(C`approx.conf\*(C'\fR or \f(CW\*(C`adduser.conf\*(C'\fR, this tree structure is quite flat. It looks much like a rake than a tree, but still, it's a tree. .PP For instance, this \f(CW\*(C`approx.conf\*(C'\fR: .PP .Vb 3 \& $pdiffs 1 \& $max_wait 14 \& debian http://ftp.fr.debian.org/debian .Ve .PP can have this tree representation: .PP .Vb 4 \& root \& |\-\-pdiff=1 \& |\-\-max_wait=14 \& \`\-\-distrib(debian)=http://ftp.fr.debian.org/debian .Ve .PP Other configuration files like \f(CW\*(C`apache2.conf\*(C'\fR or \f(CW\*(C`xorg.conf\*(C'\fR have a structure that look more like a tree. .PP For instance, consider this \f(CW\*(C`xorg.conf\*(C'\fR snippet: .PP .Vb 4 \& 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 .Ve .PP Knowing that Xorg.conf can have several Device or Screen sections identified by their \f(CW\*(C`Identifiers\*(C'\fR, the configuration can be represented in this tree as: .PP .Vb 10 \& root \& |\-\-Device(Device0) \& | \`\-\-Driver=nvidia \& \`\-\-Screen(Screen0) \& |\-\-Device=Device0 \& |\-\-Option \& | |\-\-AllowGLXWithComposite=True \& | \`\-\-DynamicTwinView=True \& \`\-\-Display \& \`\-\-Depth=24 .Ve .PP One may argue that some \f(CW\*(C`Xorg\*(C'\fR parameter refer to others (i.e.\f(CW\*(C`Device\*(C'\fR and \f(CW\*(C`Monitor\*(C'\fR value in \f(CW\*(C`Screen\*(C'\fR 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. .PP In some other case, the structure of a tree is not fixed. For instance, \f(CW\*(C`Device\*(C'\fR options in \f(CW\*(C`Xorg.conf\*(C'\fR are different depending on the value of the \f(CW\*(C`Device Driver\*(C'\fR. In this case, the structure of the configuration tree must be adapted (morphed) depending on a parameter value. .PP Just like \s-1XML\s0 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, \s-1XML\s0 like schema are not enough to validate configuration data. .PP 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 \f(CW\*(C`Xorg\*(C'\fR (and others). .SH "What is a model?" .IX Header "What is a model?" A configuration model defines the configuration tree structure: .IP "\(bu" 4 A model defines one or more configuration class .IP "\(bu" 4 At least one class is required to define the configuration tree root .IP "\(bu" 4 Each class contains several elements. An element can be: .RS 4 .IP "\(bu" 4 A leaf to represent one configuration parameter .IP "\(bu" 4 A list of hash of leaves to represent several parameter .IP "\(bu" 4 A node to hold a node of a configuration tree .IP "\(bu" 4 A list or hash of nodes .RE .RS 4 .RE .PP These basic relations enable to define the main parts of a configuration tree. .PP If we refer to the \f(CW\*(C`approx.conf\*(C'\fR example mentioned above, one only class is required (let's say the \f(CW\*(C`Approx\*(C'\fR class). This class must contain (see approx.conf man page): .IP "\(bu" 4 A boolean leaf for \f(CW\*(C`pdiff\*(C'\fR (1 if not specified) .IP "\(bu" 4 An integer leaf for \f(CW\*(C`max_wait\*(C'\fR (10 seconds unless specified otherwise) .IP "\(bu" 4 A hash of string leaves for \f(CW\*(C`distrib\*(C'\fR (no default). .PP A configuration model is stored this way by Config::Model: .PP .Vb 10 \& { \& name => \*(AqApprox\*(Aq, \& element => [ \& pdiffs => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aqboolean\*(Aq, \& upstream_default => \*(Aq1\*(Aq \& }, \& max_wait => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aqinteger\*(Aq, \& upstream_default => \*(Aq10\*(Aq \& }, \& distributions\*(Aq=> { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq , \& cargo => { \& value_type => \*(Aquniline\*(Aq, \& type => \*(Aqleaf\*(Aq, \& }, \& } \& ] \& } .Ve .PP The \f(CW\*(C`Xorg\*(C'\fR example leads to a slightly more complex model with several classes: .IP "\(bu" 4 \&\f(CW\*(C`Xorg\*(C'\fR (root class) .IP "\(bu" 4 \&\f(CW\*(C`Xorg::Device\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`Xorg::Screen\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`Xorg::Screen::Option\*(C'\fR for the Screen options .IP "\(bu" 4 \&\f(CW\*(C`Xorg::Screen::Display\*(C'\fR for the\f(CW\*(C`Display\*(C'\fR subsection .PP The root class is declared this way: .PP .Vb 10 \& { \& name => \*(AqXorg\*(Aq, \& element => [ \& Device => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq \& cargo => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Device\*(Aq \& }, \& }, \& Screen => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq \& cargo => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Screen\*(Aq \& }, \& }, \& ] \& } .Ve .PP The\f(CW\*(C`Xorg::Screen\*(C'\fR class is: .PP .Vb 10 \& { \& name => \*(AqXorg::Screen\*(Aq, \& element => [ \& Device => { \& type\*(Aq => \*(Aqleaf\*(Aq, \& value_type => \*(Aquniline\*(Aq, \& }, \& Display => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqinteger\*(Aq \& cargo => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Screen::Display\*(Aq \& }, \& } \& Option => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Screen::Option\*(Aq \& }, \& ] \& } .Ve .PP It's now time to detail how the elements of a class are constructed. .SH "Model analysis" .IX Header "Model analysis" To define the required configuration classes, you should read the documentation of the target application to : .IP "\(bu" 4 Find the structure of the configuration tree .IP "\(bu" 4 Identify configuration parameters, their constraints and relations .PP 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. .SH "Model declaration" .IX Header "Model declaration" .SS "Configuration class declaration" .IX Subsection "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 \f(CW\*(C`cme meta edit\*(C'\fR command (provided by Config::Model::Itself). This commands provides a \s-1GUI\s0 to create or update your model. .PP When saving, \f(CW\*(C`cme\*(C'\fR writes the data structure in the correct directory. .SS "Configuration class declaration (the hard way)" .IX Subsection "Configuration class declaration (the hard way)" In summary, configuration documentation is translated in a format usable by Config::Model: .IP "\(bu" 4 The structure is translated into configuration classes .IP "\(bu" 4 Configuration parameters are translated into elements .IP "\(bu" 4 Constraints are translated into element attributes .PP All models files must be written in a specific directory. For instance, for model \f(CW\*(C`Xorg\*(C'\fR, you must create \&\f(CW\*(C`./lib/Config/Model/models/Xorg.pl\*(C'\fR. Other classes like \f(CW\*(C`Xorg::Screen\*(C'\fR can be stored in their own file \&\f(CW\*(C`./lib/Config/Model/models/Xorg/Screen.pl\*(C'\fR or included in \f(CW\*(C`Xorg.pl\*(C'\fR .PP A model file is a Perl file containing an array for hash ref. Each Hash ref contains a class declaration: .PP .Vb 1 \& [ { name => \*(AqXorg\*(Aq, ... } , { name => \*(AqXorg::Screen\*(Aq, ... } ] ; .Ve .PP A class can have the following parameters: .IP "\(bu" 4 name: mandatory name of the class .IP "\(bu" 4 class_description: Description of the configuration class. .IP "\(bu" 4 generated_by: Mention with a descriptive string if this class was generated by a program. This parameter is currently reserved for \f(CW\*(C`Config::Model::Itself\*(C'\fR model editor. .IP "\(bu" 4 include: Include element description from another class. .PP For more details, see \*(L"Configuration_Model\*(R" in Config::Model. .PP For instance: .PP .Vb 10 \& $ cat lib/Config/Model/models/Xorg.pl \& [ \& { \& name => \*(AqXorg\*(Aq, \& class_description => \*(AqTop level Xorg configuration.\*(Aq, \& include => [ \*(AqXorg::ConfigDir\*(Aq], \& element => [ \& Files => { \& type => \*(Aqnode\*(Aq, \& description => \*(AqFile pathnames\*(Aq, \& config_class_name => \*(AqXorg::Files\*(Aq \& }, \& # snip \& ] \& }, \& { \& name => \*(AqXorg::DRI\*(Aq, \& element => [ \& Mode => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aquniline\*(Aq, \& description => \*(AqDRI mode, usually set to 0666\*(Aq \& } \& ] \& } \& ]; .Ve .SS "Common attributes for all elements" .IX Subsection "Common attributes for all elements" This first set of attributes helps the user by providing guidance (with \f(CW\*(C`level\*(C'\fR and \f(CW\*(C`status\*(C'\fR) and documentation (\f(CW\*(C`summary\*(C'\fR and \f(CW\*(C`description\*(C'\fR). .PP All elements (simple or complex) can have the following attributes: .IP "\(bu" 4 \&\f(CW\*(C`description\*(C'\fR: full length description of the attribute .IP "\(bu" 4 \&\f(CW\*(C`summary\*(C'\fR: one line summary of the above description .IP "\(bu" 4 \&\f(CW\*(C`level\*(C'\fR: is \f(CW\*(C`important\*(C'\fR, \f(CW\*(C`normal\*(C'\fR or \f(CW\*(C`hidden\*(C'\fR. 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. .IP "\(bu" 4 \&\f(CW\*(C`status\*(C'\fR: is \f(CW\*(C`obsolete\*(C'\fR, \f(CW\*(C`deprecated\*(C'\fR or \f(CW\*(C`standard\*(C'\fR (default). Warnings are shown when using a deprecated element and an exception is raised when an obsolete element is used. .PP See \*(L"Configuration_class\*(R" in Config::Model for details. .SS "Leaf elements" .IX Subsection "Leaf elements" Leaf element is the most common type to represent configuration data. A leaf element represents a specific configuration parameter. .PP In more details, a leaf element have the following attributes (See \&\*(L"Value_model_declaration\*(R" in Config::Model::Value doc): .IP "type" 4 .IX Item "type" Set to \f(CW\*(C`leaf\*(C'\fR (mandatory) .IP "value_type" 4 .IX Item "value_type" Either \f(CW\*(C`boolean\*(C'\fR, \f(CW\*(C`integer\*(C'\fR, \f(CW\*(C`number\*(C'\fR, \f(CW\*(C`enum\*(C'\fR, \f(CW\*(C`string\*(C'\fR, \&\f(CW\*(C`uniline\*(C'\fR (i.e. a string without \*(L"\en\*(R") (mandatory) .IP "min" 4 .IX Item "min" Minimum value (for \f(CW\*(C`integer\*(C'\fR or \f(CW\*(C`number\*(C'\fR) .IP "max" 4 .IX Item "max" Maximum value (for \f(CW\*(C`integer\*(C'\fR or \f(CW\*(C`number\*(C'\fR) .IP "choice" 4 .IX Item "choice" Possible values for an enum .IP "mandatory" 4 .IX Item "mandatory" Whether the value is mandatory or not .IP "default" 4 .IX Item "default" Default value that must be written in the configuration file .IP "upstream_default" 4 .IX Item "upstream_default" Default value that is known by the target application and thus does not need to be written in the configuration file. .PP To know which attributes to use, you should read the documentation of the target application. .PP For instance, \f(CW\*(C`AddressFamily\*(C'\fR parameter (\fIsshd_config\fR\|(5)) is specified with: \fISpecifies which address family should be used by \fIsshd\fI\|(8). Valid arguments are \*(L"any\*(R", \*(L"inet\*(R" (use IPv4 only), or \*(L"inet6\*(R" (use IPv6 only). The default is \*(L"any\*(R".\fR .PP For Config::Model, \f(CW\*(C`AddressFamily\*(C'\fR is a type \f(CW\*(C`leaf\*(C'\fR element, value_type \f(CW\*(C`enum\*(C'\fR and the application falls back to \f(CW\*(C`any\*(C'\fR if this parameter is left blank in \f(CW\*(C`sshd_config\*(C'\fR file. .PP Thus the model of this element is : .PP .Vb 7 \& AddressFamily => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aqenum\*(Aq, \& upstream_default => \*(Aqany\*(Aq, \& description => \*(AqSpecifies which address family should be used by sshd(8).\*(Aq, \& choice => [ \*(Aqany\*(Aq, \*(Aqinet\*(Aq, \*(Aqinet6\*(Aq ] \& } .Ve .SS "Simple list or hash element" .IX Subsection "Simple list or hash element" Some configuration parameters are in fact a list or a hash of parameters. For instance, \f(CW\*(C`approx.conf\*(C'\fR can feature a list of remote repositories: .PP .Vb 3 \& # remote repositories \& debian http://ftp.fr.debian.org/debian \& multimedia http://www.debian\-multimedia.org .Ve .PP These repositorie URLs must be stored as a hash where the key is \&\fIdebian\fR or \fImultimedia\fR and the associated value is a \s-1URL.\s0 But this hash must have something which is not explicit in \f(CW\*(C`approx.conf\*(C'\fR file: a parameter name. Approx man page mentions that: \&\fIThe name/value pairs [not beginning with '$' are used to map distribution names to remote repositories.\fR. So let's use \f(CW\*(C`distribution\*(C'\fR as a parameter name. .PP The example is stored this way in the configuration tree: .PP .Vb 3 \& root \& |\-\-distribution(debian)=http://ftp.fr.debian.org/debian \& \`\-\-distribution(multimedia)=http://www.debian\-multimedia.org .Ve .PP The model needs to declare that \f(CW\*(C`distribution\*(C'\fR is: .IP "\(bu" 4 a type \f(CW\*(C`hash\*(C'\fR parameter .IP "\(bu" 4 the hash key is a string .IP "\(bu" 4 the values of the hash are of type \f(CW\*(C`leaf\*(C'\fR and value_type \f(CW\*(C`uniline\*(C'\fR .PP .Vb 10 \& distribution => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq, \& cargo => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aquniline\*(Aq, \& }, \& summary => \*(Aqremote repositories\*(Aq, \& description => \*(AqThe other name/value pairs are ...\*(Aq, \& } .Ve .PP For more details on list and hash elements, see hash or list model declaration man page. .SS "node element" .IX Subsection "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. .PP In the Xorg example above, the options of \f(CW\*(C`Xorg::Screen\*(C'\fR need their own sub-branch in the tree: .PP .Vb 4 \& Screen(Screen0) \& \`\-\-Option \& |\-\-AllowGLXWithComposite=True \& \`\-\-DynamicTwinView=True .Ve .PP 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. .PP A node element has the following parameters: .IP "\(bu" 4 type (set to \f(CW\*(C`node\*(C'\fR) .IP "\(bu" 4 the name of the configuration class name (>config_class_name>) .PP So the \f(CW\*(C`Option\*(C'\fR node element is declared with: .PP .Vb 4 \& Option => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Screen::Option\*(Aq \& }, .Ve .SS "Hash or list of nodes" .IX Subsection "Hash or list of nodes" Some configuration files can feature a set of rather complex configuration entities. For instance \f(CW\*(C`Xorg.pl\*(C'\fR can feature several Screen or Device definitions. These definitions are identified by the \&\f(CW\*(C`Identifier\*(C'\fR parameter: .PP .Vb 5 \& Section "Device" \& Identifier "Device0" \& Driver "nvidia" \& BusID "PCI:3:0:1" \& EndSection \& \& Section "Screen" \& Identifier "Screen0" \& Device "Device0" \& DefaultDepth 24 \& EndSection .Ve .PP The Xorg configuration tree features 2 elements (Screen and Device) that use the Identifier parameters as hash keys: .PP .Vb 7 \& root \& |\-\-Device(Device0) \& | |\-\-Driver=nvidia \& | \`\-\-BusId=PCI:3:0:1 \& \`\-\-Screen(Screen0) \& |\-\-Device=Device0 \& \`\-\-DefaultDepth=24 .Ve .PP And the Xorg model must define these 2 parameters as \f(CW\*(C`hash\*(C'\fR. The cargo of this hash is of type \f(CW\*(C`node\*(C'\fR and refers to 2 different configuration classes, one for \f(CW\*(C`Device\*(C'\fR (\f(CW\*(C`Xorg::Device\*(C'\fR) and one for \&\f(CW\*(C`Screen\*(C'\fR (\f(CW\*(C`Xorg::Screen\*(C'\fR): .PP .Vb 10 \& { \& name => \*(AqXorg\*(Aq, \& element => [ \& Device => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq \& cargo => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Device\*(Aq \& }, \& }, \& Screen => { \& type => \*(Aqhash\*(Aq, \& index_type => \*(Aqstring\*(Aq \& cargo => { \& type => \*(Aqnode\*(Aq, \& config_class_name => \*(AqXorg::Screen\*(Aq \& }, \& }, \& ] \& } .Ve .SH "Configuration wizard" .IX Header "Configuration wizard" Both Perl/Tk and Curses interfaces feature a configuration wizard generated from a configuration model. .PP The wizard works by exploring the configuration tree and stopping on each \fIimportant\fR element and on each error (mostly missing mandatory parameter). .PP When designing a model, you have to ponder for each element: .IP "\(bu" 4 The importance level of the parameter (important, normal or hidden). \f(CW\*(C`level\*(C'\fR 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. .SH "Reading configuration files" .IX Header "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. .PP For Config::Model to read the file, the model designer must declare in the model how to read the file (the read backend). .PP The read method can use one or more of the following mechanisms: .IP "\(bu" 4 Built-in, e.g Perl file, \s-1INI\s0 file... .IP "\(bu" 4 A plugin, i.e. a Perl \f(CW\*(C`Config::Model::Backend::*\*(C'\fR class like \f(CW\*(C`Config::Model::Backend::Augeas\*(C'\fR .IP "\(bu" 4 A custom class where a read call-back must be provided .PP For more details, see Config::Model::BackendMgr. .PP The name of the backend parameter must be specified in all cases. .SS "Using built-in read mechanism" .IX Subsection "Using built-in read mechanism" \&\f(CW\*(C`Config::Model\*(C'\fR comes with 3 read/write built in mechanisms: .IP "perl_file" 4 .IX Item "perl_file" A perl data structure (like the ones produced by Data::Dumper). See Config::Model::DumpAsData for details. .IP "ini_file" 4 .IX Item "ini_file" Windows \s-1INI\s0 file (note that only simple tree structure can use this backend) .IP "cds_file" 4 .IX Item "cds_file" Config::Model own serialization format (a bit like \s-1YAML\s0). See Config::Model::Dumper for details. .PP With the backend name, the following parameters must be defined: .IP "config_dir" 4 .IX Item "config_dir" The configuration directory .IP "file" 4 .IX Item "file" Config file name (optional). defaults to \f(CW\*(C`.[pl|ini|cds]\*(C'\fR .PP .Vb 4 \& read_config => [ { backend => \*(Aqcds_file\*(Aq , \& config_dir => \*(Aq/etc/cfg_dir\*(Aq, \& file => \*(Aqcfg_file.cds\*(Aq, # optional \& } ], .Ve .PP See \*(L"Built\-in_backend\*(R" in Config::Model::BackendMgr.pm for details .PP Note that these parameters can also be set with the graphical configuration model editor. .SS "Using a plugin read mechanism" .IX Subsection "Using a plugin read mechanism" A plugin backend class can also be specified with: .PP .Vb 3 \& read_config => [ { backend => \*(Aqfoo\*(Aq , \& config_dir => \*(Aq/etc/cfg_dir\*(Aq \& } ] .Ve .PP In this case, Config::Model tries to load \f(CW\*(C`Config::Model::Backend::Foo\*(C'\fR. (The class name is constructed with \f(CW\*(C`ucfirst($backend_name)\*(C'\fR) .PP \&\f(CW\*(C`read_config\*(C'\fR can also have custom parameters that are passed verbatim to \f(CW\*(C`Config::Model::Backend::Foo\*(C'\fR methods: .PP .Vb 4 \& read_config => [ { backend => \*(Aqfoo\*(Aq , \& config_dir => \*(Aq/etc/cfg_dir\*(Aq, \& my_param => \*(Aqmy_value\*(Aq, \& } ] .Ve .PP This \f(CW\*(C`Config::Model::Backend::Foo\*(C'\fR class is expected to provide the following methods: .IP "new" 4 .IX Item "new" .PD 0 .IP "read" 4 .IX Item "read" .IP "write" 4 .IX Item "write" .PD .PP Their signatures are explained in Config::Model::BackendMgr doc on plugin backends .SS "Using a custom class" .IX Subsection "Using a custom class" In case the plugin mechanism is not possible, a class with an arbitrary name can be specified: .PP .Vb 5 \& read_config => [ { backend => \*(Aqcustom\*(Aq , \& class => \*(AqMyRead\*(Aq, \& config_dir => \*(Aq/etc/foo\*(Aq, # optional \& file => \*(Aqfoo.conf\*(Aq, # optional \& } ] .Ve .PP Even the read method can have an arbitrary name by specifying a \&\f(CW\*(C`function\*(C'\fR parameters. .PP For more details on available parameters on custom backends, see Config::Model::BackendMgr doc on custom backends .SS "Using several read mechanisms" .IX Subsection "Using several read mechanisms" Several read mechanism can be specified to enable: .IP "\(bu" 4 Migration from one syntax to another .IP "\(bu" 4 Usage of different libraries (e.g. Augeas or pure Perl backend) .PP For instance, to try Augeas and fall back on a custom class in case of problem, specify: .PP .Vb 12 \& read_config => [ { \& save => \*(Aqbackup\*(Aq, \& file => \*(Aqsshd_config\*(Aq, \& backend => \*(Aqaugeas\*(Aq, \& config_dir => \*(Aq/etc/ssh\*(Aq \& }, \& { \& function => \*(Aqsshd_read\*(Aq, \& backend => \*(Aqcustom\*(Aq, \& class => \*(AqConfig::Model::OpenSsh\*(Aq, \& config_dir => \*(Aq/etc/ssh\*(Aq \& } ], .Ve .PP Both specifications are tried in order. If Augeas backend fails (e.g. Augeas is not installed), the custom backend is used. .PP An exception is raised if both methods fails. This behavior is correct for \f(CW\*(C`OpenSsh\*(C'\fR, but it can be a problem if you want to use Config::Model to create a configuration file from scratch. In this case you should also specify the \f(CW\*(C`auto_create\*(C'\fR parameter: .PP .Vb 6 \& read_config => [ { backend => \*(Aqcustom\*(Aq , \& class => \*(AqProcessRead\*(Aq , \& config_dir => \*(Aq/etc/foo\*(Aq, \& file => \*(Aqfoo.conf\*(Aq, \& auto_create => 1, \& } ], .Ve .SH "Writing configuration files" .IX Header "Writing configuration files" Read and write specifications were designed to be very similar. Most of the times, the \f(CW\*(C`read\*(C'\fR and \f(CW\*(C`write\*(C'\fR specification are identical. In this case, there's no need to enter them: the data specified in the \f(CW\*(C`read\*(C'\fR specification is used to write the configuration file. .PP Here's an example: .PP .Vb 5 \& write_config => [ { backend => \*(Aqcustom\*(Aq, \& class => \*(AqNewFormat\*(Aq \& function => \*(Aqmy_write\*(Aq, \& } \& ], .Ve .PP Several \f(CW\*(C`write\*(C'\fR specification can be used. They are tried in order, until the first succeeds. .PP For more information, see write specification doc .SH "Syntax migration example" .IX Header "Syntax migration example" By combining multiple read specification with \f(CW\*(C`\*(Aqone\*(C'\fR' write specification, a configuration file can be migrated from old to new syntax. The following example migrates a configuration file from a custom syntax to a perl data file: .PP .Vb 10 \& { \& name => \*(AqExample\*(Aq, \& element => [ ... ] , \& read_config => [ { backend => \*(Aqperl_file\*(Aq, \& config_dir => \*(Aq/etc/my_cfg/\*(Aq \& } , \& { backend => \*(Aqcustom\*(Aq, \& class => \*(AqBar\*(Aq \& }, \& ], \& write_config => [ { backend => \*(Aqperl_file\*(Aq, \& config_dir => \*(Aq/etc/my_cfg/\*(Aq \& } \& ], \& } .Ve .PP How does this work ? Here's the sequence: .IP "1." 4 Configuration is stored in old file \f(CW\*(C`/etc/my_cfg/bar.conf\*(C'\fR .IP "2." 4 Config::Model tries to read the config with \f(CW\*(C`perl_file\*(C'\fR read backend and looks for \f(CW\*(C`/etc/my_cfg/example.pl\*(C'\fR. This file is not found so the read fails. .IP "3." 4 Config::Model tries the second backend which succeeds and load configuration data in the configuration tree .IP "4." 4 Config::Model writes data back from configuration tree using \&\f(CW\*(C`write_config\*(C'\fR backend which writes \f(CW\*(C`/etc/my_cfg/example.pl\*(C'\fR .IP "5." 4 At the next invocation, the first \f(CW\*(C`read\*(C'\fR backend will successfully read the perl configuration file. The old file is left alone and can be removed later by the system admin. .PP Thanks to this mechanism, this operation is idempotent so it can safely be scripted in package scriplets. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 More complex models: Config::Model::Manual::ModelCreationAdvanced .IP "\(bu" 4 Config::Model::Manual::ModelForUpgrade: Writing a model for configuration upgrades .IP "\(bu" 4 Configuration upgrades within Debian packages .SH "Feedback welcome" .IX Header "Feedback welcome" Feel free to send comments and suggestion about this page at .PP .Vb 1 \& config\-model\-users at lists dot sourceforge dot net. .Ve .SH "AUTHORS" .IX Header "AUTHORS" Dominique Dumont .SH "AUTHOR" .IX Header "AUTHOR" Dominique Dumont .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2005\-2016 by Dominique Dumont. .PP This is free software, licensed under: .PP .Vb 1 \& The GNU Lesser General Public License, Version 2.1, February 1999 .Ve