From 53f8eb67378f6a8054cb107e72b094f070d40c83 Mon Sep 17 00:00:00 2001
From: "Chris St. Pierre" <chris.a.st.pierre@gmail.com>
Date: Thu, 5 Dec 2013 09:58:18 -0500
Subject: Tools: new Augeas driver

---
 doc/client/tools/augeas.txt             | 72 +++++++++++++++++++++++++++++++++
 doc/server/plugins/generators/rules.txt | 14 +++++++
 2 files changed, 86 insertions(+)
 create mode 100644 doc/client/tools/augeas.txt

(limited to 'doc')

diff --git a/doc/client/tools/augeas.txt b/doc/client/tools/augeas.txt
new file mode 100644
index 000000000..94ed9066f
--- /dev/null
+++ b/doc/client/tools/augeas.txt
@@ -0,0 +1,72 @@
+.. -*- 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.
+
+Each of these commands will only be run if the path does not already
+have the given setting.  That is, the ip address for the first host
+record will only be set to ``192.168.0.1`` if it's not set to that
+value already.  Its canonical name will only be set to
+``pigiron.example.com`` if it's not that already; and so on.
+
+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.
+
+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.
diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index 9ba70238d..a21dd217f 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -136,6 +136,20 @@ Attributes common to all Path tags:
    :onlyattrs: name,type
 
 
+augeas
+^^^^^^
+
+Run `Augeas <http://www.augeas.net>`_ commands.  See
+:ref:`client-tools-augeas` for more details.
+
+.. xml:type:: PathType
+   :nochildren:
+   :noattributegroups:
+   :nodoc:
+   :notext:
+   :onlyattrs: owner,group,mode,secontext,lens
+   :requiredattrs: owner,group,mode
+
 device
 ^^^^^^
 
-- 
cgit v1.2.3-1-g7c22