You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ro...@apache.org on 2012/08/12 21:19:53 UTC
svn commit: r1372183 [7/19] - in /qpid/site/docs/books/trunk_new: ./
AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html/
AMQP-Messaging-Broker-CPP-Book/html/css/
AMQP-Messaging-Broker-CPP-Book/html/images/ AMQP-Messaging-Broker-CPP-Boo...
Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/html/queue-state-replication.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/html/queue-state-replication.html?rev=1372183&view=auto
==============================================================================
--- qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/html/queue-state-replication.html (added)
+++ qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/html/queue-state-replication.html Sun Aug 12 19:19:49 2012
@@ -0,0 +1,227 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>1.7. Queue State Replication</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Implemented in C++)"><link rel="up" href="ch01.html" title="Chapter 1. Running the AMQP Messaging Broker"><link rel="prev" href="ch01s06.html" title="1.6. LVQ - Last Value Queue"><link rel="next" href="chap-Messaging_User_Guide-Active_Active_Cluster.html" title="1.8. Active-active Messaging Clusters"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpidâ¢</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apac
he.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></L
I><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><U
L><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Implemented in C++)</a></span> > <span class="breadcrumb-link"><a href="ch01.html">
+ Running the AMQP Messaging Broker
+ </a></span> > <span class="breadcrumb-node">
+ Queue State Replication
+ </span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="queue-state-replication"></a>1.7.Â
+ Queue State Replication
+ </h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="queuestatereplication-AsynchronousReplicationofQueueState"></a>1.7.1.Â
+ Asynchronous
+ Replication of Queue State
+ </h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-Overview"></a>1.7.1.1.Â
+ Overview
+ </h4></div></div></div><p>
+ There is support in qpidd for selective asynchronous replication
+ of queue state. This is achieved by:
+ </p><p>
+ (a) enabling event generation for the queues in question
+ </p><p>
+ (b) loading a plugin on the 'source' broker to encode those
+ events as messages on a replication queue (this plugin is
+ called
+ replicating_listener.so)
+ </p><p>
+ (c) loading a custom exchange plugin on the 'backup' broker (this
+ plugin is called replication_exchange.so)
+ </p><p>
+ (d) creating an instance of the replication exchange type on the
+ backup broker
+ </p><p>
+ (e) establishing a federation bridge between the replication
+ queue on the source broker and the replication exchange on the
+ backup broker
+ </p><p>
+ The bridge established between the source and backup brokers for
+ replication (step (e) above) should have acknowledgements turned
+ on (this may be done through the --ack N option to qpid-route).
+ This ensures that replication events are not lost if the bridge
+ fails.
+ </p><p>
+ The replication protocol will also eliminate duplicates to ensure
+ reliably replicated state. Note though that only one bridge per
+ replication exchange is supported. If clients try to publish to
+ the replication exchange or if more than a the single required
+ bridge from the replication queue on the source broker is
+ created, replication will be corrupted. (Access control may be
+ used to restrict access and help prevent this).
+ </p><p>
+ The replicating event listener plugin (step (b) above) has the
+ following options:
+ </p><pre class="programlisting">
+Queue Replication Options:
+ --replication-queue QUEUE Queue on which events for
+ other queues are recorded
+ --replication-listener-name NAME (replicator) name by which to register the
+ replicating event listener
+ --create-replication-queue if set, the replication will
+ be created if it does not
+ exist
+ </pre><p>
+ The name of the queue is required. It can either point to a
+ durable queue whose definition has been previously recorded, or
+ the --create-replication-queue option can be specified in which
+ case the queue will be created a simple non-durable queue if it
+ does not already exist.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-UsewithClustering"></a>1.7.1.2.Â
+ Use with
+ Clustering
+ </h4></div></div></div><p>
+ The source and/or backup brokers may also be clustered brokers.
+ In this case the federated bridge will be re-established between
+ replicas should either of the originally connected nodes fail.
+ There are however the following limitations at present:
+ </p><div class="itemizedlist"><ul><li><p>The backup site does not process membership updates after it
+ establishes the first connection. In order for newly added
+ members on a source cluster to be eligible as failover targets,
+ the bridge must be recreated after those members have been added
+ to the source cluster.
+ </p></li></ul></div><div class="itemizedlist"><ul><li><p>New members added to a backup cluster will not receive
+ information about currently established bridges. Therefore in
+ order to allow the bridge to be re-established from these members
+ in the event of failure of older nodes, the bridge must be
+ recreated after the new members have joined.
+ </p></li></ul></div><div class="itemizedlist"><ul><li><p>Only a single URL can be passed to create the initial link
+ from backup site to the primary site. this means that at the time
+ of creating the initial connection the initial node in the
+ primary site to which the connection is made needs to be running.
+ Once connected the backup site will receive a membership update
+ of all the nodes in the primary site, and if the initial
+ connection node in the primary fails, the link will be
+ re-established on the next node that was started (time) on the
+ primary site.
+ </p></li></ul></div><p>
+ Due to the acknowledged transfer of events over the bridge (see
+ note above) manual recreation of the bridge and automatic
+ re-establishment of te bridge after connection failure (including
+ failover where either or both ends are clustered brokers) will
+ not result in event loss.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-OperationsonBackupQueues"></a>1.7.1.3.Â
+ Operations
+ on Backup Queues
+ </h4></div></div></div><p>
+ When replicating the state of a queue to a backup broker it is
+ important to recognise that any other operations performed
+ directly on the backup queue may break the replication.
+ </p><p>
+ If the backup queue is to be an active (i.e. accessed by clients
+ while replication is on) only enqueues should be selected
+ for
+ replication. In this mode, any message enqueued on the source
+ brokers copy of the queue will also be enqueued on the backup
+ brokers copy. However not attempt will be made to remove messages
+ from the backup queue in response to removal of messages from the
+ source queue.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-SelectingQueuesforReplication"></a>1.7.1.4.Â
+ Selecting
+ Queues for Replication
+ </h4></div></div></div><p>
+ Queues are selected for replication by specifying the types of
+ events they should generate (it is from these events that the
+ replicating plugin constructs messages which are then pulled and
+ processed by the backup site). This is done through options
+ passed to the initial queue-declare command that creates the
+ queue and may be done either through qpid-config or similar
+ tools, or by the application.
+ </p><p>
+ With qpid-config, the --generate-queue-events options is used:
+ </p><pre class="programlisting">
+ --generate-queue-events N
+ If set to 1, every enqueue will generate an event that can be processed by
+ registered listeners (e.g. for replication). If set to 2, events will be
+ generated for enqueues and dequeues
+ </pre><p>
+ From an application, the arguments field of the queue-declare
+ AMQP command is used to convey this information. An entry should
+ be added to the map with key 'qpid.queue_event_generation' and an
+ integer value of 1 (to replicate only enqueue events) or 2 (to
+ replicate both enqueue and dequeue events).
+ </p><p>
+ Applications written using the c++ client API may fine the
+ qpid::client::QueueOptions class convenient. This has a
+ enableQueueEvents() method on it that can be used to set the
+ option (the instance of QueueOptions is then passed as the value
+ of the arguments field in the queue-declare command. The boolean
+ option to that method should be set to true if only enequeue
+ events should be replicated; by default it is false meaning that
+ both enqueues and dequeues will be replicated. E.g.
+ </p><pre class="programlisting">
+ QueueOptions options;
+ options.enableQueueEvents(false);
+ session.queueDeclare(arg::queue="my-queue", arg::arguments=options);
+ </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-Example"></a>1.7.1.5.Â
+ Example
+ </h4></div></div></div><p>
+ Lets assume we will run the primary broker on host1 and the
+ backup on host2, have installed qpidd on both and have the
+ replicating_listener and replication_exchange plugins in qpidd's
+ module directory(*1).
+ </p><p>
+ On host1 we start the source broker and specifcy that a queue
+ called 'replication' should be used for storing the events until
+ consumed by the backup. We also request that this queue be
+ created (as transient) if not already specified:
+ </p><pre class="programlisting">
+ qpidd --replication-queue replication-queue --create-replication-queue true --log-enable info+
+ </pre><p>
+ On host2 we start up the backup broker ensuring that the
+ replication exchange module is loaded:
+ </p><pre class="programlisting">
+ qpidd
+ </pre><p>
+ We can then create the instance of that replication exchange that
+ we will use to process the events:
+ </p><pre class="programlisting">
+ qpid-config -a host2 add exchange replication replication-exchange
+ </pre><p>
+ If this fails with the message "Exchange type not implemented:
+ replication", it means the replication exchange module was
+ not
+ loaded. Check that the module is installed on your system and if
+ necessary provide the full path to the library.
+ </p><p>
+ We then connect the replication queue on the source broker with
+ the replication exchange on the backup broker using the
+ qpid-route command:
+ </p><pre class="programlisting">
+ qpid-route --ack 50 queue add host2 host1 replication-exchange replication-queue
+</pre><p>
+ The example above configures the bridge to acknowledge messages
+ in batches of 50.
+ </p><p>
+ Now create two queues (on both source and backup brokers), one
+ replicating both enqueues and dequeues (queue-a) and the
+ other
+ replicating only dequeues (queue-b):
+ </p><pre class="programlisting">
+ qpid-config -a host1 add queue queue-a --generate-queue-events 2
+ qpid-config -a host1 add queue queue-b --generate-queue-events 1
+
+ qpid-config -a host2 add queue queue-a
+ qpid-config -a host2 add queue queue-b
+ </pre><p>
+ We are now ready to use the queues and see the replication.
+ </p><p>
+ Any message enqueued on queue-a will be replicated to the backup
+ broker. When the message is acknowledged by a client connected to
+ host1 (and thus dequeued), that message will be removed from the
+ copy of the queue on host2. The state of queue-a on host2 will
+ thus mirror that of the equivalent queue on host1, albeit with a
+ small lag. (Note
+ however that we must not have clients connected to host2 publish
+ to-or consume from- queue-a or the state will fail to replicate
+ correctly due to conflicts).
+ </p><p>
+ Any message enqueued on queue-b on host1 will also be enqueued on
+ the equivalent queue on host2. However the acknowledgement and
+ consequent dequeuing of messages from queue-b on host1 will have
+ no effect on the state of queue-b on host2.
+ </p><p>
+ (*1) If not the paths in the above may need to be modified. E.g.
+ if using modules built from a qpid svn checkout, the following
+ would be added to the command line used to start qpidd on host1:
+ </p><pre class="programlisting">
+ --load-module <path-to-qpid-dir>/src/.libs/replicating_listener.so
+ </pre><p>
+ and the following for the equivalent command line on host2:
+ </p><pre class="programlisting">
+ --load-module <path-to-qpid-dir>/src/.libs/replication_exchange.so
+ </pre></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="chap-Messaging_User_Guide-Active_Active_Cluster.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.6. LVQ - Last Value Queue </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.8. Active-active Messaging Clusters</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>
Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/pdf/AMQP-Messaging-Broker-CPP-Book.pdf
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/pdf/AMQP-Messaging-Broker-CPP-Book.pdf?rev=1372183&view=auto
==============================================================================
Binary file - no diff available.
Propchange: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-CPP-Book/pdf/AMQP-Messaging-Broker-CPP-Book.pdf
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html?rev=1372183&view=auto
==============================================================================
--- qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html (added)
+++ qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Configuring-ACLS.html Sun Aug 12 19:19:49 2012
@@ -0,0 +1,163 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>2.2. Configuring ACLs</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="next" href="Qpid-Java-SSL.html" title="2.3. Configure Java Qpid to use a SSL connection."></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpidâ¢</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</
A></LI><LI><A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpi
d.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www
.apache.org">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Implemented in Java)</a></span> > <span class="breadcrumb-link"><a href="Qpid-Java-Broker-HowTos.html">How Tos</a></span> > <span class="breadcrumb-node">
+ Configuring ACLs
+ </span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Configuring-ACLS"></a>2.2.Â
+ Configuring ACLs
+ </h2></div></div></div><p>
+ In Qpid, ACLs specify which actions can be performed by each authenticated user. To enable the ACL <acl/> element is used within the
+ <security/> element of the configuration XML. In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual
+ hosts. The <acl/> references a text file containing the ACL rules. By convention, this file should have a .acl extension.
+ </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-EnablingACL"></a>2.2.1.Â
+ Enabling ACLs
+ </h3></div></div></div><p>
+ To apply an ACL broker-wide, add the following to the config.xml (Assuming that <em class="replaceable"><code>conf</code></em> has been set to a suitable
+ location such as ${QPID_HOME}/etc)
+ </p><pre class="programlisting">
+ <broker>
+ ...
+ <security>
+ ...
+ <acl><em class="replaceable"><code>${conf}/broker.acl</code></em></acl>
+ </security>
+ </broker>
+ </pre><p>
+ </p><p>
+ To apply an ACL on a single virtualhost named <em class="replaceable"><code>test</code></em>, add the following to the config.xml:
+ </p><pre class="programlisting">
+ <virtualhost>
+ ...
+ <name>test</name>
+ <test>
+ ...
+ <security>
+ <acl><em class="replaceable"><code>${conf}/vhost_test.acl</code></em></acl>
+ </security>
+ </test>
+ </virtualhost>
+ </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-WriteACL"></a>2.2.2.Â
+ Writing .acl files
+ </h3></div></div></div><p>
+ 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.
+ </p><p>
+ 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
+ the rule's applicability.
+ </p><pre class="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"
+ </pre><p>
+ 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.
+ </p><pre class="programlisting">
+ ACL ALLOW bob ALL EXCHANGE
+ ACL DENY bob CREATE EXCHANGE name="myexch" # Dead rule
+ </pre><p>
+ If the desire is to allow bob to create all exchanges except "myexch", order of the rules must be reversed:
+ </p><pre class="programlisting">
+ ACL DENY bob CREATE EXCHANGE name="myexch"
+ ACL ALLOW bob ALL EXCHANGE
+ </pre><p>
+ All ACL files end with a implict rule denying all operations to all users. It is as if each file ends with
+ </p><pre class="programlisting">ACL DENY ALL ALL </pre><p>
+ To allow all operations, other than those controlled by earlier use </p><pre class="programlisting">ACL ALLOW ALL ALL </pre><p> instead.
+ </p><p>
+ When writing a new ACL, a good approach is to begin with an .acl file containing only </p><pre class="programlisting">ACL DENY-LOG ALL ALL</pre><p>
+ 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, switch the DEBY-LOG to DENY for optimum performamce.
+ </p><p>
+ ACL rules are very powerful: it is possible to write very expressive rules permissioning every AMQP objects enumerating all object
+ 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 (i.e. QUEUE) and apply consistently across the whole system.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-Syntax"></a>2.2.3.Â
+ Syntax
+ </h3></div></div></div><p>
+ ACL rules must follow this syntax:
+ </p><pre class="programlisting">
+ ACL {permission} {<group-name>|<user-name>>|ALL} {action|ALL} [object|ALL] [property="<property-value>"]
+ </pre><p>
+ GROUP definitions must follow this syntax:
+ </p><pre class="programlisting">
+ GROUP {group name} {username 1}..{username n} # Where username is a username, or a groupname.
+ </pre><p>
+ Comments may be introduced with the hash (#) character and are ignored. Long lines can be broken with the slash (\) character.
+ </p><pre class="programlisting">
+ # A comment
+ ACL ALLOW admin CREATE ALL # Also a comment
+ ACL DENY guest \
+ ALL ALL # A broken line
+ GROUP securegroup bob \
+ alice # Another broker line
+ </pre></div><div class="table"><a name="tabl-ConfigureACLs-Syntax_permissions"></a><p class="title"><b>Table 2.2. ACL Rules: permission</b></p><div class="table-contents"><table summary="ACL Rules: permission" border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="command"><strong>ALLOW</strong></span></td><td><p>Allow the action</p></td></tr><tr><td><span class="command"><strong>ALLOW-LOG</strong></span></td><td><p> Allow the action and log the action in the log </p></td></tr><tr><td><span class="command"><strong>DENY</strong></span></td><td><p> Deny the action</p></td></tr><tr><td><span class="command"><strong>DENY-LOG</strong></span></td><td><p> Deny the action and log the action in the log</p></td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-ConfigureACLs-Syntax_actions"></a><p class="title"><b>Table 2.3. ACL Rules:action</b></p><div class="table-contents"><table summary="ACL Rules:action" border
="1"><colgroup><col><col></colgroup><tbody><tr><td> <span class="command"><strong>CONSUME</strong></span> </td><td> <p> Applied when subscriptions are created </p> </td></tr><tr><td> <span class="command"><strong>PUBLISH</strong></span> </td><td> <p> Applied on a per message basis on publish message transfers</p> </td></tr><tr><td> <span class="command"><strong>CREATE</strong></span> </td><td> <p> Applied when an object is created, such as bindings, queues, exchanges</p> </td></tr><tr><td> <span class="command"><strong>ACCESS</strong></span> </td><td> <p> Applied when an object is read or accessed</p> </td></tr><tr><td> <span class="command"><strong>BIND</strong></span> </td><td> <p> Applied when queues are bound to exchanges</p> </td></tr><tr><td> <span class="command"><strong>UNBIND</strong></span> </td><td> <p> Applied when queues are unbound from exchanges</p> </td></tr><tr><td> <span class="command"><strong>DELETE</strong></span> </td><td> <p> Applied when objects are d
eleted </p> </td></tr><tr><td> <span class="command"><strong>PURGE</strong></span> </td><td>
+ <p>Applied when purge the contents of a queue</p> </td></tr><tr><td> <span class="command"><strong>UPDATE</strong></span> </td><td> <p> Applied when an object is updated </p> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-ConfigureACLs-Syntax_objects"></a><p class="title"><b>Table 2.4. ACL Rules:object</b></p><div class="table-contents"><table summary="ACL Rules:object" border="1"><colgroup><col><col></colgroup><tbody><tr><td> <span class="command"><strong>QUEUE</strong></span> </td><td> <p> A queue </p> </td></tr><tr><td> <span class="command"><strong>EXCHANGE</strong></span> </td><td> <p> An exchange </p> </td></tr><tr><td> <span class="command"><strong>VIRTUALHOST</strong></span> </td><td> <p> A virtualhost (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>METHOD</strong></span> </td><td> <p> Management or agent or broker method (Java Broker only)</p> </td></tr><tr><td> <span class="comm
and"><strong>BROKER</strong></span> </td><td> <p> The broker (not currently used in Java Broker)</p> </td></tr><tr><td> <span class="command"><strong>LINK</strong></span> </td><td> <p> A federation or inter-broker link (not currently used in Java Broker)</p> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-ConfigureACLs-Syntax_properties"></a><p class="title"><b>Table 2.5. ACL Rules:property</b></p><div class="table-contents"><table summary="ACL Rules:property" border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="command"><strong>name</strong></span> </td><td> <p> String. Object name, such as a queue name, exchange name or JMX method name. </p> </td></tr><tr><td> <span class="command"><strong>durable</strong></span> </td><td> <p> Boolean. Indicates the object is durable </p> </td></tr><tr><td> <span class="command"><strong>routingkey</strong></span> </td><td> <p> String. Specifies routing key </p> </td></t
r><tr><td> <span class="command"><strong>passive</strong></span> </td><td> <p> Boolean. Indicates the presence of a <em class="parameter"><code>passive</code></em> flag </p> </td></tr><tr><td> <span class="command"><strong>autodelete</strong></span> </td><td> <p> Boolean. Indicates whether or not the object gets deleted when the connection is closed </p> </td></tr><tr><td> <span class="command"><strong>exclusive</strong></span> </td><td> <p> Boolean. Indicates the presence of an <em class="parameter"><code>exclusive</code></em> flag </p> </td></tr><tr><td> <span class="command"><strong>temporary</strong></span> </td><td> <p> Boolean. Indicates the presence of an <em class="parameter"><code>temporary</code></em> flag </p> </td></tr><tr><td> <span class="command"><strong>type</strong></span> </td><td> <p> String. Type of object, such as topic, fanout, or xml </p> </td></tr><tr><td> <span class="command"><strong>alternate</strong></span> </td><td> <p> String. Name of the altern
ate exchange </p> </td></tr><tr><td> <span class="command"><strong>queuename</strong></span> </td><td> <p> String. Name of the queue (used only when the object is something other than <em class="parameter"><code>queue</code></em> </p> </td></tr><tr><td> <span class="command"><strong>component</strong></span> </td><td> <p> String. JMX component name (Java Broker only)</p> </td></tr><tr><td> <span class="command"><strong>schemapackage</strong></span> </td><td> <p> String. QMF schema package name (Not used in Java Broker)</p> </td></tr><tr><td> <span class="command"><strong>schemaclass</strong></span> </td><td> <p> String. QMF schema class name (Not used in Java Broker)</p> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-ConfigureACLs-Syntax_javacomponents"></a><p class="title"><b>Table 2.6. ACL rules:components (Java Broker only)</b></p><div class="table-contents"><table summary="ACL rules:components (Java Broker only)" bord
er="1"><colgroup><col><col><col></colgroup><tbody><tr><td> <span class="command"><strong>UserManagement</strong></span> </td><td> <p>User maintainance; create/delete/view users, change passwords etc</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>ConfigurationManagement</strong></span> </td><td> <p>Dynammically reload configuration from disk.</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>LoggingManagement</strong></span> </td><td> <p>Dynammically control Qpid logging level</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>ServerInformation</strong></span> </td><td> <p>Read-only information regarding the Qpid: version number etc</p> </td><td> <p>permissionable at broker level only</p> </td></tr><tr><td> <span class="command"><strong>VirtualHost.Queue</strong></span> </td><td> <p>Queue maintainance; copy/m
ove/purge/view etc</p> </td><td class="auto-generated">Â </td></tr><tr><td> <span class="command"><strong>VirtualHost.Exchange</strong></span> </td><td> <p>Exchange maintenance; bind/unbind queues to exchanges</p> </td><td class="auto-generated">Â </td></tr><tr><td> <span class="command"><strong>VirtualHost.VirtualHost</strong></span> </td><td> <p>Virtual host maintainace; create/delete exchanges, queues etc</p> </td><td class="auto-generated">Â </td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-WorkedExamples"></a>2.2.4.Â
+ Worked Examples
+ </h3></div></div></div><p>
+ Here are three example ACLs illustrating some common use-cases.
+ </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample1"></a>2.2.4.1.Â
+ Worked example 1 - Management rights
+ </h4></div></div></div><p>
+ 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 allow to connect for messaging.
+ </p><pre class="programlisting">
+ # Give operator permission to execute all JMX Methods
+ ACL ALLOW operator ALL METHOD
+ # Give operator permission to execute only read-only JMX Methods
+ ACL ALLOW readonly ACCESS METHOD
+ # Deny operator/readonly permission to perform messaging.
+ ACL DENY operator ACCESS VIRTUALHOST
+ ACL DENY readonly ACCESS VIRTUALHOST
+ ...
+ ... rules for other users
+ ...
+ # Explicitly deny all (log) to eveyone
+ ACL DENY-LOG ALL ALL
+ </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample2"></a>2.2.4.2.Â
+ Worked example 2 - User maintainer group
+ </h4></div></div></div><p>
+ 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.
+ </p><pre class="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"
+ ...
+ ... rules for other users
+ ...
+ ACL DENY-LOG ALL ALL
+ </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-WorkedExample3"></a>2.2.4.3.Â
+ Worked example 3 - Request/Response messaging
+ </h4></div></div></div><p>
+ 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.
+ </p><pre class="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 response. 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
+ </pre></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Broker-HowTos.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-SSL.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. How Tos </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.3.Â
+ Configure Java Qpid to use a SSL connection.
+ </td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org