QPID-4236,QPID-4237: add some documentation for the FileGroupManager and update the ACL documentation to link that instead, removing the previous group info.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1379980 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 79 insertions, 18 deletions

diff --git a/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
index 017604d910..632778fab3 100644
--- a/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
+++ b/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
@@ -52,6 +52,7 @@
 
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Add-New-Users.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-ACLs.xml"/>
+        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-Group-Providers.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-Java-Qpid-to-use-a-SSL-connection.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-Log4j-CompositeRolling-Appender.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-the-Broker-via-config.xml.xml"/>
diff --git a/doc/book/src/java-broker/Configure-ACLs.xml b/doc/book/src/java-broker/Configure-ACLs.xml
index e82f2a86d0..8c50be27d9 100644
--- a/doc/book/src/java-broker/Configure-ACLs.xml
+++ b/doc/book/src/java-broker/Configure-ACLs.xml
@@ -79,11 +79,10 @@
     </title>
 
     <para>
-      The ACL file consists of a series of rules and group definitions.  Each rule grants or denies specific rights to a user or group. Group
-      definitions declare groups of users and serve to make the ACL file more concise.
+      The ACL file consists of a series of rules associating behaviour for a user or group. Use of groups can serve to make the ACL file more concise. See <link linkend="Configuring-Group-Providers">Configuring Group Providers</link> for more information on defining groups.
     </para>
     <para>
-      Each ACL rule grants (or denies) a particular action on a object to a user.  The rule may be augmented with one or more properties, restricting
+      Each ACL rule grants (or denies) a particular action on a object to a user/group.  The rule may be augmented with one or more properties, restricting
       the rule's applicability.
     </para>
     <programlisting>
@@ -136,13 +135,6 @@
     </programlisting>
 
     <para>
-       GROUP definitions must follow this syntax:
-    </para>
-    <programlisting>
-     GROUP {group name} {username 1}..{username n} # Where username is a username, or a groupname.
-    </programlisting>
-
-    <para>
        Comments may be introduced with the hash (#) character and are ignored.  Long lines can be broken with the slash (\) character.
     </para>
     <programlisting>
@@ -150,8 +142,6 @@
       ACL ALLOW admin CREATE ALL # Also a comment
       ACL DENY guest \
       ALL ALL   # A broken line
-      GROUP securegroup bob \
-      alice # Another broker line
     </programlisting>
   </section>
   <table id="tabl-ConfigureACLs-Syntax_permissions">
@@ -385,13 +375,10 @@
         Worked example 2 - User maintainer group
       </title>
       <para>
-         Suppose you wish to restrict User Management operations to users belonging to a group 'usermaint'.  No other user
-         is allowed to perform user maintainence  This example illustrates the permissioning of a individual component 
-         and a group definition.
+         Suppose you wish to restrict User Management operations to users belonging to a <link linkend="Configuring-Group-Providers">group</link> 'usermaint'.  No other user
+         is allowed to perform user maintainence  This example illustrates the permissioning of an individual component.
       </para>
       <programlisting>
-        # Create a group usermaint with members bob and alice
-        GROUP usermaint bob alice
         # Give operator permission to execute all JMX Methods
         ACL ALLOW usermaint ALL METHOD component="UserManagement"
         ACL DENY ALL ALL METHOD component="UserManagement"
diff --git a/doc/book/src/java-broker/Configure-AuthenticationProviders.xml b/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
index a5a1cd7602..4910197742 100644
--- a/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
+++ b/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
@@ -21,7 +21,7 @@
  
 -->
 
-<section>
+<section id="Configuring-Authentication-Mechanisms">
   <title>Configuring Authentication Mechanisms</title>
   <para>
     In order to successfully establish a connection to the Java Broker, the connection must be
diff --git a/doc/book/src/java-broker/Configure-Group-Providers.xml b/doc/book/src/java-broker/Configure-Group-Providers.xml
new file mode 100644
index 0000000000..f23f4b60f5
--- /dev/null
+++ b/doc/book/src/java-broker/Configure-Group-Providers.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<section id="Configuring-Group-Providers">
+  <title>Configuring Group Providers</title>
+  <para>
+    The Java broker utilises GroupProviders to allow assigning users to groups for use in <link linkend="Configuring-ACLS">ACLs</link>. Following authentication by a given <link linkend="Configuring-Authentication-Mechanisms">Authentication Provider</link>, the configured Group Providers are consulted to allowing assignment of GroupPrincipals for a given authenticated user. 
+  </para>
+
+
+  <section role="h3" id="File-Group-Manager">
+    <title>FileGroupManager</title>
+    <para>
+      The FileGroupManager allows specifying group membership in a flat file on disk, and is also exposed for inspection and update through the brokers HTTP management interface.
+    </para>
+    <para>
+      To enable the FileGroupManager, add the following configuration to the config.xml, adjusting the groupFile attribute value to match your desired groups file location.
+    </para>
+
+    <programlisting><![CDATA[
+    ...
+    <security>
+        <file-group-manager>
+            <attributes>
+              <attribute>
+                <name>groupFile</name>
+                 <value>${conf}/groups</value>
+              </attribute>
+            </attributes>
+        </file-group-manager>
+    </security>]]>
+    ...
+</programlisting>
+
+	<section role="h4" id="File-Group-Manager-FileFormat">
+       <title>File Format</title>
+	  <para>
+            The groups file has the following format:
+          </para>
+            <programlisting>
+    # &lt;GroupName&gt;.users = &lt;comma deliminated user list&gt;
+    # For example:
+
+    administrators.users = admin,manager
+</programlisting>
+          <para>
+            Only users can be added to a group currently, not other groups. Usernames can't contain commas.
+          </para><para>
+            Lines starting with a '#' are treated as comments when opening the file, but these are not preserved when the broker updates the file due to changes made through the management interface.
+          </para>
+     </section>
+  </section>
+</section>