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><Test/></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:
- element Move¶
- Implementation of the Augeas
mv
command.
- element Set¶
- Implementation of the Augeas
set
command.
- element Clear¶
- Implementation of the Augeas
clear
command.- Attributes:
Name Description Values Required Default path
Path whose value will be set toNULL
. If the path does not exist, it and all of its ancestors will be created.string
Yes None - Attribute groups:
- element SetMulti¶
- Set multiple node values at once.
- element Insert¶
- Implementation of the Augeas
ins
command.
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.