Update from trunk r1375509 through r1450773asyncstore

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

1 files changed, 536 insertions, 0 deletions

diff --git a/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml b/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
new file mode 100644
index 0000000000..21e1052183
--- /dev/null
+++ b/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
@@ -0,0 +1,536 @@
+<?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="Java-Broker-Security-ACLs">
+  <title>Access Control Lists</title>
+  <para>
+    In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user.
+    To enable, the &lt;acl/&gt; element is used within the &lt;security/&gt; element of the configuration XML.
+    In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual
+    hosts.  The  &lt;acl/&gt; configuration references a text file containing the ACL rules.
+    By convention, this file should have a .acl extension.
+  </para>
+
+
+  <section role="h3" id="Java-Broker-Security-ACLs-EnablingACL">
+    <title>
+       Enabling ACLs
+    </title>
+
+    <para>
+      To apply an ACL broker-wide, add the following to the config.xml (assuming that <replaceable>conf</replaceable> has been set to a suitable
+      location such as ${QPID_HOME}/etc):
+    </para>
+
+    <programlisting>
+      &lt;broker&gt;
+        ...
+        &lt;security&gt;
+          ...
+          &lt;acl&gt;<replaceable>${conf}/broker.acl</replaceable>&lt;/acl&gt;
+        &lt;/security&gt;
+      &lt;/broker&gt;
+    </programlisting>
+
+    <para>
+    </para>
+
+    <para>
+      To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml:
+    </para>
+
+    <programlisting>
+      &lt;virtualhost&gt;
+        ...
+        &lt;name&gt;test&lt;/name&gt;
+        &lt;test&gt;
+          ...
+          &lt;security&gt;
+            &lt;acl&gt;<replaceable>${conf}/vhost_test.acl</replaceable>&lt;/acl&gt;
+          &lt;/security&gt;
+        &lt;/test&gt;
+      &lt;/virtualhost&gt;
+    </programlisting>
+  </section>
+
+  <section role="h3" id="Java-Broker-Security-ACLs-WriteACL">
+    <title>
+       Writing .acl files
+    </title>
+
+    <para>
+      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="Java-Broker-Security-Group-Providers">Configuring Group Providers</link> for more information on defining groups.
+    </para>
+    <para>
+      Each ACL rule grants or denies a particular action on an object to a user/group.  The rule may be augmented with one or more properties, restricting
+      the rule's applicability.
+    </para>
+    <programlisting>
+      ACL ALLOW alice CREATE QUEUE              # Grants alice permission to create all queues.
+      ACL DENY bob CREATE QUEUE name="myqueue"  # Denies bob permission to create a queue called "myqueue"
+    </programlisting>
+    <para>
+      The ACL is considered in strict line order with the first matching rule taking precedence over all those that follow. In the following
+      example, if the user bob tries to create an exchange "myexch", the operation will be allowed by the first rule.  The second rule will
+      never be considered.
+    </para>
+    <programlisting>
+      ACL ALLOW bob ALL EXCHANGE
+      ACL DENY bob CREATE EXCHANGE name="myexch"  # Dead rule
+    </programlisting>
+    <para>
+      If the desire is to allow bob to create all exchanges except "myexch", order of the rules must be reversed:
+    </para>
+    <programlisting>
+      ACL DENY bob CREATE EXCHANGE name="myexch"
+      ACL ALLOW bob ALL EXCHANGE
+    </programlisting>
+    <para>
+      All ACL files end with an implict rule denying all operations to all users.  It is as if each file ends with
+      <programlisting>ACL DENY ALL ALL </programlisting>
+      If instead you wish to <emphasis>allow</emphasis> all operations other than those controlled by earlier rules,
+      add <programlisting>ACL ALLOW ALL ALL</programlisting> to the bottom of the ACL file.
+    </para>
+    <para>
+      When writing a new ACL, a good approach is to begin with an .acl file containing only <programlisting>ACL DENY-LOG ALL ALL</programlisting>
+      which will cause the Broker to deny all operations with details of the denial logged to the Qpid log file. Build up the ACL rule by rule,
+      gradually working through the use-cases of your system.  Once the ACL is complete, consider switching the DENY-LOG actions to DENY
+      to improve performamce and reduce log noise.
+    </para>
+    <para>
+      ACL rules are very powerful: it is possible to write very granular rules specifying many broker objects and their
+      properties.  Most projects probably won't need this degree of flexibility.  A reasonable approach is to choose to apply permissions
+      at a certain level of abstraction (e.g. QUEUE) and apply them consistently across the whole system.
+    </para>
+  </section>
+
+  <section role="h4" id="Java-Broker-Security-ACLs-Syntax">
+    <title>
+       Syntax
+    </title>
+
+    <para>
+       ACL rules follow this syntax:
+    </para>
+    <programlisting>
+     ACL {permission} {&lt;group-name&gt;|&lt;user-name>&gt;|ALL} {action|ALL} [object|ALL] [property="&lt;property-value&gt;"]
+    </programlisting>
+
+    <para>
+       Comments may be introduced with the hash (#) character and are ignored.  Long lines can be broken with the slash (\) character.
+    </para>
+    <programlisting>
+      # A comment
+      ACL ALLOW admin CREATE ALL # Also a comment
+      ACL DENY guest \
+      ALL ALL   # A broken line
+    </programlisting>
+  </section>
+  <table id="table-Java-Broker-Security-ACLs-Syntax_permissions">
+    <title>List of ACL permission</title>
+    <tgroup cols="2">
+      <tbody>
+        <row>
+          <entry><command>ALLOW</command></entry>
+          <entry><para>Allow the action</para></entry>
+        </row>
+        <row>
+          <entry><command>ALLOW-LOG</command></entry>
+          <entry><para> Allow the action and log the action in the log </para></entry>
+        </row>
+        <row>
+          <entry><command>DENY</command></entry>
+          <entry><para> Deny the action</para></entry>
+        </row>
+        <row>
+          <entry><command>DENY-LOG</command></entry>
+          <entry><para> Deny the action and log the action in the log</para></entry>
+       </row>
+     </tbody>
+    </tgroup>
+  </table>
+  <table id="table-Java-Broker-Security-ACLs-Syntax_actions">
+    <title>List of ACL actions</title>
+    <tgroup cols="2">
+      <tbody>
+        <row>
+          <entry> <command>CONSUME</command> </entry>
+          <entry> <para> Applied when subscriptions are created </para> </entry>
+        </row>
+        <row>
+          <entry> <command>PUBLISH</command> </entry>
+          <entry> <para> Applied on a per message basis on publish message transfers</para> </entry>
+        </row>
+        <row>
+          <entry> <command>CREATE</command> </entry>
+          <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry>
+        </row>
+        <row>
+          <entry> <command>ACCESS</command> </entry>
+          <entry> <para> Applied when an object is read or accessed</para> </entry>
+        </row>
+        <row>
+          <entry> <command>BIND</command> </entry>
+          <entry> <para> Applied when queues are bound to exchanges</para> </entry>
+        </row>
+        <row>
+          <entry> <command>UNBIND</command> </entry>
+          <entry> <para> Applied when queues are unbound from exchanges</para> </entry>
+        </row>
+        <row>
+          <entry> <command>DELETE</command> </entry>
+          <entry> <para> Applied when objects are deleted </para> </entry>
+        </row>
+        <row>
+          <entry> <command>PURGE</command> </entry> <entry>
+          <para>Applied when purge the contents of a queue</para> </entry>
+        </row>
+        <row>
+          <entry> <command>UPDATE</command> </entry>
+          <entry> <para> Applied when an object is updated </para> </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+  <table id="table-Java-Broker-Security-ACLs-Syntax_objects">
+    <title>List of ACL objects</title>
+    <tgroup cols="2">
+      <tbody>
+        <row>
+          <entry> <command>VIRTUALHOST</command> </entry>
+          <entry> <para>A virtualhost (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>MANAGEMENT </command> </entry>
+          <entry> <para>Management - for web and JMX (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>QUEUE</command> </entry>
+          <entry> <para>A queue </para> </entry>
+        </row>
+        <row>
+          <entry> <command>EXCHANGE</command> </entry>
+        <entry> <para>An exchange </para> </entry>
+        </row>
+        <row>
+          <entry> <command>USER</command> </entry>
+          <entry> <para>A user (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>GROUP</command> </entry>
+          <entry> <para>A group (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>METHOD</command> </entry>
+          <entry> <para>Management or agent or broker method (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>LINK</command> </entry>
+          <entry> <para>A federation or inter-broker link (not currently used in Java Broker)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>BROKER</command> </entry>
+          <entry> <para>The broker (not currently used in Java Broker)</para> </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+  <table id="table-Java-Broker-Security-ACLs-Syntax_properties">
+    <title>List of ACL properties</title>
+    <tgroup cols="2">
+      <tbody>
+        <row>
+          <entry><command>name</command> </entry>
+          <entry> <para> String. Object name, such as a queue name, exchange name or JMX method name.  </para> </entry>
+        </row>
+        <row>
+          <entry> <command>durable</command> </entry>
+          <entry> <para> Boolean. Indicates the object is durable </para> </entry>
+        </row>
+        <row>
+          <entry> <command>routingkey</command> </entry>
+          <entry> <para> String. Specifies routing key </para> </entry>
+        </row>
+        <row>
+          <entry> <command>passive</command> </entry>
+          <entry> <para> Boolean. Indicates the presence of a <parameter>passive</parameter> flag </para> </entry>
+        </row>
+        <row>
+          <entry> <command>autodelete</command> </entry>
+          <entry> <para> Boolean. Indicates whether or not the object gets deleted when the connection is closed </para> </entry>
+        </row>
+        <row>
+          <entry> <command>exclusive</command> </entry>
+          <entry> <para> Boolean. Indicates the presence of an <parameter>exclusive</parameter> flag </para> </entry>
+        </row>
+        <row>
+          <entry> <command>temporary</command> </entry>
+          <entry> <para> Boolean. Indicates the presence of an <parameter>temporary</parameter> flag </para> </entry>
+        </row>
+        <row>
+          <entry> <command>type</command> </entry>
+          <entry> <para> String. Type of object, such as topic, fanout, or xml </para> </entry>
+        </row>
+        <row>
+          <entry> <command>alternate</command> </entry>
+          <entry> <para> String. Name of the alternate exchange </para> </entry>
+        </row>
+        <row>
+          <entry> <command>queuename</command> </entry>
+          <entry> <para> String. Name of the queue (used only when the object is something other than <parameter>queue</parameter> </para> </entry>
+        </row>
+        <row>
+          <entry> <command>component</command> </entry>
+          <entry> <para> String. JMX component name (Java Broker only)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>schemapackage</command> </entry>
+          <entry> <para> String. QMF schema package name (Not used in Java Broker)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>schemaclass</command> </entry>
+          <entry> <para> String. QMF schema class name (Not used in Java Broker)</para> </entry>
+        </row>
+        <row>
+          <entry> <command>from_network</command> </entry>
+          <entry>
+            <para>
+              Comma-separated strings representing IPv4 address ranges.
+            </para>
+            <para>
+              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
+            </para>
+            <para>
+              The rule matches if any of the address ranges match the IPv4 address of the messaging client.
+              The address ranges are specified using either Classless Inter-Domain Routing notation
+              (e.g. 192.168.1.0/24; see <ulink url="http://tools.ietf.org/html/rfc4632">RFC 4632</ulink>)
+              or wildcards (e.g. 192.169.1.*).
+            </para>
+            <para>
+              Java Broker only.
+            </para>
+          </entry>
+        </row>
+        <row>
+          <entry> <command>from_hostname</command> </entry>
+          <entry>
+            <para>
+              Comma-separated strings representing hostnames, specified using Perl-style regular
+              expressions, e.g. .*\.example\.company\.com
+            </para>
+            <para>
+              Intended for use in ACCESS VIRTUALHOST rules to apply firewall-like restrictions.
+            </para>
+            <para>
+              The rule matches if any of the patterns match the hostname of the messaging client.
+            </para>
+            <para>
+              To look up the client's hostname, Qpid uses Java's DNS support, which internally caches its results.
+            </para>
+            <para>
+              You can modify the time-to-live of cached results using the *.ttl properties described on the
+              Java <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/net/properties.html">Networking
+              Properties</ulink> page.
+            </para>
+            <para>
+              For example, you can either set system property sun.net.inetaddr.ttl from the command line
+              (e.g. export QPID_OPTS="-Dsun.net.inetaddr.ttl=0") or networkaddress.cache.ttl in
+              $JAVA_HOME/lib/security/java.security. The latter is preferred because it is JVM
+              vendor-independent.
+            </para>
+            <para>
+              Java Broker only.
+            </para>
+          </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+  <table id="table-Java-Broker-Security-ACLs-Syntax_javacomponents">
+    <title>List of ACL rules</title>
+    <tgroup cols="3">
+      <tbody>
+        <row>
+          <entry> <command>UserManagement</command> </entry>
+          <entry> <para>User maintainance; create/delete/view users, change passwords etc</para> </entry>
+          <entry> <para>permissionable at broker level only</para> </entry>
+        </row>
+        <row>
+          <entry> <command>ConfigurationManagement</command> </entry>
+          <entry> <para>Dynammically reload configuration from disk.</para> </entry>
+          <entry> <para>permissionable at broker level only</para> </entry>
+        </row>
+        <row>
+          <entry> <command>LoggingManagement</command> </entry>
+          <entry> <para>Dynammically control Qpid logging level</para> </entry>
+          <entry> <para>permissionable at broker level only</para> </entry>
+        </row>
+        <row>
+          <entry> <command>ServerInformation</command> </entry>
+          <entry> <para>Read-only information regarding the Qpid: version number etc</para> </entry>
+          <entry> <para>permissionable at broker level only</para> </entry>
+        </row>
+        <row>
+          <entry> <command>VirtualHost.Queue</command> </entry>
+          <entry> <para>Queue maintainance; copy/move/purge/view etc</para> </entry>
+        </row>
+        <row>
+          <entry> <command>VirtualHost.Exchange</command> </entry>
+          <entry> <para>Exchange maintenance; bind/unbind queues to exchanges</para> </entry>
+        </row>
+        <row>
+          <entry> <command>VirtualHost.VirtualHost</command> </entry>
+          <entry> <para>Virtual host maintainace; create/delete exchanges, queues etc</para> </entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+  <section role="h4" id="Java-Broker-Security-ACLs-WorkedExamples">
+    <title>
+      Worked Examples
+    </title>
+    <para>
+      Here are some example ACLs illustrating common use cases.
+      In addition, note that the Java broker provides a complete example ACL file, located at etc/broker_example.acl.
+    </para>
+    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample1">
+      <title>
+        Worked example 1 - Management rights
+      </title>
+      <para>
+        Suppose you wish to permission two users: a user 'operator' must be able to perform all Management operations, and
+        a user 'readonly' must be enable to perform only read-only functions.  Neither 'operator' nor 'readonly'
+        should be allowed to connect clients for messaging.
+      </para>
+      <programlisting>
+# Deny (loggged) operator/readonly permission to connect messaging clients.
+ACL DENY-LOG operator ACCESS VIRTUALHOST
+ACL DENY-LOG readonly ACCESS VIRTUALHOST
+# Give operator permission to perfom all other actions
+ACL ALLOW operator ALL ALL
+# Give readonly permission to execute only read-only actions
+ACL ALLOW readonly ACCESS ALL
+...
+... rules for other users
+...
+# Explicitly deny all (log) to eveyone
+ACL DENY-LOG ALL ALL
+      </programlisting>
+    </section>
+    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample2">
+      <title>
+        Worked example 2 - User maintainer group
+      </title>
+      <para>
+        Suppose you wish to restrict User Management operations to users belonging to a
+        <link linkend="Java-Broker-Security-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>
+# Give usermaint access to management and permission to execute all JMX Methods on the
+# UserManagement MBean and perform all actions for USER objects
+ACL ALLOW usermaint ACCESS MANAGEMENT
+ACL ALLOW usermaint ALL METHOD component="UserManagement"
+ACL ALLOW usermaint ALL USER
+ACL DENY ALL ALL METHOD component="UserManagement"
+ACL DENY ALL ALL USER
+...
+... rules for other users
+...
+ACL DENY-LOG ALL ALL
+      </programlisting>
+    </section>
+    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample3">
+      <title>
+        Worked example 3 - Request/Response messaging
+      </title>
+      <para>
+        Suppose you wish to permission a system using a request/response paradigm. Two users: 'client' publishes requests;
+        'server' consumes the requests and generates a response.  This example illustrates the permissioning of AMQP exchanges
+        and queues.
+      </para>
+      <programlisting>
+# Allow client and server to connect to the virtual host.
+ACL ALLOW client ACCESS VIRTUALHOST
+ACL ALLOW server ACCESS VIRTUALHOST
+
+# Client side
+# Allow the 'client' user to publish requests to the request queue. As is the norm for the request/response paradigm, the client
+# is required to create a temporary queue on which the server will respond.  Consequently, there are rules to allow the creation
+# of the temporary queues and consumption of messages from it.
+ACL ALLOW client CREATE QUEUE temporary="true"
+ACL ALLOW client CONSUME QUEUE temporary="true"
+ACL ALLOW client DELETE QUEUE temporary="true"
+ACL ALLOW client BIND EXCHANGE name="amq.direct" temporary="true"
+ACL ALLOW client UNBIND EXCHANGE name="amq.direct" temporary="true"
+ACL ALLOW client PUBLISH EXCHANGE name="amq.direct" routingKey="example.RequestQueue"
+
+# Server side
+# Allow the 'server' user to consume from the request queue and publish a response to the temporary response queue created by
+# client.  We also allow the server to create the request queue.
+ACL ALLOW server CREATE QUEUE name="example.RequestQueue"
+ACL ALLOW server CONSUME QUEUE name="example.RequestQueue"
+ACL ALLOW server BIND EXCHANGE
+ACL ALLOW server PUBLISH EXCHANGE name="amq.direct" routingKey="TempQueue*"
+
+ACL DENY-LOG all all
+      </programlisting>
+    </section>
+    <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample4">
+      <title>
+        Worked example 4 - firewall-like access control
+      </title>
+      <para>
+        This example illustrates how to set up an ACL that restricts the IP addresses and hostnames
+        of messaging clients that can access a virtual host.
+      </para>
+      <programlisting>
+################
+# Hostname rules
+################
+
+# Allow messaging clients from company1.com and company1.co.uk to connect
+ACL ALLOW all ACCESS VIRTUALHOST from_hostname=".*\.company1\.com,.*\.company1\.co\.uk"
+
+# Deny messaging clients from hosts within the dev subdomain
+ACL DENY-LOG all ACCESS VIRTUALHOST from_hostname=".*\.dev\.company1\.com"
+
+##################
+# IP address rules
+##################
+
+# Deny access to all users in the IP ranges 192.168.1.0-192.168.1.255 and 192.168.2.0-192.168.2.255,
+# using the notation specified in RFC 4632, "Classless Inter-domain Routing (CIDR)"
+ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
+  from_network="192.168.1.0/24,192.168.2.0/24"
+
+# Deny access to all users in the IP ranges 192.169.1.0-192.169.1.255 and 192.169.2.0-192.169.2.255,
+# using wildcard notation.
+ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \
+  from_network="192.169.1.*,192.169.2.*"
+
+ACL DENY-LOG all all
+      </programlisting>
+    </section>
+  </section>
+</section>