Added client ACLs:

* IP and CIDR-based ACLs
* Metadata (group/hostname)-based ACLs
* Documentation
* Unit tests

2 files changed, 207 insertions, 0 deletions

diff --git a/doc/server/plugins/misc/acl.txt b/doc/server/plugins/misc/acl.txt
new file mode 100644
index 000000000..73f99bf85
--- /dev/null
+++ b/doc/server/plugins/misc/acl.txt
@@ -0,0 +1,202 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-misc-acl:
+
+===
+ACL
+===
+
+The ACL plugin lets you set client communication ACLs to prevent
+clients from accessing the full range of exposed XML-RPC methods.
+
+You can get a list of all exposed methods by running::
+
+    bcfg2-admin xcmd listMethods
+
+Note that this will only list methods that are available to the client
+this is run from; that is, if the ACL plugin is in place,
+``listMethods`` will reflect the ACLs.
+
+ACLs can be set in two different ways:
+
+* IP-based ACLs allow you to set ACLs based on client IP address or
+  CIDR range.
+* Metadata-based ACLs allow you to set ACLs based on client hostname,
+  group membership, or complex combinations thereof.
+
+IP-based ACLs are much faster, but metadata-based ACLs are often
+easier and better.
+
+If you are not going to use any ACLs, it is recommended that you
+disable this plugin because using it can incur a slight performance
+hit.  If you are using IP-based ACLs but *not* metadata-based ACLs, it
+is similarly recommended that you ensure that your IP-based ACL file
+ends with an explicit Deny for all clients; this will ensure that
+metadata-based ACLs are never checked.  If you are using
+metadata-based ACLs, :ref:`server-caching` can alleviate most of the
+performance penalty.
+
+Enabling the ACL plugin
+=======================
+
+First, create ``/var/lib/bcfg2/ACL/``.  Then, add ``ACL`` to your
+``plugins`` list in ``bcfg2.conf``::
+
+    plugins = Bundler, Cfg, ..., Packages, ACL
+
+Finally, create ``/var/lib/bcfg2/ACL/ip.xml`` (for `IP-based ACLs`_),
+``/var/lib/bcfg2/ACL/metadata.xml`` (for `Metadata-based ACLs`_), or
+both.
+
+IP-based ACLs
+=============
+
+IP-based ACLs allow you to set ACLs based on client IP address or CIDR
+range.  IP-based ACLs are very fast.  If you are using IP-based ACLs
+but *not* metadata-based ACLs, it is recommended that you ensure that
+your IP-based ACL file ends with an explicit Deny for all clients;
+this will ensure that metadata-based ACLs are never checked.
+
+IP-based ACLs are defined in ``ACL/ip.xml``.  The file is parsed
+sequentially; the first matching rule applies.  Each rule is either
+Allow (to allow the client access), Deny (to deny the client access),
+or Defer (to defer to `Metadata-based ACLs`_).  The last rule in
+``ip.xml`` is an implicit default allow for 127.0.0.1, and an implicit
+default defer for all other machines.
+
+If no ``ip.xml`` file exists, then ACL checking will be deferred to
+metadata-based ACLs.
+
+Example
+-------
+
+.. code-block:: xml
+
+    <ACL>
+      <Allow address="192.168.1.10" method="*.*"/>
+      <Deny address="192.168.2.0" netmask="255.255.255.0"
+            method="AssertProfile"/>
+      <Allow address="192.168.1.12" method="Git.Update"/>
+      <Allow method="*"/>
+    </ACL>
+
+In this example:
+
+* The machine at 192.168.1.10 (perhaps the Bcfg2 server) can call all
+  plugin XML-RPC methods;
+* Machines in the 192.168.2.0/24 network cannot assert their own
+  profiles;
+* The machine at 192.168.1.12 (perhaps the Git server) can call the
+  Git.Update method;
+* All machines can call core methods (except 192.168.2.0/24, which can
+  call all core methods except AssertProfile).
+
+Implicitly, all machines (except localhost) except 192.168.1.10 are
+disallowed access to the plugin methods.
+
+You can also provide a minimal configuration to try to weed out some
+obvious bad requests before doing the more expensive `Metadata-based
+ACLs`_.  For instance:
+
+.. code-block:: xml
+
+    <ACL>
+      <Allow method="*"/>
+      <Defer address="192.168.1.0" netmask="24" method="*.*"/>
+      <Deny method="*.*"/>
+    </ACL>
+
+In this example:
+
+* All machines can call all core methods without checking metadata
+  ACLs;
+* Plugin method calls from machines in 192.168.1.0/24 are deferred to
+  metadata ACLs; and
+* All other plugin method calls are denied.
+
+The only time metadata ACLs would be checked in this example would be
+plugin method calls by machines in 192.168.1.0/24.
+
+Reference
+---------
+
+.. xml:type: IPACLContainerType
+
+Metadata-based ACLs
+===================
+
+Metadata-based ACLs let you set ACLs based on client hostname or group
+membership, which is much more flexible and maintainable than
+`IP-based ACLs`_.  The downside is that it is slower, because it
+requires generating client metadata for each machine that tries to
+authenticate.  Without :ref:`server-caching`, using metadata-based
+ACLs will double the number of client metadata builds per client run,
+which could be a sizeable performance penalty.
+
+In order to limit the performance penalty, it's highly recommended
+to:
+
+* Enable :ref:`server-caching` in ``cautious`` or ``aggressive`` mode;
+  and
+* Deny as many clients as possible with `IP-based ACLs`_.
+
+Metadata-based ACLs are defined in ``ACL/metadata.xml``.  Only Allow
+and Deny rules are supported, not Defer rules.  The file is parsed
+sequentially; the first matching rule applies.  The last rule in
+``metadata.xml`` is an implicit default allow for machines called
+``localhost`` or ``localhost.localdomain``, and an implicit default
+deny for all other machines.
+
+If no ``metadata.xml`` file exists, then all requests are implicitly
+allowed.
+
+Example
+-------
+
+This example is functionally identical to the `IP-based ACLs` example
+above, but more maintainable in several ways:
+
+.. code-block:: xml
+
+    <ACL>
+      <Group name="bcfg2-server">
+        <Allow method="*.*"/>
+      </Group>
+      <Group name="user-workstations">
+        <Deny method="AssertProfile"/>
+      </Group>
+      <Group name="git-server">
+        <Allow method="Git.Update"/>
+      </Group>
+      <Allow method="*"/>
+    </ACL>
+
+In this case, if you add a Bcfg2 server or Git server, or one of those
+servers changes IP address, you don't need to rewrite your ACLs.
+Similarly, you could add a new subnet of user workstations.
+
+Reference
+---------
+
+.. xml:type: MetadataACLContainerType
+
+.. _server-plugins-misc-acl-wildcards:
+
+Wildcards
+=========
+
+The ACL descriptions allow you to use '*' as a wildcard for any number
+of characters *other than* ``.``.  That is:
+
+* ``*`` would match ``DeclareVersion`` and ``GetProbes``, but would
+  *not* match ``Git.Update`.
+* ``*.*`` would match ``Git.Update``, but not ``DeclareVersion`` or
+  ``GetProbes``.
+
+Since all plugin methods are scoped to their plugin (i.e., they are
+all ``<plugin name>.<method name>``), and all core methods have no
+scope, this lets you easily allow or deny core or plugin methods.  You
+could also do something like ``*.toggle_debug`` to allow a host to
+enable or disable debugging for all plugins.
+
+No other bash globbing is supported.
diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt
index 96644571b..f35c1bd23 100644
--- a/doc/server/xml-common.txt
+++ b/doc/server/xml-common.txt
@@ -289,6 +289,11 @@ Feature Matrix
 +-------------------------------------------------+--------------+--------+------------+------------+
 | File                                            | Group/Client | Genshi | Encryption | XInclude   |
 +=================================================+==============+========+============+============+
+| :ref:`ACL ip.xml <server-plugins-misc-acl>'     | No           | No     | No         | Yes        |
++-------------------------------------------------+--------------+--------+------------+------------+
+| :ref:`ACL metadata.xml                          | Yes          | Yes    | Yes        | Yes        |
+| <server-plugins-misc-acl>'                      |              |        |            |            |
++-------------------------------------------------+--------------+--------+------------+------------+
 | :ref:`Bundler                                   | Yes          | Yes    | Yes        | Yes        |
 | <server-plugins-structures-bundler-index>`      |              |        |            |            |
 +-------------------------------------------------+--------------+--------+------------+------------+