Add the ability to specify important entries via info/info.xml

We currently have 'important' entries specified only inside the code for
various client tools. This provides no room for growing that list
outside of adding things to the code itself. With this change, users can
now specify important entries via an additional attribute in their
info.xml files.

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5957 ce84e21b-d406-0410-9b95-82705330c041

6 files changed, 127 insertions, 65 deletions

diff --git a/doc/server/configurationentries.txt b/doc/server/configurationentries.txt
index ba727ee22..059eb1288 100644
--- a/doc/server/configurationentries.txt
+++ b/doc/server/configurationentries.txt
@@ -1,11 +1,14 @@
 .. -*- mode: rst -*-
 
-.. _Base: server-plugins-structures-base
-.. _Bundler: server-plugins-structures-bundler-index
-.. _Cfg: server-plugins-generators-cfg
-.. _TGenshi: server-plugins-generators-tgenshi-index
-.. _TCheetah: server-plugins-generators-tcheetah
-.. _Rules: server-plugins-generators-rules
+.. NOTE: these are relative links (change when directory structure
+..       changes)
+
+.. _Base: plugins/structures/base
+.. _Bundler: plugins/structures/bundler
+.. _Cfg: plugins/generators/cfg
+.. _TGenshi: plugins/generators/tgenshi
+.. _TCheetah: plugins/generators/tcheetah
+.. _Rules: plugins/generators/rules
 
 .. _server-configurationentries:
 
@@ -90,8 +93,7 @@ the *type* and any other necessary attributes in `Rules`_.
 +-------------+----------------------+-----------------+--------------------------+
 
 Keep in mind that permissions for files served up by Cfg/TGenshi/TCheetah
-are still handled via the traditional mechanisms (info/:info/info.xml
-files in the plugin directory).
+are still handled via the traditional :ref:`server-info` mechanisms.
 
 .. _boundentries:
 
diff --git a/doc/server/index.txt b/doc/server/index.txt
index 9c351c652..b0c97ccae 100644
--- a/doc/server/index.txt
+++ b/doc/server/index.txt
@@ -13,4 +13,5 @@ Bcfg2 Server
    admin/index
    reports/index
    configurationentries
+   info
    snapshots/index
diff --git a/doc/server/info.txt b/doc/server/info.txt
new file mode 100644
index 000000000..0adf8ce51
--- /dev/null
+++ b/doc/server/info.txt
@@ -0,0 +1,97 @@
+.. -*- mode: rst -*-
+
+.. NOTE: these are relative links (change when directory structure
+..       changes)
+
+.. _Cfg: plugins/generators/cfg
+.. _TGenshi: plugins/generators/tgenshi
+.. _TCheetah: plugins/generators/tcheetah
+
+.. _server-info:
+
+====
+Info
+====
+
+Various file properties for entries served by the `Cfg`_, `TGenshi`_,
+and `TCheetah`_ plugins are controlled through the use of ``:info``,
+``info``, or ``info.xml`` files.
+
+By default, these plugins are set to write files to the filesystem with
+owner **root**, group **root**, and mode **644** (read and write for
+owner, read only for group and other). These options, and a few others,
+can be overridden through use of ``:info`` or ``info`` files. Each config
+file directory can have a ``:info`` or ``info`` file if needed. The
+possible fields in an info file are:
+
++------------+-------------------+----------------------------------+---------+
+| Field      | Possible values   | Description                      | Default |
++============+===================+==================================+=========+
+| encoding:  | ascii | base64    | Encoding of the file. Use        | ascii   |
+|            |                   | base64 for non-ASCII files       |         |
++------------+-------------------+----------------------------------+---------+
+| group:     | Any valid group   | Sets group of the file           | root    |
++------------+-------------------+----------------------------------+---------+
+| important: | true | false      | Important entries are            | root    |
+|            |                   | installed first during client    |         |
+|            |                   | execution                        |         |
++------------+-------------------+----------------------------------+---------+
+| owner:     | Any valid user    | Sets owner of the file           | root    |
++------------+-------------------+----------------------------------+---------+
+| paranoid:  | yes | no          | Backup file before replacement?  | no      |
++------------+-------------------+----------------------------------+---------+
+| perms:     | Numeric file mode | Sets the permissions of the file | 0644    |
++------------+-------------------+----------------------------------+---------+
+
+A sample info file for CGI script on a web server might look like::
+
+    owner: www
+    group: www
+    perms: 0755
+
+Back to the fstab example again, our final ``Cfg/etc/fstab/`` directory
+might look like::
+
+    :info
+    fstab
+    fstab.G50_server
+    fstab.G99_fileserver
+    fstab.H_host.example.com
+
+Important attribute
+===================
+
+.. versionadded:: 1.1.0
+
+Having important entries hardcoded into the various client tools has
+worked relatively well so far. However, this method allows for a bit
+more flexibility as the entries can be controlled via the configuration
+specification.
+
++------------+-------------------+----------------------------------+---------+
+| Field      | Possible values   | Description                      | Default |
++============+===================+==================================+=========+
+| important: | true | false      | Important entries are            | root    |
+|            |                   | installed first during client    |         |
+|            |                   | execution                        |         |
++------------+-------------------+----------------------------------+---------+
+
+info.xml files
+==============
+
+``info.xml`` files add the ability to specify different sets of file
+metadata on a group by group basis. These files are XML, and work
+similarly to those used by :ref:`Rules <server-plugins-generators-rules>`
+or :ref:`Pkgmgr <server-plugins-generators-pkgmgr>`.
+
+The following specifies a different global set of permissions
+(root/sys/0651) than on clients in group webserver (root/root/0652)
+
+.. code-block:: xml
+
+    <FileInfo>
+      <Group name='webserver'>
+        <Info owner='root' group='root' perms='0652'/>
+      </Group>
+      <Info owner='root' group='sys' perms='0651'/>
+    </FileInfo>
diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt
index a79b93178..0d837f419 100644
--- a/doc/server/plugins/generators/cfg.txt
+++ b/doc/server/plugins/generators/cfg.txt
@@ -149,61 +149,9 @@ file. The reason the other deltas aren't applied to *foo.example.com*
 is because a **.H_** delta is more specific than a **.G##_** delta. Bcfg2
 applies all the deltas at the most specific level.
 
-Info files
-==========
-
-By default, Cfg writes files to the filesystem with owner *root*, group
-*root*, and mode *644* (read and write for owner, read only for group
-and other). These options, and a few others, can be overridden through
-use of ``:info`` or ``info`` files. Each config file directory can have
-a ``:info`` or ``info`` file if needed. The possible fields in an info
-file are:
-
-+-----------+-------------------+------------------------------------------------------+---------+
-| Field     | Possible values   | Description                                          | Default |
-+===========+===================+======================================================+=========+
-| owner:    | Any valid user    | Sets owner of the file                               | root    |
-+-----------+-------------------+------------------------------------------------------+---------+
-| group:    | Any valid group   | Sets group of the file                               | root    |
-+-----------+-------------------+------------------------------------------------------+---------+
-| perms:    | Numeric file mode | Sets the permissions of the file                     | 0644    |
-+-----------+-------------------+------------------------------------------------------+---------+
-| encoding: | ascii | base64    | Encoding of the file. Use base64 for non-ASCII files | ascii   |
-+-----------+-------------------+------------------------------------------------------+---------+
-| paranoid: | yes | no          | Backup file before replacement?                      | no      |
-+-----------+-------------------+------------------------------------------------------+---------+
-
-A sample info file for CGI script on a web server might look like::
-
-    owner: www
-    group: www
-    perms: 0755
-
-Back to the fstab example again, our final ``Cfg/etc/fstab/`` directory
-might look like::
-
-    :info
-    fstab
-    fstab.G50_server
-    fstab.G99_fileserver
-    fstab.H_host.example.com
-
-info.xml files
-==============
-
-info.xml files add the ability to specify different sets of file metadata
-on a group by group basis. These files are XML, and work similarly
-to those used by :ref:`Rules <server-plugins-generators-rules>` or
-:ref:`Pkgmgr <server-plugins-generators-pkgmgr>`.
-
-The following specifies a different global set of permissions
-(root/sys/0651) than on clients in group webserver (root/root/0652)
-
-.. code-block:: xml
+File permissions
+================
 
-    <FileInfo>
-      <Group name='webserver'>
-        <Info owner='root' group='root' perms='0652'/>
-      </Group>
-      <Info owner='root' group='sys' perms='0651'/>
-    </FileInfo>
+File permissions for entries handled by Cfg are controlled via the use
+of :ref:`server-info` files. Note that you **cannot** use both a
+Permissions entry and a Path entry to handle the same file.
diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt
index 2daa18740..b5c99f33a 100644
--- a/doc/server/plugins/generators/tcheetah.txt
+++ b/doc/server/plugins/generators/tcheetah.txt
@@ -34,6 +34,13 @@ The ``info`` file is formatted like ``:info`` files from Cfg.
 
 Mostly, people will want to use client metadata.
 
+File permissions
+================
+
+File permissions for entries handled by TCheetah are controlled via the
+use of :ref:`server-info` files. Note that you **cannot** use both a
+Permissions entry and a Path entry to handle the same file.
+
 self.metadata variables
 =======================
 
diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt
index 71d0acfad..57440f6df 100644
--- a/doc/server/plugins/generators/tgenshi/index.txt
+++ b/doc/server/plugins/generators/tgenshi/index.txt
@@ -129,6 +129,13 @@ allocations map to sudo and root access.
     ${"\n".join(metadata.BB['users'][user])}
     {% end %}
 
+File permissions
+================
+
+File permissions for entries handled by TGenshi are controlled via the
+use of :ref:`server-info` files. Note that you **cannot** use both a
+Permissions entry and a Path entry to handle the same file.
+
 FAQs
 ====