Trying to use augeas in puppet, which is disgracefully poorly documented. I keep finding "working examples", but no explanations of why they're working, where the syntax came from, what anything means... etc. I'm having trouble fathoming how the authors felt they were in any way helping. >:(
Soo..... I'm figuring it out myself. So, first of all -- part of the augeas magic appears to have to do with the fact that there are predefined lenses for certain configuration files. That means it's not going to behave the same for any file. To dig into the particular file that you're interested in managing, take a look at it with the augtool command:
augtool /files/boot/grub/grub.conf
...okay, there's confusing item #1. the leading "/files" in the path. Yep, that's an augeas thing, that tells augeas that you are looking at something in the filesystem, apparently. You can see what else is in the augeas tree by doing augtool ls /:
[root@whatever etc]# augtool ls /
augeas/ = (none)
files/ = (none)
...but we're getting off track -- back to the task at hand:
root@whatever# augtool /files/boot/grub/grub.conf
#comment[1] = grub.conf generated by anaconda
#comment[2] = Note that you do not have to rerun grub after making changes to this file
#comment[3] = NOTICE: You have a /boot partition. This means that
#comment[4] = all kernel and initrd paths are relative to /boot/, eg.
#comment[5] = root (hd0,0)
#comment[6] = kernel /vmlinuz-version ro root=/dev/mapper/vg_pixie-lv_root
#comment[7] = initrd /initrd-[generic-]version.img
#comment[8] = boot=/dev/sda
default = 0
timeout = 5
splashimage = (hd0,0)/grub/splash.xpm.gz
hiddenmenu = (none)
password/ = $6$1234$abcdefghijklmopqrstuvwxyz
title[1]/ = Red Hat Enterprise Linux Server (2.6.32-642.1.1.el6.x86_64)
title[2]/ = Red Hat Enterprise Linux Server (2.6.32-504.30.3.el6.x86_64)
title[3]/ = Red Hat Enterprise Linux 6 (2.6.32-504.el6.x86_64)
So, augeas defines the configuration settings in the form of a tree with nodes branches of the tree start with the filesystem (/files), continue with subdirectories (/boot/grub), continue with the filename (grub.conf), and further continue with the settings inside the file (password, timeout, default, title, etc.) The lens magic comes in here -- it makes augeas smart enough to parse the stanzas in the file itself, so the tree nodes break out sanely. We can descend into a title stanza, which details different operating systems or kernel revisions to boot, and into individual settings. Note that nodes into which you can further descend are displayed with a trailing slash:
[root@whatever]# augtool ls /files/boot/grub/grub.conf/title[1]
root = (hd0,0)
kernel/ = /vmlinuz-2.6.32-642.1.1.el6.x86_64
initrd = /initramfs-2.6.32-642.1.1.el6.x86_64.img
So we can see what's in the kernel settings within title[1] thusly:
[root@pixie etc]# augtool ls /files/boot/grub/grub.conf/title[1]/kernel
ro = (none)
root = /dev/mapper/vg_pixie-lv_root
rd_LVM_LV[1] = vg_pixie/lv_swap
rd_NO_LUKS = (none)
LANG = en_US.UTF-8
rd_NO_MD = (none)
rd_LVM_LV[2] = vg_pixie/lv_root
SYSFONT = latarcyrheb-sun16
crashkernel = 128M
KEYBOARDTYPE = pc
KEYTABLE = us
rd_NO_DM = (none)
rhgb = (none)
quiet = (none)
Right, so in this example, we are trying to do a couple of things:
1. Set the audit flag on the kernel line
2. Remove the rhgb flag from the kernel lines
3. Remove the quiet flag from the kernel lines
4. Make sure we have the password properly set.
So it now follows that we need to modify:
/files/boot/grub/grub.conf/title[1]/kernel/rhgb
/files/boot/grub/grub.conf/title[1]/kernel/quiet
/files/boot/grub/grub.conf/title[1]/kernel/audit
/files/boot/grub/grub.conf/password
That wasn't so bad. You'd think someone could write it down. *cough*
Okay, so how to make these changes? See the man page for augtool(1) to see the assorted options available.
Using augtool directly, we can simply remove the existence of rhgb and quiet. Note the asterisk '*' used to match all title lines:
augtool rm /files/boot/grub/grub.conf/title[*]/kernel/rhgb
augtool rm /files/boot/grub/grub.conf/title[*]/kernel/quiet
To add audit=1, we need to set a new key and value pair under each title:
augtool setm /files/boot/grub/grub.conf/title[*]/kernel/ audit 1
The setm is a "set multiple" or "set matching", which applies the set to multiple lines matching the given expression, so we can use the asterisk wildcard again.
The equivalent expressions within puppet are:
Honestly, the dependency on proper lenses existing and navigating the trees makes me wonder if there is value to this tool for simple changes that sed or awk or other simple shell or perl scripts can handle more easily, and are far easier for a fellow admin to comprehend.
Cases where I see the value are managing arbitrary values in grub.conf, managing entries in /etc/hosts (we have a particular environment where different machines have wildly different hosts aliased to a particular name for a variety of reasons, so tweaking that particular alias in different places is useful).
References
http://augeas.net
https://docs.puppet.com/guides/augeas.html
http://xmodulo.com/manage-configurations-linux-puppet-augeas.html
http://www.moeding.net/archives/61-Quoted-Shellvars-in-Augeas.html
http://www.watzmann.net/categories/augeas.html
http://projects.puppetlabs.com/projects/1/wiki/puppet_augeas
http://www.ghostar.org/2014/07/using-augeas-and-puppet-to-modify-grub-conf/