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

Author

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

Caveats

       •   Augeas "#comment" nodes are ignored

Copyright

       Copyright (C) 2008-2010 by Dominique Dumont

Description

       This class provides a way to load or store configuration data through 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 "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/],
           },

   Sequentiallens
       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 square brackets keeps track of how the "AcceptEnv" items  are  grouped,
       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/],

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

License

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

perl v5.32.1                                       2022-01-07                Config::Model::Backend::Augeas(3pm)

Log And Trace

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

Name

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

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 => ...
         }