From 2937c360fb7bd0c674ec484bec1a21d3b6f24186 Mon Sep 17 00:00:00 2001
From: "Chris St. Pierre" <chris.a.st.pierre@gmail.com>
Date: Wed, 1 Aug 2012 10:29:07 -0400
Subject: added ACL docs

---
 doc/server/info.txt                     | 37 +++++++++----------------
 doc/server/plugins/generators/rules.txt | 48 +++++++++++++++++++++++++++++++++
 schemas/types.xsd                       |  1 -
 3 files changed, 61 insertions(+), 25 deletions(-)

diff --git a/doc/server/info.txt b/doc/server/info.txt
index d6bcf67e2..eea819b7e 100644
--- a/doc/server/info.txt
+++ b/doc/server/info.txt
@@ -13,12 +13,13 @@ Various file properties for entries served by the :ref:`Cfg
 <server-plugins-generators-sshbase>` 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:
+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.xml``, ``:info``, or
+``info`` files. Each config file directory can have a ``info.xml``,
+``:info`` or ``info`` file if needed. The possible fields in an info
+file are:
 
 +------------+-------------------+----------------------------------+---------+
 | Field      | Possible values   | Description                      | Default |
@@ -76,24 +77,6 @@ might look like::
 See :ref:`server-selinux` for more information on the ``secontext``
 attribute and managing SELinux in general.
 
-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                        |         |
-+------------+-------------------+----------------------------------+---------+
-
 .. _server-info-info-xml:
 
 info.xml files
@@ -133,3 +116,9 @@ of permissions depending on the path of the file::
         <Info owner="root" group="root" perms="0600"/>
       </Path>
     </FileInfo>
+
+.. versionadded:: 1.3.0
+
+You can also specify ACLs as children of ``<Info>`` tags in
+``info.xml``.  See :ref:`server-plugins-generators-rules-acls` for
+more information on the formatting of ACL tags.
diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index f693f6e62..0b143dcd6 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -328,6 +328,54 @@ symlink
 | to   | File to link to      | String |
 +------+----------------------+--------+
 
+.. _server-plugins-generators-rules-acls:
+
+ACLs
+^^^^
+
+.. versionadded:: 1.3.0
+
+ACLs on a Path entry are specified not by attributes on the tag but by
+child ``<ACL>`` tags.  For instance:
+
+.. code-block:: xml
+
+    <Path name="/etc/foo" type="directory" owner="root" group="root"
+          perms="0775">
+      <ACL type="default" scope="user" user="foouser" perms="rw"/>
+      <ACL type="default" scope="group" group="users" perms="rx"/>
+    </Path>
+
+The ACL tag has the following attributes:
+
++-------+---------------------------------------------------+----------------+
+| Name  | Description                                       | Values         |
++=======+===================================================+================+
+| type  | ACL type                                          | default|access |
++-------+---------------------------------------------------+----------------+
+| scope | ACL scope                                         | user|group     |
++-------+---------------------------------------------------+----------------+
+| user  | User the ACL applies to ``(with scope="user"``)   | String         |
++-------+---------------------------------------------------+----------------+
+| group | Group the ACL applies to ``(with scope="group"``) | String         |
++-------+---------------------------------------------------+----------------+
+| perms | Permissions for the ACL                           | See below      |
++-------+---------------------------------------------------+----------------+
+
+The ``perms`` attribute can either be a single octal digit (e.g.,
+``6`` would indicate read and write, but not execute), or a symbolic
+mode including 'r', 'w', and 'x'.  You can include '-' for operations
+that are not permitted, but it's not required.  I.e., all of the
+following are identical::
+
+    perms="5"
+    perms="rx"
+    perms="r-x"
+
+It is not currently possible to manually set an effective rights mask;
+the mask will be automatically calculated from the given ACLs when
+they are applied.
+
 SELinux Tag
 -----------
 
diff --git a/schemas/types.xsd b/schemas/types.xsd
index 1055bdf67..83cc2c9ee 100644
--- a/schemas/types.xsd
+++ b/schemas/types.xsd
@@ -128,7 +128,6 @@
     <xsd:attribute type="xsd:string" name="perms" use="required"/>
     <xsd:attribute type="xsd:string" name="user"/>
     <xsd:attribute type="xsd:string" name="group"/>
-    <xsd:attribute type="xsd:string" name="recursive"/>
     <xsd:attributeGroup ref="py:genshiAttrs"/>
   </xsd:complexType>
 
-- 
cgit v1.2.3-1-g7c22