An introduction to Augeas, augeasproviders and parts of the augeasproviders project and library.

1. Writing your own
augeasproviders
Dominic Cleal
dcleal@redhat.com
4th February 2014

2. Agenda
●
Intro to Augeas
●
Intro to augeasproviders
●
Delving into augeasproviders
●
●
Core support layer
●
●
Types and providers layer
Test layer
What's next?
augeasproviders | 2 | Dominic Cleal

3. A tree, its branches and leaves
Augeas turns configuration files into a tree structure:
/etc/hosts -> /files/etc/hosts
... and their parameters into branches and leaves:
augtool> print /files/etc/hosts
/files/etc/hosts
/files/etc/hosts/1
/files/etc/hosts/1/ipaddr = "127.0.0.1"
/files/etc/hosts/1/canonical = "localhost"
augeasproviders | 3 | Dominic Cleal

4. Augeas provides many stock parsers
They are called lenses:
Access
Aliases
Anacron
Approx
AptConf
Automaster
Automounter
BackupPCHosts
cgconfig
cgrules
Channels
...
Cron
Crypttab
debctrl
Desktop
Dhcpd
Dpkg
Exports
FAI_DiskConfig
Fonts
Fuse
Grub
Host_Conf
Hostname
Hosts_Access
IniFile
Inputrc
Iptables
Kdump
Keepalived
Keepalived
Login_defs
Mke2fs
$ augtool print /augeas//path | wc -l
813
augeasproviders | 4 | Dominic Cleal

5. augtool lets you inspect the tree
$ augtool
augtool> ls /
augeas/ = (none)
files/ = (none)
augtool> print /files/etc/passwd/root/
/files/etc/passwd/root
/files/etc/passwd/root/password = "x"
/files/etc/passwd/root/uid = "0"
/files/etc/passwd/root/gid = "0"
/files/etc/passwd/root/name = "root"
/files/etc/passwd/root/home = "/root"
/files/etc/passwd/root/shell = "/bin/bash"
augeasproviders | 5 | Dominic Cleal

6. Puppet has a native provider
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",
],
}
$ cat /etc/exports
/foo weeble(ro,all_squash)
augeasproviders | 6 | Dominic Cleal

7. Introducing augeasproviders
kernel_parameter { 'elevator':
ensure => present,
value => 'deadline',
}
shellvar
ensure
target
value
}
{ 'HOSTNAME':
=> present,
=> '/etc/sysconfig/network',
=> 'host.example.com',
sysctl { 'net.ipv4.ip_forward':
ensure => present,
value => '1',
}
augeasproviders | 7 | Dominic Cleal

8. More types (and providers)
●
host, mailalias
●
mounttab (puppetlabs-mount_providers)
●
apache_setenv (and apache_directive to follow)
●
kernel_parameter
●
nrpe_command
●
pg_hba
●
puppet_auth
●
sshd_config, sshd_config_subsystem
●
sysctl
●
syslog
augeasproviders | 8 | Dominic Cleal

9. But Augeas is safe...
class network($hostname) {
file_line { 'set hostname':
ensure => present,
path
=> '/etc/sysconfig/network',
line
=> “HOSTNAME=${hostname}”,
}
}
# puppet apply example.pp
Notice: /Stage[main]/Main/File_line[set
hostname]/ensure: created
# . /etc/sysconfig/network
-bash: bar: command not found
augeasproviders | 9 | Dominic Cleal

10. But Augeas is safe...
class network($hostname) {
shellvar { 'HOSTNAME':
ensure => present,
target => '/etc/sysconfig/network',
value => $hostname,
}
}
# puppet apply example.pp
Error: Could not set 'present' on ensure:
/augeas/files/etc/sysconfig/network/error/path =
/files/etc/sysconfig/network
/augeas/files/etc/sysconfig/network/error/message =
Failed to match
augeasproviders | 10 | Dominic Cleal

11. augeasproviders | 11 | Dominic Cleal

12. Types and providers
●
●
●
●
See last year's talk on replacing “exec” with a type/provider
Nothing fancy here – either building on existing types,
where they're been properly separated, or declaring new
ones
Types all take a “target” parameter for the configuration file
to be edited, but providers have sensible defaults
augeasproviders helps declare getters/setters in providers
with attribute helpers:
●
attr_aug_accessor(:foo)
●
Gives us foo and foo=
augeasproviders | 12 | Dominic Cleal

13. What's in augeasproviders core?
●
Helpers to define information about the file being managed
●
default_file
●
●
lens
●
●
Defines a block for the Augeas lens of the file
resource_path
●
●
Defines a block to get the default file path for this provider
Defines a block for the location in the tree of this resource
Augeas library wrappers
●
augopen, augopen!
●
Helpers to open the Augeas library, save, and close
augeasproviders | 13 | Dominic Cleal

14. augeasproviders | 14 | Dominic Cleal

15. What's in augeasproviders core?
●
Helpers to define methods that use Augeas
●
define_aug_method, define_aug_method!
●
●
Takes a block, which is wrapped in augopen or augopen!
methods to open Augeas
Helpers using the resource_path
●
attr_aug_accessor, attr_aug_reader, attr_aug_writer
●
Much like Ruby's accessor definitions
augeasproviders | 15 | Dominic Cleal

16. augeasproviders | 16 | Dominic Cleal

17. Complete functional tests
●
Don't test the provider, test the resource
●
Start with a set of known-state fixtures
●
Then take a resource and build a catalogue out of it:
shellvar { .. }
●
●
catalogue
.apply
Then let's check the result of the resource apply
But what happens if you run it twice? Verify that a resource
behaves in an idempotent manner
augeasproviders | 17 | Dominic Cleal

18. Verifying test results
●
Much code stolen from rspec-puppet-augeas
●
If you haven't checked it out, and use augeas { }
resources, do so.
augparse_filter(target, "Sysctl.lns", "net.ipv4.ip_forward", '
{ "net.ipv4.ip_forward" = "1" }
')
aug_open(target, "Sysctl.lns") do |aug|
aug.match("#comment[. =~ regexp('kernel.sysrq:.*')]").should == []
aug.match("#comment[. = 'SysRq setting']").should_not == []
end
augeasproviders | 18 | Dominic Cleal

19. What's next?
●
Big split
●
augeasproviders core
●
Do users want packages?
●
Can Puppet reliably handle libs in other modules?
●
●
●
Where to put existing providers?
Resource testing to rspec-puppet or r-p-augeas
Always more providers
augeasproviders | 19 | Dominic Cleal

20. Questions?
http://augeas.net
augeas-devel@redhat.com
freenode: #augeas
augeasproviders | 20 | Dominic Cleal