Puppet

# Using Puppet with Augeas

[Augeas](http://augeas.net/index.html) is a lovely tool that treats

config files (well, anything really, but it's mostly about config

files) as trees of values. You then modify the tree as you like,

and write the file back.

This is basically the solution to the problem of dealing with

upstream configuration changes combined with local modifications:

you can allow the upstream changes through and then apply changes

with Augeas to the new version.

Assuming you want to work with Augeas, this is a description of how

to perform Augeas changes using Puppet. You'll need Puppet >=

0.24.7 for this. The basic usage is [Type Reference](http://docs.reductivelabs.com/references/latest/type.html#augeas).

The somewhat more important, and unfortunately complicated, part is

figuring out what the tree for a file looks like so you can

manipulate it properly. The definition that Augeas uses to turn a

file into a tree is called a lens, and understanding the trees is

more difficult than it should be, because many lenses are not

documented sufficiently, or at all. The documentation for those

that are

[has its own surprisingly hard to find page](http://augeas.net/docs/references/lenses/index.html)

on the Augeas site. You can see what lenses are available by

looking in /usr/share/augeas/lenses/ (or

/usr/local/share/augeas/lenses/ , or possibly somewhere else,

depending on your setup).

You can also see which files Augeas has successfully parsed by

entering "ls /files/" in augtool and drilling down from there. If a

file hasn't been properly parsed by Augeas, it simply won't show

up. This could mean that the file has a syntax error, or it could

imply a failure in the lense itself.

Here's an example of how to determine the tree structure of a file,

in this case /etc/exports.

The easiest thing to do is to set up the file with some examples (I

pulled examples from the bottom of "man 5 exports") and see what

they look like:

    $ augtool

    augtool> ls /files/etc/exports/

    comment[1] = /etc/exports: the access control list for filesystems which may be exported

    comment[2] = to NFS clients.  See exports(5).

    comment[3] = sample /etc/exports file

    dir[1]/ = /

    dir[2]/ = /projects

    dir[3]/ = /usr

    dir[4]/ = /home/joe

From here you can investigate the structure, like so:

    augtool> ls /files/etc/exports/dir[1]

    client[1]/ = master

    client[2]/ = trusty

The corresponding line in the file is:

    /               master(rw) trusty(rw,no_root_squash)

Digging further:

    augtool> ls /files/etc/exports/dir[1]/client[1]

    option = rw

So, if you want to add a new entry, you'd do something like this:

    augtool> set /files/etc/exports/dir[last()+1] /foo

    augtool> set /files/etc/exports/dir[last()]/client weeble

    augtool> set /files/etc/exports/dir[last()]/client/option[1] ro

    augtool> set /files/etc/exports/dir[last()]/client/option[2] all_squash

    augtool> save

    Saved 1 file(s)

Which creates the line:

    /foo weeble(ro,all_squash)

Now that you've played around in augtool, you can make changes

using Puppet:

    augeas{ "export foo" :

        context => "/files/etc/exports",

        changes => [

            "set dir[last()+1] /foo",

            "set dir[last()]/client weeble",

            "set dir[last()]/client/option[1] ro",

            "set dir[last()]/client/option[2] all_squash",

        ],

    }

This adds the line described above.

**For information on quotes and spaces, see** http://groups.google.com/group/puppet-users/browse_thread/thread/b4730f74589433e5

# Working Examples

test it like this:

    sudo puppet apply --verbose --debug --trace --summarize test.pp

## /etc/sysctl.conf

works on puppet 2.6.1; fedora 12; ubuntu 10.04

    class sysctl {

      # nested class/define

      define conf ( $value ) {

        # $name is provided by define invocation

        # guid of this entry

        $key = $name

        $context = "/files/etc/sysctl.conf"

         augeas { "sysctl_conf/$key":

           context => "$context",

           onlyif  => "get $key != $value",

           changes => "set $key $value",

           notify  => Exec["sysctl"],

         }

      } 

       file { "sysctl_conf":

          name => $operatingsystem ? {

            default => "/etc/sysctl.conf",

          },

       }

       exec { "sysctl -p":

          alias => "sysctl",

          refreshonly => true,

          subscribe => File["sysctl_conf"],

       }

    }

use case:

    include sysctl

    sysctl::conf { 

      # prevent java heap swap

      "vm.swappiness": value =>  0;

      # increase max read/write buffer size that can be applied via setsockopt()

      "net.core.rmem_max": value =>  16777216;

      "net.core.wmem_max": value =>  16777216;

    }

## /etc/security/limits.conf

works on puppet 2.6.1; fedora 12; ubuntu 10.04

    class limits {

      # nested class/define

      define conf (

        $domain = "root",

        $type = "soft",

        $item = "nofile",

        $value = "10000"

        ) {

          # guid of this entry

          $key = "$domain/$type/$item"

          # augtool> match /files/etc/security/limits.conf/domain[.="root"][./type="hard" and ./item="nofile" and ./value="10000"]

          $context = "/files/etc/security/limits.conf"

          $path_list  = "domain[.=\"$domain\"][./type=\"$type\" and ./item=\"$item\"]"

          $path_exact = "domain[.=\"$domain\"][./type=\"$type\" and ./item=\"$item\" and ./value=\"$value\"]"

          # TODO add duplicate entry cleanup

          augeas { "limits_conf/$key":

             context => "$context",

             onlyif  => "match $path_exact size==0",

             changes => [

               # remove all matching to the $domain, $type, $item, for any $value

               "rm $path_list", 

               # insert new node at the end of tree

               "set domain[last()+1] $domain",

               # assign values to the new node

               "set domain[last()]/type $type",

               "set domain[last()]/item $item",

               "set domain[last()]/value $value",

             ],

           }

      } 

    }

use case:

    include limits

    limits::conf { 

      # maximum number of open files/sockets for root

      "root-soft": domain => root, type => soft, item => nofile, value =>  9999;

      "root-hard": domain => root, type => hard, item => nofile, value =>  9999;

    }