Augeas

The Augeas tool provides a way to use Augeas to edit files that may not be completely managed.

In the simplest case, you simply tell Augeas which path to edit, and give it a sequence of commands:

<Path type="augeas" name="/etc/hosts" owner="root" group="root"
      mode="0644">
  <Set path="01/ipaddr" value="192.168.0.1"/>
  <Set path="01/canonical" value="pigiron.example.com"/>
  <Set path="01/alias[1]" value="pigiron"/>
  <Set path="01/alias[2]" value="piggy"/>
</Path>

The commands are run in document order. There’s no need to do an explicit save at the end.

These commands will be run if any of the paths do not already have the given setting. In other words, if any command has not already been run, they will all be run.

So, if the first host already has all of the specified settings, then that Path will verify successfully and nothing will be changed. But suppose the first host looks like this:

192.168.0.1 pigiron.example.com pigiron

All that is missing is the second alias, piggy. The entire Augeas script will be run in this case. It’s important, then, to ensure that all commands you use are idempotent. (For instance, the Move and Insert commands are unlikely to be useful.)

The Augeas paths are all relative to /files/etc/hosts.

The Augeas tool understands a subset of augtool commands. Valid tags are: Remove, Move, Set, Clear, SetMulti, and Insert. Refer to the official Augeas docs or the Schema below for details on the commands.

The Augeas tool also supports one additional directive, Initial, for setting initial file content when a file does not exist. For instance, the Xml lens fails to parse a file that does not exist, and, as a result, you cannot add content to it. You can use Initial to circumvent this issue:

<Path type="augeas" name="/etc/test.xml" lens="Xml"
      owner="root" group="root" mode="0640">
  <Initial>&lt;Test/&gt;</Initial>
  <Set path="Test/#text" value="text content"/>
</Path>

Editing files outside the default load path

If you’re using Augeas to edit files outside of its default load path, you must manually specify the lens. For instance:

<Path type="augeas" name="/opt/jenkins/home/config.xml" lens="Xml"
      owner="jenkins" group="jenkins" mode="0640">
  <Set path="hudson/systemMessage/#text"
       value="This is a Jenkins server."/>
</Path>

Note that there’s no need to manually modify the load path by setting /augeas/load/<lens>/incl, nor do you have to call load explicitly.

Schema

group augeasCommands

All available Augeas commands.

Elements:

element Initial

Specify initial content for a file, which will be created before Augeas commands are applied if a file doesn’t exist.

Initial takes only text content, which may be the following values: string

element Remove

Implementation of the Augeas rm command.

Attributes:

Name	Description	Values	Required	Default
path	Delete nodes (and all children) matching the given Augeas path expression.	string	Yes	None

Attribute groups:

• py:genshiAttrs

element Move

Implementation of the Augeas mv command.

Attributes:

Name	Description	Values	Required	Default
destination	Move the node to this location. destination must match either zero or one nodes.	string	Yes	None
source	Move the node matching this path expression. source must match exactly one node.	string	Yes	None

Attribute groups:

• py:genshiAttrs

element Set

Implementation of the Augeas set command.

Attributes:

Name	Description	Values	Required	Default
path	Path to set the value for. If the path does not exist, it and all of its ancestors will be created.	string	Yes	None
value	Value to set.	string	Yes	None

Attribute groups:

• py:genshiAttrs

element Clear

Implementation of the Augeas clear command.

Attributes:

Name	Description	Values	Required	Default
path	Path whose value will be set to NULL. If the path does not exist, it and all of its ancestors will be created.	string	Yes	None

Attribute groups:

• py:genshiAttrs

element SetMulti

Set multiple node values at once.

Attributes:

Name	Description	Values	Required	Default
base	The base path.	string	Yes	None
sub	sub will be used as an expression relative to each node that matches the base expression.	string	Yes	None
value	The value to set on all nodes that match sub relative to each node matching base.	string	Yes	None

Attribute groups:

• py:genshiAttrs

element Insert

Implementation of the Augeas ins command.

Attributes:

Name	Description	Values	Required	Default
label	The label of the new node to be created.	string	Yes	None
path	The path to a node that will be the sibling of the new node.	string	Yes	None
where	Where to create the node: before or after the sibling given in path.	before | after	No	before

Attribute groups:

• py:genshiAttrs

Performance

The Augeas tool is quite slow to initialize. For each <Path type="augeas" ... > entry you have, it creates a new Augeas object internally, which can take several seconds. It’s thus important to use this tool sparingly.