Config...Augeas(3pm)

📦 version 0.126, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

💖 Config::Model::Backend::Augeas 💖

okay bestie so this is from the Config...Augeas(3pm) manual, User Contributed Perl Documentation, and it's literally about reading and writing config data through Augeas. slay. let's go ✨

🌸 NAME 🌸

Config::Model::Backend::Augeas — read and write config data through Augeas 💅

✨ SYNOPSIS ✨

no cap, here's the whole vibe:

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

🦋 DESCRIPTION 🦋

so this class gives you a way to load or store configuration data through Config::Augeas. and the iconic part? the structure and the comments of the original configuration file are preserved. periodt 💚

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

  • backend — use "augeas" (or "Augeas") in this case. iykyk 🎀
  • save — either "backup" or "newfile". see "Constructor" in Config::Augeas for the details, bestie, they're all there.
  • file — name of the configuration file. yes, the actual path. 🗂️
  • sequential_lens — okay this one is tricky. set to one when a new Augeas list or hash node must be created for each new list or hash element. see "Sequential lens" for the whole saga below.

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 a list or as a hash. depending on the syntax, Augeas list or hash lenses can be written so that new "container" nodes are required for each new element. it's giving ✨structural✨.

for instance, "HostKey" lines can be repeated several times in "sshd_config". since Augeas must keep track of these several lines, the 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 gets more complex when the syntax allows 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. okay that's a lot, i know 😭

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' trees 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. no skipping, no shuffling, bestie 🫶

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 the Config::Model root class that will hold the configuration data retrieved by Augeas.

💜 Log and trace 💜

this module uses Log::Log4perl to log debug and info trace with "Data::Read" and "Data::Write" categories. very demure, very mindful logging ✨

💀 CAVEATS 💀

  • Augeas "#comment" nodes are ignored. yeah. sorry bestie. 💔

🌟 SEE ALSO 🌟

👑 AUTHOR 👑

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

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.

and that's the whole thing, fr fr 🫶 this page came to you courtesy of perl v5.32.1, dated 2022-01-07, from the Config...Augeas(3pm) manual. go forth and augeas, you absolute icon 💅💖🌈

📦 where this page comes from