Docu review done: Wed 31 Jul 2024 02:06:52 PM CEST

Augeas

Table of Content

Description

Full online documentation

augeas is a configuration editing tool. It parses configuration files in there native formats and transform them into a tree. Configuration changes are made by manipulating this tree and saving it back to native config files.

augeas uses lenses to detect the language of a configuration file. The default lenses can be found /usr/share/augeas/lenses//usr/share/augeas/lenses/dist or you have a look at the online documentation stock lenses.

augeas official homepage has a small quick tour which also gives you same samples and useful information.

Installation

If you are running debian, you can simply install it with apt

$ apt install augeas-tools

Of course you can install it via several other methods as well, this link will bring you to the download page of augeas.

And if you have puppet installed on your system, you could even use it to perform commands with augeas without installing any additional package. All what you need is to add the module augeas_core and call the class according to your needs.

The augeas-tools package installs three tools for you:

  • augmatch: inspect and match contents of configuration files
  • augparse: execute auges module
  • augtool: full control of augeas

augmatch

augmatch prints the tree that augeas generates by parsing a configuration file, or only those parts of the tree that match a certain path expression. Parsing is controlled by lenses, many of which ship with augeas. augmatch to select the correct lens for a given file automatically unless one is specified with the --lens option.

augmatch Parameters

ParametersDescription
[-e/--exact]Only print the parts of the tree that exactly match the expression provided with --match and not any of the descendants of matching nodes
[-L/--print-lens]Print the name of the lens that will be used with the given file and exit
[-m/--match] <expr>Only print the parts of the tree that match the path expression expr. All nodes that match expr and their descendants will be printed
[-o/--only-value]Only print the value
[-q/--quiet]Do not print anything. Exit with zero status if a match was found

augparse

Execute an augeas module, most commonly to evaluate the tests it contains during the development of new lenses/modules.

augtool

augeas is a configuration editing tool. It parses configuration files in their native formats and transforms them into a tree. Configuration changes are made by manipulating this tree and saving it back into native config files.

augtool provides a command line interface to the generated tree. COMMAND can be a single command as described under augtool Commands. When called with no COMMAND, it reads commands from standard input until an end-of-file is encountered.

augtool Commands

This is a small list of available regular used commands:

Admin commands

CommandDescription
helpshows help ;)
saveSave all pending changes to disk. Unless either the -b or -n command line options are given, files are changed in place

Read commands

CommandDescription
ls <path>list direct child’s of path
match <path pattern> [value]lists paths which matches path pattern allows value filter
print <path>prints all childes of path, if no path given, it prints all system wide paths

Write commands

CommandDescription
rm <path>deletes path and all its children from the tree
set <path> <value>sets the value in path, if the path is not in the tree yet, it and all its ancestors will be created
touch <path>creates path with null value in tree

Samples

augtool match

This will find all paths that match the path pattern and if you add a value it will filter the result with this as well.

$ augtool match "/files/etc/ssh/sshd_config/*/" yes
/files/etc/ssh/sshd_config/PubkeyAuthentication
/files/etc/ssh/sshd_config/UsePAM
/files/etc/ssh/sshd_config/PrintLastLog
/files/etc/ssh/sshd_config/TCPKeepAlive

augtool print

Use the print command to list all paths and values which matches a path pattern:

$ augtool print "/files/etc/sudoers/spec[1]/host_group/command"
/files/etc/sudoers/spec[1]/host_group/command = "ALL"
/files/etc/sudoers/spec[1]/host_group/command/runas_user = "ALL"
/files/etc/sudoers/spec[1]/host_group/command/runas_group = "ALL"

augtool last value or item

If you don’t know how long a array is, you can use for example the internal command last() to operate on the last value or item

$ augtool print "/files/etc/hosts/*/alias[last()]"
/files/etc/hosts/1/alias = "local_dude"
/files/etc/hosts/2/alias = "my_second_dude"
/files/etc/hosts/3/alias = "my_third_dude"

augtool set

To modify values, you use the command set followed by the path and the new value. If the path does not exists, it will be generated.

$ augtool set "/files/etc/puppetlabs/puppetserver/conf.d/puppetserver.conf/@hash[. = 'http-client']/@array[. = 'ssl-protocols']/1" "TLSv1.3"

puppet augeas

As I have mentioned at the top of the documentation, you can control augeas with puppet as well, this will do the same as the above set sample

augeas { 'puppetserver.conf_augeas_tls':
  context => '/files/etc/puppetlabs/puppetserver/conf.d/puppetserver.conf',
  changes => [
    "set @hash[. = 'http-client']/@array[1] 'ssl-protocols'",
    "set @hash[. = 'http-client']/@array/1 'TLSv1.3'",
  ],
  notify  => Service['puppetserver'],
}
augeas { "sshd_config":
  changes => [ "set /files/etc/ssh/sshd_config/PermitRootLogin no", ],
}
augeas { "sshd_config":
  context => "/files/etc/ssh/sshd_config",
  changes => [ "set PermitRootLogin no", ],
augeas { "export foo":
  context => "/files/etc/exports",
  changes => [
    "set dir[. = '/foo'] /foo",
    "set dir[. = '/foo']/client weeble",
    "set dir[. = '/foo']/client/option[1] ro",
    "set dir[. = '/foo']/client/option[2] all_squash",
  ],
}

PA paths for numbered items

augeas { "localhost":
  context => "/files/etc/hosts",
  changes => [
    "set *[ipaddr = '127.0.0.1']/canonical localhost",
    "set *[ipaddr = '127.0.0.1']/alias[1] $hostname",
    "set *[ipaddr = '127.0.0.1']/alias[2] $hostname.domain.com",
  ],
}
augeas { "sudojoe":
  context => "/files/etc/sudoers",
  changes => [
    "set spec[user = 'joe']/user joe",
    "set spec[user = 'joe']/host_group/host ALL",
    "set spec[user = 'joe']/host_group/command ALL",
    "set spec[user = 'joe']/host_group/command/runas_user ALL",
  ],
}

PA loading generic lense for non standard files

augeas { "sudoers":
  lens    => "Sudoers.lns",
  incl    => "/foo/sudoers",
  changes => "...",
}