# salt.states.augeas

Configuration management using Augeas

New in version 0.17.0.

This state requires the `augeas` Python module.

Augeas can be used to manage configuration files.

Warning

Minimal installations of Debian and Ubuntu have been seen to have packaging bugs with python-augeas, causing the augeas module to fail to import. If the minion has the augeas module installed, and the state fails with a comment saying that the state is unavailable, first restart the salt-minion service. If the problem persists past that, the following command can be run from the master to determine what is causing the import to fail:

    salt minion-id cmd.run 'python -c "from augeas import Augeas"'

For affected Debian/Ubuntu hosts, installing `libpython2.7` has been known to resolve the issue.

salt.states.augeas.change(name, context=None, changes=None, lens=None, load_path=None, **kwargs)

  New in version 2014.7.0.

  This state replaces `setvalue()`.

  Issue changes to Augeas, optionally for a specific context, with a specific lens.

  name

    State name

  context

    A file path, prefixed by `/files`. Should resolve to an actual file (not an arbitrary augeas path). This is used to avoid duplicating the file name for each item in the changes list (for example, `set bind 0.0.0.0` in the example below operates on the file specified by `context`). If `context` is not specified, a file path prefixed by `/files` should be included with the `set` command.

    The file path is examined to determine if the specified changes are already present.

        redis-conf:
          augeas.change:
            - context: /files/etc/redis/redis.conf
            - changes:
              - set bind 0.0.0.0
              - set maxmemory 1G

  changes

    List of changes that are issued to Augeas. Available commands are `set`, `setm`, `mv`/`move`, `ins`/`insert`, and `rm`/`remove`.

  lens

    The lens to use, needs to be suffixed with .lns, e.g.: Nginx.lns. See the list of stock lenses shipped with Augeas.

  New in version 2016.3.0.

  load_path

    A list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB.

  Usage examples:

  Set the `bind` parameter in `/etc/redis/redis.conf`:

      redis-conf:
        augeas.change:
          - changes:
            - set /files/etc/redis/redis.conf/bind 0.0.0.0

  Note

  Use the `context` parameter to specify the file you want to manipulate. This way you don't have to include this in the changes every time:

      redis-conf:
        augeas.change:
          - context: /files/etc/redis/redis.conf
          - changes:
            - set bind 0.0.0.0
            - set databases 4
            - set maxmemory 1G

  Augeas is aware of a lot of common configuration files and their syntax. It knows the difference between for example ini and yaml files, but also files with very specific syntax, like the hosts file. This is done with lenses, which provide mappings between the Augeas tree and the file.

  There are many preconfigured lenses that come with Augeas by default, and they specify the common locations for configuration files. So most of the time Augeas will know how to manipulate a file. In the event that you need to manipulate a file that Augeas doesn't know about, you can specify the lens to use like this:

      redis-conf:
        augeas.change:
          - lens: redis.lns
          - context: /files/etc/redis/redis.conf
          - changes:
            - set bind 0.0.0.0

  Note

  Even though Augeas knows that `/etc/redis/redis.conf` is a Redis configuration file and knows how to parse it, it is recommended to specify the lens anyway. This is because by default, Augeas loads all known lenses and their associated file paths. All these files are parsed when Augeas is loaded, which can take some time. When specifying a lens, Augeas is loaded with only that lens, which speeds things up quite a bit.

  A more complex example, this adds an entry to the services file for Zabbix, and removes an obsolete service:

      zabbix-service:
        augeas.change:
          - lens: services.lns
          - context: /files/etc/services
          - changes:
            - ins service-name after service-name[last()]
            - set service-name[last()] "zabbix-agent"
            - set "service-name[. = 'zabbix-agent']/port" 10050
            - set "service-name[. = 'zabbix-agent']/protocol" tcp
            - set "service-name[. = 'zabbix-agent']/#comment" "Zabbix Agent service"
            - rm "service-name[. = 'im-obsolete']"
          - unless: grep "zabbix-agent" /etc/services

  Warning

  Don't forget the `unless` here, otherwise it will fail on next runs because the service is already defined. Additionally you have to quote lines containing `service-name[. = 'zabbix-agent']` otherwise `augeas_cfg` execute will fail because it will receive more parameters than expected.

  Note

  Order is important when defining a service with Augeas, in this case it's `port`, `protocol` and `#comment`. For more info about the lens check services lens documentation.

  http://augeas.net/docs/references/lenses/files/services-aug.html#Services.record