Using Augeas to reliably edit config files

Sometimes it seems like every application has its own subtly different config file format, and writing regular expressions to parse and modify all of them can be a tiresome business.

Thankfully, Augeas is here to help. Augeas is a system that aims to simplify working with different config file formats by presenting them all as a simple tree of values. Puppet's Augeas support allows you to create augeas resources that can make the required config changes intelligently and automatically.

How to do it…

Follow these steps to create an example augeas resource:

1. Modify your base module as follows:

     class base {
       augeas { 'enable-ip-forwarding':
         incl    => '/etc/sysctl.conf',
         lens    => 'Sysctl.lns',
         changes => ['set net.ipv4.ip_forward 1'],
       }
     }

2. Run Puppet:

   [root@cookbook ~]# puppet agent -t
   Info: Applying configuration version '1412130479'
   Notice: Augeas[enable-ip-forwarding](provider=augeas): 
   --- /etc/sysctl.conf 2014-09-04 03:41:09.000000000 -0400
   +++ /etc/sysctl.conf.augnew 2014-09-30 22:28:03.503000039 -0400
   @@ -4,7 +4,7 @@
    # sysctl.conf(5) for more details.
    
    # Controls IP packet forwarding
   -net.ipv4.ip_forward = 0
   +net.ipv4.ip_forward = 1
    
    # Controls source route verification
    net.ipv4.conf.default.rp_filter = 1
   Notice: /Stage[main]/Base/Augeas[enable-ip-forwarding]/returns: executed successfully
   Notice: Finished catalog run in 2.27 seconds
   

3. Check whether the setting has been correctly applied:

   [root@cookbook ~]# sysctl -p |grep ip_forward
   net.ipv4.ip_forward = 1
   

How it works…

We declare an augeas resource named enable-ip-forwarding:

augeas { 'enable-ip-forwarding':

We specify that we want to make changes in the file /etc/sysctl.conf:

incl => '/etc/sysctl.conf',

Next we specify the lens to use on this file. Augeas uses files called lenses to translate a configuration file into an object representation. Augeas ships with several lenses, they are located in /usr/share/augeas/lenses by default. When specifying the lens in an augeas resource, the name of the lens is capitalized and has the .lns suffix. In this case, we will specify the Sysctl lens as follows:

lens => 'Sysctl.lns',

The changes parameter specifies the changes we want to make. Its value is an array, because we can supply several changes at once. In this example, there is only change, so the value is an array of one element:

changes => ['set net.ipv4.ip_forward 1'],

In general, Augeas changes take the following form:

set <parameter> <value>

In this case, the setting will be translated into a line like this in /etc/sysctl.conf:

net.ipv4.ip_forward=1

There's more…

I've chosen /etc/sysctl.conf as the example because it can contain a wide variety of kernel settings and you may want to change these settings for all sorts of different purposes and in different Puppet classes. You might want to enable IP forwarding, as in the example, for a router class but you might also want to tune the value of net.core.somaxconn for a load-balancer class.

This means that simply puppetizing the /etc/sysctl.conf file and distributing it as a text file won't work because you might have several different and conflicting versions depending on the setting you want to modify. Augeas is the right solution here because you can define augeas resources in different places, which modify the same file and they won't conflict.

For more information about using Puppet and Augeas, see the page on the Puppet Labs website http://projects.puppetlabs.com/projects/1/wiki/Puppet_Augeas.

Another project that uses Augeas is Augeasproviders. Augeasproviders uses Augeas to define several types. One of these types is sysctl, using this type you can make sysctl changes without knowing how to write the changes in Augeas. More information is available on the forge at https://forge.puppetlabs.com/domcleal/augeasproviders.

Learning how to use Augeas can be a little confusing at first. Augeas provides a command line tool, augtool, which can be used to get acquainted with making changes in Augeas.