VERSION
version 1.205SYNOPSIS
# top level config file name matches instance name
$model->create_config_class
(
name => 'OneAutoReadConfigClass',
read_config => [ { backend => 'cds_file' , config_dir => '/etc/cfg_dir'},
{ backend => 'custom' ,
class => 'ProcessRead' ,
config_dir => '/etc/foo', # optional
file => 'foo.conf', # optional
auto_create => 1, # optional
}
],
# if omitted, write_config will be written using read_config specifications
# write_config can be array of hash ref to write several syntaxes
write_config => { backend => 'cds_file', config_dir => '/etc/cfg_dir' } ,
element => ...
) ;
# config data will be written in /etc/my_config_dir/foo.cds
# according to the instance name
my $instance = $model->instance(instance_name => 'foo') ;
DESCRIPTION
This class provides a way to specify how to load or store configuration data within the model (instead of writing dedicated perl code).With these specifications, all the configuration information is read during creation of a node.
This load/store can be done with different "backend":
- cds_file
- Config dump string (cds) in a file. I.e. a string that describes the content of a configuration tree is loaded from or saved in a text file. See Config::Model::Dumper.
- ini_file
- Ini files (written with Config::Tiny. See limitations in ``Limitations depending on storage''.
- perl_file
- Perl data structure (perl) in a file. See Config::Model::DumpAsData for details on the data structure.
- custom
- Any format when the user provides a dedicated class and function to read and load the configuration tree.
- augeas
- Data can be loaded or stored using RedHat's Augeas library. See Config::Model::Backend::Augeas for details.
After loading the data, the object registers itself to the instance. Then the user can call the "write_back" method on the instance (See Config::Model::Instance) to store all configuration information back.
Built-in backend
"cds_file", "ini_file" and "perl_file" backend must be specified with mandatory "config_dir" parameter. For instance:
read_config => { backend => 'cds_file' , config_dir => '/etc/cfg_dir', file => 'cfg_file.cds', #optional },
If "file" is not specified, a file name will be constructed with "<config_class_name>.<suffix>" where suffix is "pl" or "ini" or "cds".
Plugin backend classes
A plugin backend class can also be specified with:
read_config => [ { backend => 'foo' , config_dir => '/etc/cfg_dir' file => 'foo.conf', # optional } ]
In this case, this class 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
-
with parameters:
node => ref_to_config_model_node
"new()" must return the newly created object
- read
-
with parameters:
%custom_parameters, # model data root => $root_dir, # mostly used for tests config_dir => $read_dir, # path below root file_path => $full_name, # full file name (root+path+file) io_handle => $io_file # IO::File object
Must return 1 if the read was successful, 0 otherwise.
Following the "my_param" example above, %custom_parameters will contain " ( 'my_param' , 'my_value' ) ", so "read()" will also be called with "root", "config_dir", "file_path", "io_handle" and "my_param => 'my_value'".
- write
-
with parameters:
%$write, # model data auto_create => $auto_create, # from model backend => $backend, # backend name config_dir => $write_dir, # override from instance io_handle => $fh, # IO::File object write => 1, # always root => $root_dir,
Must return 1 if the write was successful, 0 otherwise
Custom backend
Custom backend must be specified with a class name that will features the methods used to write and read the configuration files:
read_config => [ { backend => 'custom' , class => 'MyRead', config_dir => '/etc/foo', # optional file => 'foo.conf', # optional } ]
"custom" backend parameters are:
- class
- Specify the class that contain the read method
- config_dir
- Specify configuration directory. This parameter is optional as the directory can be hardcoded in the custom class.
- file
- optional. This parameter may not apply if the configuration is stored in several files. By default, the instance name is used as configuration file name.
- function
- Function name that will be called back to read the file. See ``read callback'' for details. (default is "read")
- auto_create
-
By default, an exception is thrown if no read was
successfull. This behavior can be overridden by specifying
"auto_create => 1" in one of the backend specification. For instance:
read_config => [ { backend => 'cds_file', config_dir => '/etc/my_cfg/' } , { backend => 'custom', class => 'Bar' , auto_create => 1 }, ],
This feature is necessary to create a configuration from scratch
When set in write backend, missing directory and files will be created with current umask. Default is false.
Write specification is similar to read_specification. Except that the default value for "function" is "write". Here's an example:
write_config => [ { backend => 'cds_file', config_dir => '/etc/my_cfg/' } , { backend => 'custom', class => 'Bar' , function => 'my_write', }, ],
Limitations depending on storage
Some storage system will limit the structure of the model you can map to the file.Ini files limitation
Structure of the Config::Model must be very simple. Either:- A single class with hash of leaves elements.
- 2 levels of classes. The top level has nodes elements. All other classes have only leaf elements.
Configuration class with auto read or auto write
read specification
A configuration class will be declared with optional "read_config" parameter:
read_config => [ { backend => 'cds_file', config_dir => '/etc/my_cfg/' } , { backend => 'custom', class => 'Bar' }, ],
The read backends will be tried in the specified order:
- First the cds file whose name depend on the parameters used in model creation and instance creation: "<model_config_dir>/<instance_name>.cds" The syntax of the "cds" file is described in Config::Model::Dumper.
- A callback to "Bar::read". See "``read callback'' for details.
When a read operation is successful, the remaining read methods will be skipped.
write specification
A configuration class will be declared with optional "write_config" parameters (along with "read_config" parameter):
write_config => [ { backend => 'cds_file', config_dir => '/etc/my_cfg/', auto_create => 1, }, { backend => 'custom', class => 'NewFormat' } ],
By default, the specifications are tried in order, until the first succeeds.
When required by the user, all configuration information is written back using all the write specifications. See ``write_back ( ... )'' in Config::Model::Instance for details.
The write class declared witn "custom" backend must provide a call-back. See ``write callback'' for details.
read write directory
By default, configurations files are read from the directory specified by "config_dir" parameter specified in the model. You may override the "root" directory for test.read callback
Read callback function will be called with these parameters:
object => $obj, # Config::Model::Node object root => './my_test', # fake root directory, userd for tests config_dir => /etc/foo', # absolute path file => 'foo.conf', # file name file_path => './my_test/etc/foo/foo.conf' io_handle => $io # IO::File object
The IO::File object is undef if the file cannot be read.
The callback must return 0 on failure and 1 on succesfull read.
write callback
Write callback function will be called with these parameters:
object => $obj, # Config::Model::Node object root => './my_test', # fake root directory, userd for tests config_dir => /etc/foo', # absolute path file => 'foo.conf', # file name file_path => './my_test/etc/foo/foo.conf' io_handle => $io # IO::File object opened in write mode auto_create => 1 # create dir as needed
The IO::File object is undef if the file cannot be written to.
The callback must return 0 on failure and 1 on succesfull write.
CAVEATS
When both "config_dir" and "file" are specified, this class will write-open the configuration file (and thus clobber it) before calling the "write" call-back and pass the file handle with "io_handle" parameter. "write" should use this handle to write data in the target configuration file.If this behavior causes problem (e.g. with augeas backend), the solution is to:
- Skip either "file" or "config_dir" parameter in the "write_config" specification.
- Create a "skip_open" function in your backend class that returns 1
EXAMPLES
In the example below, only a "cds" file is written. But, both custom format and "cds" file are tried for read. This is also an example of a graceful migration from a customized format to a "cds" format.
read_config => [ { backend => 'cds_file', config_dir => '/etc/my_cfg/' } , { backend => 'custom', class => 'Bar' }, ], write_config => [{ backend => 'cds_file', config_dir => '/etc/my_cfg/' }],
You can choose also to read and write only customized files:
read_config => [{ backend => 'custom', class => 'Bar'}],
Or to read and write only cds files :
read_config => [{ backend => 'cds_file'}] ,
You can also specify more parameters that must be passed to your custom class:
read_config => [{ backend => 'custom', class => 'Bar', config_dir => '/etc/foo'}],
To migrate from an old format to a new format:
read_config => [ { backend => 'custom', class => 'OldFormat', function => 'old_read' } , { backend => 'custom', class => 'NewFormat', function => 'new_read' } ], write_config => [ { backend => 'custom', class => 'NewFormat' } ],
If "write_config" is missing, the data provided by "read_config" will be used. For instance:
read_config => [ { backend => 'custom', class => 'Bar', config_dir => '/etc/foo' } ],
In this case, configuration data will be read by "Bar::read" in directory "/etc/foo" and will be written back there by "Bar::write".