view release on metacpan or  search on metacpan

lib/Config/Model/Backend/Augeas.pm  view on Meta::CPAN

package Config::Model::Backend::Augeas;
use Mouse;
use Carp;
use Log::Log4perl qw(get_logger :levels);

extends 'Config::Model::Backend::Any';
with "Config::Model::Role::FileHandler";

use Config::Model::Exception;

use File::Path;
use Log::Log4perl qw(get_logger :levels);

my $has_augeas = 1;
eval { require Config::Augeas; };
$has_augeas = 0 if $@;

our $VERSION = '0.126';

my $logger = get_logger('Backend::Augeas');

=head1 NAME

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

=head1 SYNOPSIS

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

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

   # config is written back using read_config specifications

   element => ...
  }

=head1 DESCRIPTION

This class provides a way to load or store configuration data through
L<Config::Augeas>. This way, the structure and comments of the
original configuration file are preserved.

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

=over

=item backend

Use C<augeas> (or C<Augeas>)in this case.

=item save

Either C<backup> or C<newfile>. See L<Config::Augeas/Constructor> for
details.

=item file

Name of the configuration file.

=item 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 L</Sequential lens>
for details.

=back

For instance:

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

=head2 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, C<HostKey> lines can be repeated several times in
C<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 C<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 C<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 square brackets keeps track of how
the C<AcceptEnv> items are grouped, but the I<real> list index is
after the slash.

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

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

So this lens is not sequential.