Dominique Dumont > Config-Model-Backend-Augeas-0.114 > Config::Model::Backend::Augeas

Download:
Config-Model-Backend-Augeas-0.114.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.114   Source   Latest Release: Config-Model-Backend-Augeas-0.116

NAME ^

Config::Model::Backend::Augeas - Read and write config data through Augeas

SYNOPSIS ^

  # model specification with augeas backend
  {
   config_class_name => 'OpenSsh::Sshd',

   # try Augeas and fall-back with custom method
   read_config  => [ { backend => 'augeas' , 
                       file => '/etc/ssh/sshd_config',
                       # declare "seq" Augeas elements 
                       sequential_lens => [/AcceptEnv AllowGroups [etc]/],
                     },
                     { backend => 'custom' , # dir hardcoded in custom class
                       class => 'Config::Model::Sshd' 
                     }
                   ],
   # write_config will be written using read_config specifications


   element => ...
  }

DESCRIPTION ^

This class provides a way to load or store configuration data through Config::Augeas. This way, the structure and commments of the original configuration file will preserved.

To use Augeas as a backend, you must specify the following read_config parameters:

backend

Use augeas (or Augeas)in this case.

save

Either backup or newfile. See "Constructor" in Config::Augeas for details.

file

Name of the configuration file.

sequential_lens

This one is tricky. Set to one when new Augeas list or hash node must be created for each new list or hash element. See "Sequential lens" for details.

For instance:

   read_config  => [ { backend => 'augeas' , 
                       save   => 'backup',
                       file => '/etc/ssh/sshd_config',
                       # declare "seq" Augeas elements 
                       sequential_lens => [/AcceptEnv AllowGroups/],
                     },
                   ],

Sequential lens

Some configuration files feature data that must be written as list or as hash. Depending on the syntax, Augeas list or hash lenses can be written so that new "container" nodes are required for each new element.

For instance, HostKey lines can be repeated several times in sshd_config. Since Augeas must keep track of these several lines, Augeas tree will be written like:

 /files/etc/ssh/sshd_config/HostKey[1]
 /files/etc/ssh/sshd_config/HostKey[2]
 /files/etc/ssh/sshd_config/HostKey[3]

and not:

 /files/etc/ssh/sshd_config/HostKey/1
 /files/etc/ssh/sshd_config/HostKey/2
 /files/etc/ssh/sshd_config/HostKey/3

The HostKey node is created several times. A new hostkey must be added with the following syntax:

 /files/etc/ssh/sshd_config/HostKey[4]

and not:

 /files/etc/ssh/sshd_config/HostKey/4

So the HostKey lens is sequential.

The situation is more complex when syntax allow repeated values on several lines. Like:

 AcceptEnv LC_PAPER LC_NAME LC_ADDRESS
 AcceptEnv LC_IDENTIFICATION LC_ALL

Augeas will have this tree:

 /files/etc/ssh/sshd_config/AcceptEnv[1]/1
 /files/etc/ssh/sshd_config/AcceptEnv[1]/2
 /files/etc/ssh/sshd_config/AcceptEnv[1]/3
 /files/etc/ssh/sshd_config/AcceptEnv[2]/4
 /files/etc/ssh/sshd_config/AcceptEnv[2]/5

Note that the first index between squarekeeps track of how are grouped the AcceptEnv data, but the real list index is after the slash.

Augeas does not require new elements to create AcceptEnv[3]. A new element can be added as :

 /files/etc/ssh/sshd_config/AcceptEnv[2]/6

So this lens is not sequential.

The same kind of trouble occurs with hash elements. Some hashes tree are like:

 /files/etc/foo/my_hash/my_key1
 /files/etc/foo/my_hash/my_key2

Others are like:

 /files/etc/foo/my_hash[1]/my_key1
 /files/etc/foo/my_hash[2]/my_key2

Note that a list-like index is used with the hash key.

This also depends on the syntax of the configuration file. For instance, Subsystem in sshd_config can be :

 Subsystem   sftp /usr/lib/openssh/sftp-server
 Subsystem   fooftp /usr/lib/openssh/fooftp-server
 Subsystem   barftp /usr/lib/openssh/barftp-server

This (unvalid) sshd configuration is represented by:

 /files/etc/ssh/sshd_config/Subsystem[1]/sftp
 /files/etc/ssh/sshd_config/Subsystem[2]/fooftp
 /files/etc/ssh/sshd_config/Subsystem[3]/barftp

Any new Subsystem must be added with:

 /files/etc/ssh/sshd_config/Subsystem[4]/bazftp

In this case, the hash is also sequential.

For these examples, the augeas backend declaration must feature:

 sequential_lens => [qw/HostKey Subsystem/],

Augeas backend limitation

The structure and element names of the Config::Model tree must match the structure defined in Augeas lenses. I.e. the order of the element declared in Config::Model must match the order required by Augeas lenses.

Sometimes, the structure of a file loaded by Augeas starts directly with a list of items. For instance /etc/hosts structure starts with a list of lines that specify hosts and IP addresses. The set_in parameter specifies an element name in Config::Model root class that will hold the configuration data retrieved by Augeas.

Log and trace ^

This module use Log::Log4perl to log debug and info trace with Data::Read and Data::Write categories.

CAVEATS ^

SEE ALSO ^

AUTHOR ^

Dominique Dumont, <ddumont at cpan dot org@<gt>

COPYRIGHT ^

Copyright (C) 2008-2010 by Dominique Dumont

LICENSE ^

This library is free software; you can redistribute it and/or modify it under the LGPL terms.

syntax highlighting: