1 files changed, 95 insertions, 0 deletions
diff --git a/doc/client/tools/augeas.txt b/doc/client/tools/augeas.txt
new file mode 100644
index 000000000..6fed5f5ce
--- /dev/null
+++ b/doc/client/tools/augeas.txt
@@ -0,0 +1,95 @@
+.. -*- mode: rst -*-
+
+.. _client-tools-augeas:
+
+========
+ Augeas
+========
+
+The Augeas tool provides a way to use `Augeas
+<http://www.augeas.net>`_ 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:
+
+.. code-block:: xml
+
+    <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:
+
+.. code-block:: xml
+
+    <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:
+
+.. code-block:: xml
+
+    <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
+======
+
+.. xml:group:: augeasCommands
+
+
+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.