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:03:53 UTC
svn commit: r1372179 [5/18] - in /qpid/site/docs/books/0.18: ./
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-Book/pdf...
Added: qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Broker_Federation.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Broker_Federation.html?rev=1372179&view=auto
==============================================================================
--- qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Broker_Federation.html (added)
+++ qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Broker_Federation.html Sun Aug 12 19:03:49 2012
@@ -0,0 +1,320 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>1.4. Broker Federation</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="ch01s03.html" title="1.3. Cheat Sheet for configuring Exchange Options"><link rel="next" href="chap-Messaging_User_Guide-Security.html" title="1.5. Security"></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">Ho
me</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:/
/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><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 C++)</a></span> > <span class="breadcrumb-link"><a href="ch01.html">
+ Running the AMQP Messaging Broker
+ </a></span> > <span class="breadcrumb-node">Broker Federation</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap-Messaging_User_Guide-Broker_Federation"></a>1.4. Broker Federation</h2></div></div></div><p>
+ <em class="firstterm">Broker Federation</em> allows messaging networks to be defined by creating <em class="firstterm">message routes</em>, in which messages in one broker (the <em class="firstterm">source broker</em>) are automatically routed to another broker (the <em class="firstterm">destination broker</em>). These routes may be defined between exchanges in the two brokers (the <em class="firstterm">source exchange</em> and the <em class="firstterm">destination exchange</em>), or from a queue in the source broker (the <em class="firstterm">source queue</em>) to an exchange in the destination broker. Message routes are unidirectional; when bidirectional flow is needed, one route is created in each direction. Routes can be durable or transient. A durable route survives broker restarts, restoring a route as soon as both the source broker and the destination are available. If the connection to a destination is lost, messages associated with a durable route continue to accu
mulate on the source, so they can be retrieved when the connection is reestablished.
+ </p><p>
+ Broker Federation can be used to build large messaging networks, with many brokers, one route at a time. If network connectivity permits, an entire distributed messaging network can be configured from a single location. The rules used for routing can be changed dynamically as servers change, responsibilities change, at different times of day, or to reflect other changing conditions.
+ </p><p>
+ Broker Federation is useful in a wide variety of scenarios. Some of these have to do with functional organization; for instance, brokers may be organized by geography, service type, or priority. Here are some use cases for federation:
+ </p><div class="itemizedlist"><ul><li><p>
+ Geography: Customer requests may be routed to a processing location close to the customer.
+ </p></li><li><p>
+ Service Type: High value customers may be routed to more responsive servers.
+ </p></li><li><p>
+ Load balancing: Routing among brokers may be changed dynamically to account for changes in actual or anticipated load.
+ </p></li><li><p>
+ High Availability: Routing may be changed to a new broker if an existing broker becomes unavailable.
+ </p></li><li><p>
+ WAN Connectivity: Federated routes may connect disparate locations across a wide area network, while clients connect to brokers on their own local area network. Each broker can provide persistent queues that can hold messages even if there are gaps in WAN connectivity.
+ </p></li><li><p>
+ Functional Organization: The flow of messages among software subsystems can be configured to mirror the logical structure of a distributed application.
+ </p></li><li><p>
+ Replicated Exchanges: High-function exchanges like the XML exchange can be replicated to scale performance.
+ </p></li><li><p>
+ Interdepartmental Workflow: The flow of messages among brokers can be configured to mirror interdepartmental workflow at an organization.
+ </p></li></ul></div><p>
+
+ </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Broker_Federation-Message_Routes"></a>1.4.1. Message Routes</h3></div></div></div><p>
+ Broker Federation is done by creating message routes. The destination for a route is always an exchange on the destination broker. By default, a message route is created by configuring the destination broker, which then contacts the source broker to subscribe to the source queue. This is called a <em class="firstterm">pull route</em>. It is also possible to create a route by configuring the source broker, which then contacts the destination broker in order to send messages. This is called a <em class="firstterm">push route</em>, and is particularly useful when the destination broker may not be available at the time the messaging route is configured, or when a large number of routes are created with the same destination exchange.
+ </p><p>
+ The source for a route can be either an exchange or a queue on the source broker. If a route is between two exchanges, the routing criteria can be given explicitly, or the bindings of the destination exchange can be used to determine the routing criteria. To support this functionality, there are three kinds of message routes: queue routes, exchange routes, and dynamic exchange routes.
+ </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Message_Routes-Queue_Routes"></a>1.4.1.1. Queue Routes</h4></div></div></div><p>
+ <em class="firstterm">Queue Routes</em> route all messages from a source queue to a destination exchange. If message acknowledgement is enabled, messages are removed from the queue when they have been received by the destination exchange; if message acknowledgement is off, messages are removed from the queue when sent.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Message_Routes-Exchange_Routes"></a>1.4.1.2. Exchange Routes</h4></div></div></div><p>
+ <em class="firstterm">Exchange routes</em> route messages from a source exchange to a destination exchange, using a binding key (which is optional for a fanout exchange).
+ </p><p>
+ Internally, creating an exchange route creates a private queue (auto-delete, exclusive) on the source broker to hold messages that are to be routed to the destination broker, binds this private queue to the source broker exchange, and subscribes the destination broker to the queue.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Message_Routes-Dynamic_Exchange_Routes"></a>1.4.1.3. Dynamic Exchange Routes</h4></div></div></div><p>
+ Dynamic exchange routes allow a client to create bindings to an exchange on one broker, and receive messages that satisfy the conditions of these bindings not only from the exchange to which the client created the binding, but also from other exchanges that are connected to it using dynamic exchange routes. If the client modifies the bindings for a given exchange, they are also modified for dynamic exchange routes associated with that exchange.
+ </p><p>
+ <em class="firstterm">Dynamic exchange routes</em> apply all the bindings of a destination exchange to a source exchange, so that any message that would match one of these bindings is routed to the destination exchange. If bindings are added or removed from the destination exchange, these changes are reflected in the dynamic exchange route -- when the destination broker creates a binding with a given binding key, this is reflected in the route, and when the destination broker drops a binding with a binding key, the route no longer incurs the overhead of transferring messages that match the binding key among brokers. If two exchanges have dynamic exchange routes to each other, then all bindings in each exchange are reflected in the dynamic exchange route of the other. In a dynamic exchange route, the source and destination exchanges must have the same exchange type, and they must have the same name; for instance, if the source exchange is a direct exchange, the destinatio
n exchange must also be a direct exchange, and the names must match.
+ </p><p>
+ Internally, dynamic exchange routes are implemented in the same way as exchange routes, except that the bindings used to implement dynamic exchange routes are modified if the bindings in the destination exchange change.
+ </p><p>
+ A dynamic exchange route is always a pull route. It can never be a push route.
+ </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies"></a>1.4.2. Federation Topologies</h3></div></div></div><p>
+ A federated network is generally a tree, star, or line, using bidirectional links (implemented as a pair of unidirectional links) between any two brokers. A ring topology is also possible, if only unidirectional links are used.
+ </p><p>
+ Every message transfer takes time. For better performance, you should minimize the number of brokers between the message origin and final destination. In most cases, tree or star topologies do this best.
+ </p><p>
+ For any pair of nodes A,B in a federated network, there should be only one path from A to B. If there is more than one path, message loops can cause duplicate message transmission and flood the federated network. The topologies discussed above do not have message loops. A ring topology with bidirectional links is one example of a topology that does cause this problem, because a given broker can receive the same message from two different brokers. Mesh topologies can also cause this problem.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters"></a>1.4.3. Federation among High Availability Message Clusters</h3></div></div></div><p>
+ Federation is generally used together with High Availability Message Clusters, using clusters to provide high availability on each LAN, and federation to route messages among the clusters. Because message state is replicated within a cluster, it makes little sense to define message routes between brokers in the same cluster.
+ </p><p>
+ To create a message route between two clusters, simply create a route between any one broker in the first cluster and any one broker in the second cluster. Each broker in a given cluster can use message routes defined for another broker in the same cluster. If the broker for which a message route is defined should fail, another broker in the same cluster can restore the message route.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility"></a>1.4.4. The qpid-route Utility</h3></div></div></div><p>
+ <span class="command"><strong>qpid-route</strong></span> is a command line utility used to configure federated networks of brokers and to view the status and topology of networks. It can be used to configure routes among any brokers that <span class="command"><strong>qpid-route</strong></span> can connect to.
+ </p><p>
+ The syntax of <span class="command"><strong>qpid-route</strong></span> is as follows:
+ </p><pre class="screen">
+qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange>
+qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange>
+
+qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key>
+qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key>
+
+qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue>
+qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue>
+
+qpid-route [OPTIONS] list [<broker>]
+qpid-route [OPTIONS] flush [<broker>]
+qpid-route [OPTIONS] map [<broker>]
+
+
+qpid-route [OPTIONS] list connections [<broker>]
+</pre><p>
+ The syntax for <span class="command"><strong>broker</strong></span>, <span class="command"><strong>dest-broker</strong></span>, and <span class="command"><strong>src-broker</strong></span> is as follows:
+ </p><pre class="screen">
+[username/password@] hostname | ip-address [:<port>]
+</pre><p>
+ The following are all valid examples of the above syntax: <span class="command"><strong>localhost</strong></span>, <span class="command"><strong>10.1.1.7:10000</strong></span>, <span class="command"><strong>broker-host:10000</strong></span>, <span class="command"><strong>guest/guest@localhost</strong></span>.
+ </p><p>
+ These are the options for <span class="command"><strong>qpid-route</strong></span>:
+ </p><div class="table"><a name="tabl-Messaging_User_Guide-The_qpid_route_Utility-qpid_route_options"></a><p class="title"><b>Table 1.2. <span class="command">qpid-route</span> options</b></p><div class="table-contents"><table summary="qpid-route options" border="1"><colgroup><col align="left"><col align="left"></colgroup><tbody><tr><td align="left">
+ <span class="command"><strong>-v</strong></span>
+ </td><td align="left">
+ Verbose output.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>-q</strong></span>
+ </td><td align="left">
+ Quiet output, will not print duplicate warnings.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>-d</strong></span>
+ </td><td align="left">
+ Make the route durable.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong> --timeout N</strong></span>
+ </td><td align="left">
+ Maximum time to wait when qpid-route connects to a broker, in seconds. Default is 10 seconds.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>--ack N</strong></span>
+ </td><td align="left">
+ Acknowledge transfers of routed messages in batches of N. Default is 0 (no acknowledgements). Setting to 1 or greater enables acknowledgements; when using acknowledgements, values of N greater than 1 can significnantly improve performance, especially if there is significant network latency between the two brokers.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>-s [ --src-local ]</strong></span>
+ </td><td align="left">
+ Configure the route in the source broker (create a push route).
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>-t <transport> [ --transport <transport>]</strong></span>
+ </td><td align="left">
+ Transport protocol to be used for the route.
+ <div class="itemizedlist"><ul><li><p>
+ tcp (default)
+ </p></li><li><p>
+ ssl
+ </p></li><li><p>
+ rdma
+ </p></li></ul></div>
+
+ </td></tr></tbody></table></div></div><br class="table-break"><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Queue_Routes"></a>1.4.4.1. Creating and Deleting Queue Routes</h4></div></div></div><p>
+ The syntax for creating and deleting queue routes is as follows:
+ </p><pre class="screen">
+qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue>
+qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue>
+</pre><p>
+ For instance, the following creates a queue route that routes all messages from the queue named <span class="command"><strong>public</strong></span> on the source broker <span class="command"><strong>localhost:10002</strong></span> to the <span class="command"><strong>amq.fanout</strong></span> exchange on the destination broker <span class="command"><strong>localhost:10001</strong></span>:
+ </p><pre class="screen">
+$ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public
+</pre><p>
+ If the <span class="command"><strong>-d</strong></span> option is specified, this queue route is persistent, and will be restored if one or both of the brokers is restarted:
+ </p><pre class="screen">
+$ qpid-route -d queue add localhost:10001 localhost:10002 amq.fanout public
+</pre><p>
+ The <span class="command"><strong>del</strong></span> command takes the same arguments as the <span class="command"><strong>add</strong></span> command. The following command deletes the queue route described above:
+ </p><pre class="screen">
+$ qpid-route queue del localhost:10001 localhost:10002 amq.fanout public
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Exchange_Routes"></a>1.4.4.2. Creating and Deleting Exchange Routes</h4></div></div></div><p>
+ The syntax for creating and deleting exchange routes is as follows:
+ </p><pre class="screen">
+qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key>
+qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key>
+qpid-route [OPTIONS] flush [<broker>]
+</pre><p>
+ For instance, the following creates an exchange route that routes messages that match the binding key <span class="command"><strong>global.#</strong></span> from the <span class="command"><strong>amq.topic</strong></span> exchange on the source broker <span class="command"><strong>localhost:10002</strong></span> to the <span class="command"><strong>amq.topic</strong></span> exchange on the destination broker <span class="command"><strong>localhost:10001</strong></span>:
+ </p><pre class="screen">
+$ qpid-route route add localhost:10001 localhost:10002 amq.topic global.#
+</pre><p>
+ In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second exchange route, reversing the roles of the two exchanges:
+ </p><pre class="screen">
+$ qpid-route route add localhost:10002 localhost:10001 amq.topic global.#
+</pre><p>
+ If the <span class="command"><strong>-d</strong></span> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted:
+ </p><pre class="screen">
+$ qpid-route -d route add localhost:10001 localhost:10002 amq.fanout public
+</pre><p>
+ The <span class="command"><strong>del</strong></span> command takes the same arguments as the <span class="command"><strong>add</strong></span> command. The following command deletes the first exchange route described above:
+ </p><pre class="screen">
+$ qpid-route route del localhost:10001 localhost:10002 amq.topic global.#
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Deleting_all_routes_for_a_broker"></a>1.4.4.3. Deleting all routes for a broker</h4></div></div></div><p>
+ Use the <span class="command"><strong>flush</strong></span> command to delete all routes for a given broker:
+ </p><pre class="screen">
+qpid-route [OPTIONS] flush [<broker>]
+</pre><p>
+ For instance, the following command deletes all routes for the broker <span class="command"><strong>localhost:10001</strong></span>:
+ </p><pre class="screen">
+$ qpid-route flush localhost:10001
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Creating_and_Deleting_Dynamic_Exchange_Routes"></a>1.4.4.4. Creating and Deleting Dynamic Exchange Routes</h4></div></div></div><p>
+ The syntax for creating and deleting dynamic exchange routes is as follows:
+ </p><pre class="screen">
+qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange>
+qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange>
+</pre><p>
+ In the following examples, we will route messages from a topic exchange. We will create a new topic exchange and federate it so that we are not affected by other all clients that use the built-in <span class="command"><strong>amq.topic</strong></span> exchange. The following commands create a new topic exchange on each of two brokers:
+ </p><pre class="screen">
+$ qpid-config -a localhost:10003 add exchange topic fed.topic
+$ qpid-config -a localhost:10004 add exchange topic fed.topic
+</pre><p>
+ Now let's create a dynamic exchange route that routes messages from the <span class="command"><strong>fed.topic</strong></span> exchange on the source broker <span class="command"><strong>localhost:10004</strong></span> to the <span class="command"><strong>fed.topic</strong></span> exchange on the destination broker <span class="command"><strong>localhost:10003</strong></span> if they match any binding on the destination broker's <span class="command"><strong>fed.topic</strong></span> exchange:
+ </p><pre class="screen">
+$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
+</pre><p>
+ Internally, this creates a private autodelete queue on the source broker, and binds that queue to the <span class="command"><strong>fed.topic</strong></span> exchange on the source broker, using each binding associated with the <span class="command"><strong>fed.topic</strong></span> exchange on the destination broker.
+ </p><p>
+ In many applications, messages published to the destination exchange should also be routed to the source exchange. This is accomplished by creating a second dynamic exchange route, reversing the roles of the two exchanges:
+ </p><pre class="screen">
+$ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
+</pre><p>
+ If the <span class="command"><strong>-d</strong></span> option is specified, the exchange route is persistent, and will be restored if one or both of the brokers is restarted:
+ </p><pre class="screen">
+$ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic
+</pre><p>
+ When an exchange route is durable, the private queue used to store messages for the route on the source exchange is also durable. If the connection between the brokers is lost, messages for the destination exchange continue to accumulate until it can be restored.
+ </p><p>
+ The <span class="command"><strong>del</strong></span> command takes the same arguments as the <span class="command"><strong>add</strong></span> command. The following command deletes the first exchange route described above:
+ </p><pre class="screen">
+$ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic
+</pre><p>
+ Internally, this deletes the bindings on the source exchange for the the private queues associated with the message route.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Viewing_Routes"></a>1.4.4.5. Viewing Routes</h4></div></div></div><p>
+ The <span class="command"><strong>route list</strong></span> command shows the routes associated with an individual broker. For instance, suppose we have created the following two routes:
+ </p><pre class="screen">
+$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
+$ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
+</pre><p>
+ We can now use <span class="command"><strong>route list</strong></span> to show all routes for the broker <span class="command"><strong>localhost:10003</strong></span>:
+ </p><pre class="screen">
+$ qpid-route route list localhost:10003
+localhost:10003 localhost:10004 fed.topic <dynamic>
+</pre><p>
+ Note that this shows only one of the two routes we created, the route for which <span class="command"><strong>localhost:10003</strong></span> is a destination. If we want to see the route for which <span class="command"><strong>localhost:10004</strong></span> is a destination, we need to do another route list:
+ </p><pre class="screen">
+$ qpid-route route list localhost:10004
+localhost:10004 localhost:10003 fed.topic <dynamic>
+</pre><p>
+ The <span class="command"><strong>route map</strong></span> command shows all routes associated with a broker, and recursively displays all routes for brokers involved in federation relationships with the given broker. For instance, here is the output for the two brokers configured above:
+ </p><pre class="screen">
+$ qpid-route route map localhost:10003
+
+Finding Linked Brokers:
+ localhost:10003... Ok
+ localhost:10004... Ok
+
+Dynamic Routes:
+
+ Exchange fed.topic:
+ localhost:10004 <=> localhost:10003
+
+Static Routes:
+ none found
+</pre><p>
+ Note that the two dynamic exchange links are displayed as though they were one bidirectional link. The <span class="command"><strong>route map</strong></span> command is particularly helpful for larger, more complex networks. Let's configure a somewhat more complex network with 16 dynamic exchange routes:
+ </p><pre class="screen">
+qpid-route dynamic add localhost:10001 localhost:10002 fed.topic
+qpid-route dynamic add localhost:10002 localhost:10001 fed.topic
+
+qpid-route dynamic add localhost:10003 localhost:10002 fed.topic
+qpid-route dynamic add localhost:10002 localhost:10003 fed.topic
+
+qpid-route dynamic add localhost:10004 localhost:10002 fed.topic
+qpid-route dynamic add localhost:10002 localhost:10004 fed.topic
+
+qpid-route dynamic add localhost:10002 localhost:10005 fed.topic
+qpid-route dynamic add localhost:10005 localhost:10002 fed.topic
+
+qpid-route dynamic add localhost:10005 localhost:10006 fed.topic
+qpid-route dynamic add localhost:10006 localhost:10005 fed.topic
+
+qpid-route dynamic add localhost:10006 localhost:10007 fed.topic
+qpid-route dynamic add localhost:10007 localhost:10006 fed.topic
+
+qpid-route dynamic add localhost:10006 localhost:10008 fed.topic
+qpid-route dynamic add localhost:10008 localhost:10006 fed.topic
+</pre><p>
+ Now we can use <span class="command"><strong>route map</strong></span> starting with any one broker, and see the entire network:
+ </p><pre class="screen">
+$ ./qpid-route route map localhost:10001
+
+Finding Linked Brokers:
+ localhost:10001... Ok
+ localhost:10002... Ok
+ localhost:10003... Ok
+ localhost:10004... Ok
+ localhost:10005... Ok
+ localhost:10006... Ok
+ localhost:10007... Ok
+ localhost:10008... Ok
+
+Dynamic Routes:
+
+ Exchange fed.topic:
+ localhost:10002 <=> localhost:10001
+ localhost:10003 <=> localhost:10002
+ localhost:10004 <=> localhost:10002
+ localhost:10005 <=> localhost:10002
+ localhost:10006 <=> localhost:10005
+ localhost:10007 <=> localhost:10006
+ localhost:10008 <=> localhost:10006
+
+Static Routes:
+ none found
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-The_qpid_route_Utility-Resilient_Connections"></a>1.4.4.6. Resilient Connections</h4></div></div></div><p>
+ When a broker route is created, or when a durable broker route is restored after broker restart, a connection is created between the source broker and the destination broker. The connections used between brokers are called <em class="firstterm">resilient connections</em>; if the connection fails due to a communication error, it attempts to reconnect. The retry interval begins at 2 seconds and, as more attempts are made, grows to 64 seconds, and continues to retry every 64 seconds thereafter. If the connection fails due to an authentication problem, it will not continue to retry.
+ </p><p>
+ The command <span class="command"><strong>list connections</strong></span> can be used to show the resilient connections for a broker:
+ </p><pre class="screen">
+$ qpid-route list connections localhost:10001
+
+Host Port Transport Durable State Last Error
+=============================================================================
+localhost 10002 tcp N Operational
+localhost 10003 tcp N Operational
+localhost 10009 tcp N Waiting Connection refused
+</pre><p>
+ In the above output, <span class="command"><strong>Last Error</strong></span> contains the string representation of the last connection error received for the connection. <span class="command"><strong>State</strong></span> represents the state of the connection, and may be one of the following values:
+ </p><div class="table"><a name="tabl-Messaging_User_Guide-Resilient_Connections-State_values_in_qpid_route_list_connections"></a><p class="title"><b>Table 1.3. State values in <span class="command">$ qpid-route list connections</span></b></p><div class="table-contents"><table summary="State values in $ qpid-route list connections" border="1"><colgroup><col><col></colgroup><tbody><tr><td align="left">
+ Waiting
+ </td><td align="left">
+ Waiting before attempting to reconnect.
+ </td></tr><tr><td align="left">
+ Connecting
+ </td><td align="left">
+ Attempting to establish the connection.
+ </td></tr><tr><td align="left">
+ Operational
+ </td><td align="left">
+ The connection has been established and can be used.
+ </td></tr><tr><td align="left">
+ Failed
+ </td><td align="left">
+ The connection failed and will not retry (usually because authentication failed).
+ </td></tr><tr><td align="left">
+ Closed
+ </td><td align="left">
+ The connection has been closed and will soon be deleted.
+ </td></tr><tr><td align="left">
+ Passive
+ </td><td align="left">
+ If a cluster is federated to another cluster, only one of the nodes has an actual connection to remote node. Other nodes in the cluster have a passive connection.
+ </td></tr></tbody></table></div></div><br class="table-break"></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s03.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-Security.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.3.Â
+ Cheat Sheet for configuring Exchange Options
+  </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.5. Security</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>
Added: qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html?rev=1372179&view=auto
==============================================================================
--- qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html (added)
+++ qpid/site/docs/books/0.18/AMQP-Messaging-Broker-CPP-Book/html/chap-Messaging_User_Guide-Security.html Sun Aug 12 19:03:49 2012
@@ -0,0 +1,525 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>1.5. Security</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="chap-Messaging_User_Guide-Broker_Federation.html" title="1.4. Broker Federation"><link rel="next" href="ch01s06.html" title="1.6. LVQ - Last Value Queue"></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://qpid.apache.o
rg/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.or
g">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">Security</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chap-Messaging_User_Guide-Security"></a>1.5. Security</h2></div></div></div><p>
+ This chapter describes how authentication, rule-based authorization, encryption, and digital signing can be accomplished using Qpid. Authentication is the process of verifying the identity of a user; in Qpid, this is done using the SASL framework. Rule-based authorization is a mechanism for specifying the actions that each user is allowed to perform; in Qpid, this is done using an Access Control List (ACL) that is part of the Qpid broker. Encryption is used to ensure that data is not transferred in a plain-text format that could be intercepted and read. Digital signatures provide proof that a given message was sent by a known sender. Encryption and signing are done using SSL (they can also be done using SASL, but SSL provides stronger encryption).
+ </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Security-User_Authentication"></a>1.5.1. User Authentication</h3></div></div></div><p>
+ AMQP uses Simple Authentication and Security Layer (SASL) to authenticate client connections to the broker. SASL is a framework that supports a variety of authentication methods. For secure applications, we suggest <span class="command"><strong>CRAM-MD5</strong></span>, <span class="command"><strong>DIGEST-MD5</strong></span>, or <span class="command"><strong>GSSAPI</strong></span>. The <span class="command"><strong>ANONYMOUS</strong></span> method is not secure. The <span class="command"><strong>PLAIN</strong></span> method is secure only when used together with SSL.
+ </p><p>
+ Both the Qpid broker and Qpid clients use the <a class="ulink" href="http://cyrusimap.web.cmu.edu/" target="_top">Cyrus SASL library</a>, a full-featured authentication framework, which offers many configuration options. This section shows how to configure users for authentication with SASL, which is sufficient when using <span class="command"><strong>SASL PLAIN</strong></span>. If you are not using SSL, you should configure SASL to use <span class="command"><strong>CRAM-MD5</strong></span>, <span class="command"><strong>DIGEST-MD5</strong></span>, or <span class="command"><strong>GSSAPI</strong></span> (which provides Kerberos authentication). For information on configuring these and other options in SASL, see the Cyrus SASL documentation.
+ </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
+ The <span class="command"><strong>SASL PLAIN</strong></span> method sends passwords in cleartext, and is vulnerable to man-in-the-middle attacks unless SSL (Secure Socket Layer) is also used (see <a class="xref" href="chap-Messaging_User_Guide-Security.html#sect-Messaging_User_Guide-Security-Encryption_using_SSL" title="1.5.3. Encryption using SSL">Section 1.5.3, âEncryption using SSLâ</a>).
+ </p><p>
+ If you are not using SSL, we recommend that you disable <span class="command"><strong>PLAIN</strong></span> authentication in the broker.
+ </p></div><p>
+ The Qpid broker uses the <span class="command"><strong>auth yes|no</strong></span> option to determine whether to use SASL authentication. Turn on authentication by setting <span class="command"><strong>auth</strong></span> to <span class="command"><strong>yes</strong></span> in <code class="filename">/etc/qpidd.conf</code>:
+ </p><pre class="programlisting">
+# /etc/qpidd.conf
+#
+# Set auth to 'yes' or 'no'
+
+auth=yes
+</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-User_Authentication-Configuring_SASL"></a>1.5.1.1. Configuring SASL</h4></div></div></div><p>
+ On Linux systems, the SASL configuration file is generally found in <code class="filename">/etc/sasl2/qpidd.conf</code> or <code class="filename">/usr/lib/sasl2/qpidd.conf</code>.
+ </p><p>
+ The SASL database contains user names and passwords for SASL. In SASL, a user may be associated with a <em class="firstterm">realm</em>. The Qpid broker authenticates users in the <span class="command"><strong>QPID</strong></span> realm by default, but it can be set to a different realm using the <span class="command"><strong>realm</strong></span> option:
+ </p><pre class="programlisting">
+# /etc/qpidd.conf
+#
+# Set the SASL realm using 'realm='
+
+auth=yes
+realm=QPID
+</pre><p>
+ The SASL database is installed at <code class="filename">/var/lib/qpidd/qpidd.sasldb</code>; initially, it has one user named <span class="command"><strong>guest</strong></span> in the <span class="command"><strong>QPID</strong></span> realm, and the password for this user is <span class="command"><strong>guest</strong></span>.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ The user database is readable only by the <code class="systemitem">qpidd</code> user. When run as a daemon, Qpid always runs as the <code class="systemitem">qpidd</code> user. If you start the broker from a user other than the <code class="systemitem">qpidd</code> user, you will need to either reconfigure SASL or turn authentication off.
+ </p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
+ The SASL database stores user names and passwords in plain text. If it is compromised so are all of the passwords that it stores. This is the reason that the <code class="systemitem">qpidd</code> user is the only user that can read the database. If you modify permissions, be careful not to expose the SASL database.
+ </p></div><p>
+ Add new users to the database by using the <span class="command"><strong>saslpasswd2</strong></span> command, which specifies a realm and a user ID. A user ID takes the form <span class="command"><strong><em class="replaceable"><code>user-id</code></em>@<em class="replaceable"><code>domain</code></em>.</strong></span>.
+ </p><pre class="screen"># saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <em class="replaceable"><code>realm</code></em> <em class="replaceable"><code>new_user_name</code></em></pre><p>
+ To list the users in the SASL database, use <span class="command"><strong>sasldblistusers2</strong></span>:
+ </p><pre class="screen"># sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
+</pre><p>
+ If you are using <span class="command"><strong>PLAIN</strong></span> authentication, users who are in the database can now connect with their user name and password. This is secure only if you are using SSL. If you are using a more secure form of authentication, please consult your SASL documentation for information on configuring the options you need.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-User_Authentication-Kerberos"></a>1.5.1.2. Kerberos</h4></div></div></div><p>
+ Both the Qpid broker and Qpid users are 'principals' of the Kerberos server, which means that they are both clients of the Kerberos authentication services.
+ </p><p>
+ To use Kerberos, both the Qpid broker and each Qpid user must be authenticated on the Kerberos server:
+ </p><div class="procedure"><ol type="1"><li><p>
+ Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client:
+ </p><pre class="screen">$ sudo yum install cyrus-sasl-gssapi krb5-workstation</pre></li><li><p>
+ Make sure that the Qpid broker is registered in the Kerberos database.
+ </p><p>
+ Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format <code class="literal">primary/instance@REALM</code>. For a Qpid broker, the primary is <code class="literal">qpidd</code>, the instance is the fully qualified domain name, which you can obtain using <span class="command"><strong>hostname --fqdn</strong></span>, and the REALM is the Kerberos domain realm. By default, this realm is <code class="literal">QPID</code>, but a different realm can be specified in qpid.conf, e.g.:
+</p><pre class="screen">realm=EXAMPLE.COM</pre><p>
+
+ </p><p>
+ For instance, if the fully qualified domain name is <code class="literal">dublduck.example.com</code> and the Kerberos domain realm is <code class="literal">EXAMPLE.COM</code>, then the principal name is <code class="literal">qpidd/dublduck.example.com@EXAMPLE.COM</code>.
+ </p><p>
+ The following script creates a principal for qpidd:
+ </p><pre class="programlisting">
+FDQN=`hostname --fqdn`
+REALM="EXAMPLE.COM"
+kadmin -r $REALM -q "addprinc -randkey -clearpolicy qpidd/$FQDN"
+</pre><p>
+ Now create a Kerberos keytab file for the Qpid broker. The Qpid broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access:
+ </p><pre class="programlisting">
+QPIDD_GROUP="qpidd"
+kadmin -r $REALM -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM"
+chmod g+r /etc/qpidd.keytab
+chgrp $QPIDD_GROUP /etc/qpidd.keytab
+</pre><p>
+ The default location for the keytab file is <code class="filename">/etc/krb5.keytab</code>. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file, e.g.:
+ </p><pre class="programlisting">
+export KRB5_KTNAME=/etc/qpidd.keytab
+</pre><p>
+ If this is correctly configured, you can now enable kerberos support on the Qpid broker by setting the <code class="varname">auth</code> and <code class="varname">realm</code> options in <code class="filename">/etc/qpidd.conf</code>:
+ </p><pre class="programlisting">
+# /etc/qpidd.conf
+auth=yes
+realm=EXAMPLE.COM
+</pre><p>
+ Restart the broker to activate these settings.
+ </p></li><li><p>
+ Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed:
+ </p><pre class="screen">$ kinit user@REALM.COM</pre></li></ol></div><p>
+ Java JMS clients require a few additional steps.
+ </p><div class="procedure"><ol type="1"><li><p>
+ The Java JVM must be run with the following arguments:
+ </p><div class="variablelist"><dl><dt><span class="term">-Djavax.security.auth.useSubjectCredsOnly=false</span></dt><dd><p>
+ Forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.
+ </p></dd><dt><span class="term">-Djava.security.auth.login.config=myjas.conf</span></dt><dd><p>
+ Specifies the jass configuration file. Here is a sample JASS configuration file:
+ </p><pre class="programlisting">
+com.sun.security.jgss.initiate {
+ com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
+};
+</pre></dd><dt><span class="term">-Dsun.security.krb5.debug=true</span></dt><dd><p>
+ Enables detailed debug info for troubleshooting
+ </p></dd></dl></div></li><li><p>
+ The client's Connection URL must specify the following Kerberos-specific broker properties:
+ </p><div class="itemizedlist"><ul><li><p>
+ <code class="varname">sasl_mechs</code> must be set to <code class="literal">GSSAPI</code>.
+ </p></li><li><p>
+ <code class="varname">sasl_protocol</code> must be set to the principal for the qpidd broker, e.g. <code class="literal">qpidd</code>/
+ </p></li><li><p>
+ <code class="varname">sasl_server</code> must be set to the host for the SASL server, e.g. <code class="literal">sasl.com</code>.
+ </p></li></ul></div><p>
+ Here is a sample connection URL for a Kerberos connection:
+ </p><pre class="screen">amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''</pre></li></ol></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Security-Authorization"></a>1.5.2. Authorization</h3></div></div></div><p>
+ In Qpid, Authorization specifies which actions can be performed by each authenticated user using an Access Control List (ACL). Use the <span class="command"><strong>--acl-file</strong></span> command to load the access control list. The filename should have a <code class="filename">.acl</code> extension:
+ </p><pre class="screen">
+$ qpidd --acl-file <em class="replaceable"><code>./aclfilename.acl</code></em></pre><p>
+ Each line in an ACL file grants or denies specific rights to a user. If the last line in an ACL file is <code class="literal">acl deny all all</code>, the ACL uses <em class="firstterm">deny mode</em>, and only those rights that are explicitly allowed are granted:
+ </p><pre class="programlisting">
+acl allow rajith@QPID all all
+acl deny all all
+</pre><p>
+ On this server, <code class="literal">rajith@QPID</code> can perform any action, but nobody else can. Deny mode is the default, so the previous example is equivalent to the following ACL file:
+ </p><pre class="programlisting">
+acl allow rajith@QPID all all
+</pre><p>
+ ACL syntax allows fine-grained access rights for specific actions:
+ </p><pre class="programlisting">
+acl allow carlt@QPID create exchange name=carl.*
+acl allow fred@QPID create all
+acl allow all consume queue
+acl allow all bind exchange
+acl deny all all
+</pre><p>
+ An ACL file can define user groups, and assign permissions to them:
+ </p><pre class="programlisting">
+group admin ted@QPID martin@QPID
+acl allow admin create all
+acl deny all all
+</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Authorization-ACL_Syntax"></a>1.5.2.1. ACL Syntax</h4></div></div></div><p>
+ ACL rules must be on a single line and follow this syntax:
+</p><pre class="programlisting">
+user = username[/domain[@realm]]
+user-list = user1 user2 user3 ...
+group-name-list = group1 group2 group3 ...
+
+group <group-name> = [user-list] [group-name-list]
+
+permission = [allow|allow-log|deny|deny-log]
+action = [consume|publish|create|access|bind|unbind|delete|purge|update]
+object = [virtualhost|queue|exchange|broker|link|route|method]
+property = [name|durable|owner|routingkey|autodelete|exclusive|
+ type|alternate|queuename|schemapackage|schemaclass|
+ queuemaxsizelowerlimit|queuemaxsizeupperlimit|
+ queuemaxcountlowerlimit|queuemaxcountupperlimit]
+
+acl permission {<group-name>|<user-name>|"all"} {action|"all"} [object|"all"
+ [property=<property-value> ...]]
+</pre><p>
+
+ ACL rules can also include a single object name (or the keyword <em class="parameter"><code>all</code></em>) and one or more property name value pairs in the form <span class="command"><strong>property=value</strong></span>
+ </p><p>
+ The following tables show the possible values for <span class="command"><strong>permission</strong></span>, <span class="command"><strong>action</strong></span>, <span class="command"><strong>object</strong></span>, and <span class="command"><strong>property</strong></span> in an ACL rules file.
+ </p><div class="table"><a name="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rules_permission"></a><p class="title"><b>Table 1.4. 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 event 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 event log
+ </p>
+
+ </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesaction"></a><p class="title"><b>Table 1.5. 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, this rule consumes the most resources
+ </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, links
+ </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 objects are bound together
+ </p>
+
+ </td></tr><tr><td>
+ <span class="command"><strong>unbind</strong></span>
+ </td><td>
+ <p>
+ Applied when objects are unbound
+ </p>
+
+ </td></tr><tr><td>
+ <span class="command"><strong>delete</strong></span>
+ </td><td>
+ <p>
+ Applied when objects are deleted
+ </p>
+
+ </td></tr><tr><td>
+ <span class="command"><strong>purge</strong></span>
+ </td><td>
+ <p>
+ Similar to delete but the action is performed on more than one object
+ </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-Messaging_User_Guide-ACL_Syntax-ACL_Rulesobject"></a><p class="title"><b>Table 1.6. 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>broker</strong></span>
+ </td><td>
+ <p>
+ The broker
+ </p>
+
+ </td></tr><tr><td>
+ <span class="command"><strong>link</strong></span>
+ </td><td>
+ <p>
+ A federation or inter-broker link
+ </p>
+
+ </td></tr><tr><td>
+ <span class="command"><strong>method</strong></span>
+ </td><td>
+ <p>
+ Management or agent or broker method
+ </p>
+
+ </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesproperty"></a><p class="title"><b>Table 1.7. ACL Rules:property</b></p><div class="table-contents"><table summary="ACL Rules:property" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Property</th><th>Type</th><th>Description</th><th>Usage</th></tr></thead><tbody><tr><td> <span class="command"><strong>name</strong></span> </td><td>String</td><td>Object name, such as a queue name or exchange name.</td><td>.</td></tr><tr><td> <span class="command"><strong>durable</strong></span> </td><td>Boolean</td><td>Indicates the object is durable</td><td>CREATE QUEUE, CREATE EXCHANGE</td></tr><tr><td> <span class="command"><strong>routingkey</strong></span> </td><td>String</td><td>Specifies routing key</td><td>BIND EXCHANGE, UNBIND EXCHANGE, ACCESS EXCHANGE</td></tr><tr><td> <span class="command"><strong>autodelete</strong><
/span> </td><td>Boolean</td><td>Indicates whether or not the object gets deleted when the connection is closed</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>exclusive</strong></span> </td><td>Boolean</td><td>Indicates the presence of an <em class="parameter"><code>exclusive</code></em> flag</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>type</strong></span> </td><td>String</td><td>Type of exchange, such as topic, fanout, or xml</td><td>CREATE EXCHANGE</td></tr><tr><td> <span class="command"><strong>alternate</strong></span> </td><td>String</td><td>Name of the alternate exchange</td><td>CREATE EXCHANGE, CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>queuename</strong></span> </td><td>String</td><td>Name of the queue</td><td>ACCESS EXCHANGE</td></tr><tr><td> <span class="command"><strong>schemapackage</strong></span> </td><td>String</td><td>QMF schema package name</td><td>ACCESS METHOD</td></tr><tr><td> <span class="co
mmand"><strong>schemaclass</strong></span> </td><td>String</td><td>QMF schema class name</td><td>ACCESS METHOD</td></tr><tr><td> <span class="command"><strong>queuemaxsizelowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for queue.max_size</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>queuemaxsizeupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for queue.max_size</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>queuemaxcountlowerlimit</strong></span> </td><td>Integer</td><td>Minimum value for queue.max_count</td><td>CREATE QUEUE</td></tr><tr><td> <span class="command"><strong>queuemaxcountupperlimit</strong></span> </td><td>Integer</td><td>Maximum value for queue.max_count</td><td>CREATE QUEUE</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Authorization-ACL_Syntacti
c_Conventions"></a>1.5.2.2. ACL Syntactic Conventions</h4></div></div></div><p>
+ In ACL files, the following syntactic conventions apply:
+ </p><div class="itemizedlist"><ul><li><p>
+ A line starting with the <span class="command"><strong>#</strong></span> character is considered a comment and is ignored.
+ </p></li><li><p>
+ Empty lines and lines that contain only whitespace (' ', '\f', '\n', '\r', '\t', '\v') are ignored.
+ </p></li><li><p>
+ All tokens are case sensitive. <em class="parameter"><code>name1</code></em> is not the same as <em class="parameter"><code>Name1</code></em> and <em class="parameter"><code>create</code></em> is not the same as <em class="parameter"><code>CREATE</code></em>.
+ </p></li><li><p>
+ Group lists can be extended to the following line by terminating the line with the <span class="command"><strong>\</strong></span> character.
+ </p></li><li><p>
+ Additional whitespace - that is, where there is more than one whitespace character - between and after tokens is ignored. Group and ACL definitions must start with either <span class="command"><strong>group</strong></span> or <span class="command"><strong>acl</strong></span> and with no preceding whitespace.
+ </p></li><li><p>
+ All ACL rules are limited to a single line of at most 1024 characters.
+ </p></li><li><p>
+ Rules are interpreted from the top of the file down until a matching rule is obtained. The matching rule then controls the allow or deny decision.
+ </p></li><li><p>
+ The keyword <em class="parameter"><code>all</code></em> is reserved and may be used in ACL rules to match all individuals and groups, all actions, or all objects.
+ </p></li><li><p>
+ By default ACL files are in 'Deny Mode' and deny all actions by all users. That is, there is an implicit <em class="parameter"><code>acl deny all all</code></em> rule appended to the ACL rule list.
+ </p></li><li><p>
+ Group names may contain only <em class="parameter"><code>a-z</code></em>, <em class="parameter"><code>A-Z</code></em>, <em class="parameter"><code>0-9</code></em>, <em class="parameter"><code>- hyphen</code></em> and <em class="parameter"><code>_ underscore</code></em>.
+ </p></li><li><p>
+ Individual user names may contain only <em class="parameter"><code>a-z</code></em>, <em class="parameter"><code>A-Z</code></em>, <em class="parameter"><code>0-9</code></em>, <em class="parameter"><code>- hyphen</code></em>, <em class="parameter"><code>_ underscore</code></em>, <em class="parameter"><code>. period</code></em>, <em class="parameter"><code>@ ampersand</code></em>, and <em class="parameter"><code>/ slash</code></em>.
+ </p></li><li><p>
+ Rules must be preceded by any group definitions they can use. Any name not defined as a group will be assumed to be that of an individual.
+ </p></li></ul></div><p>
+
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Authorization-ACL_Rule_Matching"></a>1.5.2.3. ACL Rule Matching</h4></div></div></div><p>
+ The minimum matching criteria for ACL rules are:
+ </p><div class="itemizedlist"><ul><li>An actor (individually named or group member)</li><li>An action</li><li>An object</li></ul></div><p>
+ </p><p>
+ If a rule does not match the minimum criteria then that rule does not control the ACL allow or deny decision.
+ </p><p>
+ ACL rules optionally specify object names and property name=value pairs. If an ACL rule specifies an object name or property values than all of them must match to cause the rule to match.
+ </p><p>
+ The following illustration shows how ACL rules are processed to find matching rules.
+</p><pre class="programlisting">
+# Example of rule matching
+#
+# Using this ACL file content:
+
+(1) acl deny bob create exchange name=test durable=true passive=true
+(2) acl deny bob create exchange name=myEx type=direct
+(3) acl allow all all
+
+#
+# Lookup 1. id:bob action:create objectType:exchange name=test
+# {durable=false passive=false type=direct alternate=}
+#
+# ACL Match Processing:
+# 1. Rule 1 passes minimum criteria with user bob, action create,
+# and object exchange.
+# 2. Rule 1 matches name=test.
+# 3. Rule 1 does not match the rule's durable=true with the requested
+# lookup of durable=false.
+# 4. Rule 1 does not control the decision and processing continues
+# to Rule 2.
+# 5. Rule 2 passes minimum criteria with user bob, action create,
+# and object exchange.
+# 6. Rule 2 does not match the rule's name=myEx with the requested
+# lookup of name=test.
+# 7. Rule 2 does not control the decision and processing continues
+# to Rule 3.
+# 8. Rule 3 matches everything and the decision is 'allow'.
+#
+# Lookup 2. id:bob action:create objectType:exchange name=myEx
+# {durable=true passive=true type=direct alternate=}
+#
+# ACL Match Processing:
+# 1. Rule 1 passes minimum criteria with user bob, action create,
+# and object exchange.
+# 6. Rule 1 does not match the rule's name=test with the requested
+# lookup of name=myEx.
+# 4. Rule 1 does not control the decision and processing continues
+# to Rule 2.
+# 5. Rule 2 passes minimum criteria with user bob, action create,
+# and object exchange.
+# 2. Rule 2 matches name=myEx.
+# 3. Rule 2 matches the rule's type=direct with the requested
+# lookup of type=direct.
+# 8. Rule 2 is the matching rule and the decision is 'deny'.
+#
+</pre><p>
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Permissions"></a>1.5.2.4. Specifying ACL Permissions</h4></div></div></div><p>
+ Now that we have seen the ACL syntax, we will provide representative examples and guidelines for ACL files.
+ </p><p>
+ Most ACL files begin by defining groups:
+ </p><pre class="programlisting">
+group admin ted@QPID martin@QPID
+group user-consume martin@QPID ted@QPID
+group group2 kim@QPID user-consume rob@QPID
+group publisher group2 \
+tom@QPID andrew@QPID debbie@QPID
+</pre><p>
+ Rules in an ACL file grant or deny specific permissions to users or groups:
+ </p><pre class="programlisting">
+acl allow carlt@QPID create exchange name=carl.*
+acl allow rob@QPID create queue
+acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.rht.#
+acl allow user-consume create queue name=tmp.*
+
+acl allow publisher publish all durable=false
+acl allow publisher create queue name=RequestQueue
+acl allow consumer consume queue durable=true
+acl allow fred@QPID create all
+acl allow bob@QPID all queue
+acl allow admin all
+acl allow all consume queue
+acl allow all bind exchange
+acl deny all all
+</pre><p>
+ In the previous example, the last line, <code class="literal">acl deny all all</code>, denies all authorizations that have not been specifically granted. This is the default, but it is useful to include it explicitly on the last line for the sake of clarity. If you want to grant all rights by default, you can specify <code class="literal">acl allow all all</code> in the last line.
+ </p><p>
+ ACL allows specification of conflicting rules. Be sure to specify the most specific rules first followed by more general rules. Here is an example:
+ </p><p>
+</p><pre class="programlisting">
+group users alice@QPID bob@QPID charlie@QPID
+acl deny charlie@QPID create queue
+acl allow users create queue
+acl deny all all
+</pre><p>
+ </p><p>
+ In this example users alice and bob would be able to create queues due to their membership in the users group. However, user charlie is denied from creating a queue despite his membership in the users group because a deny rule for him is stated before the allow rule for the users group.
+ </p><p>
+ Do not allow <em class="parameter"><code>guest</code></em> to access and log QMF management methods that could cause security breaches:
+ </p><pre class="programlisting">
+group allUsers guest@QPID
+....
+acl deny-log allUsers create link
+acl deny-log allUsers access method name=connect
+acl deny-log allUsers access method name=echo
+acl allow all all
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Authorization-Specifying_ACL_Connection_Limits"></a>1.5.2.5. Specifying ACL Connection Limits</h4></div></div></div><p>
+ The ACL module creates two broker command line switches that set limits on the number of connections allowed per user or per client host address. These settings are not specified in the ACL file.
+ </p><p>
+</p><pre class="programlisting">
+--acl-max-connect-per-user N_USER
+--acl-max-connect-per-ip N_IP
+</pre><p>
+ </p><p>
+ If either of these switches is not specified or the value specified is zero then the corresponding connection limit is not enforced.
+ </p><p>
+ If a limit is set for user connections then all users are limited to that number of connections regardless of the client IP address the users are coming from.
+ </p><p>
+ If a limit is set for IP connections then connections for a given IP address are limited regardless of the user credentials presented with the connection.
+ </p><p>
+ Note that addresses using different transports are counted separately even though the host is actually the same physical machine. In the setting illustrated above a host would allow N_IP connections from [::1] IPv6 transport localhost and another N_IP connections from [127.0.0.1] IPv4 transport localhost.
+ </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-Security-Encryption_using_SSL"></a>1.5.3. Encryption using SSL</h3></div></div></div><p>
+ Encryption and certificate management for <span class="command"><strong>qpidd</strong></span> is provided by Mozilla's Network Security Services Library (NSS).
+ </p><div class="orderedlist"><a name="orde-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_for_the_RHM_broker"></a><p class="title"><b>Enabling SSL for the Qpid broker</b></p><ol type="1"><li><p>
+ You will need a certificate that has been signed by a Certification Authority (CA). This certificate will also need to be trusted by your client. If you require client authentication in addition to server authentication, the client's certificate will also need to be signed by a CA and trusted by the broker.
+ </p><p>
+ In the broker, SSL is provided through the <span class="command"><strong>ssl.so</strong></span> module. This module is installed and loaded by default in Qpid. To enable the module, you need to specify the location of the database containing the certificate and key to use. This is done using the <span class="command"><strong>ssl-cert-db</strong></span> option.
+ </p><p>
+ The certificate database is created and managed by the Mozilla Network Security Services (NSS) <span class="command"><strong>certutil</strong></span> tool. Information on this utility can be found on the <a class="ulink" href="http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html" target="_top">Mozilla website</a>, including tutorials on setting up and testing SSL connections. The certificate database will generally be password protected. The safest way to specify the password is to place it in a protected file, use the password file when creating the database, and specify the password file with the <span class="command"><strong>ssl-cert-password-file</strong></span> option when starting the broker.
+ </p><p>
+ The following script shows how to create a certificate database using certutil:
+ </p><pre class="programlisting">
+mkdir ${CERT_DIR}
+certutil -N -d ${CERT_DIR} -f ${CERT_PW_FILE}
+certutil -S -d ${CERT_DIR} -n ${NICKNAME} -s "CN=${NICKNAME}" -t "CT,," -x -f ${CERT_PW_FILE} -z /usr/bin/certutil
+</pre><p>
+ When starting the broker, set <span class="command"><strong>ssl-cert-password-file</strong></span> to the value of <span class="command"><strong>${CERT_PW_FILE}</strong></span>, set <span class="command"><strong>ssl-cert-db</strong></span> to the value of <span class="command"><strong>${CERT_DIR}</strong></span>, and set <span class="command"><strong>ssl-cert-name</strong></span> to the value of <span class="command"><strong>${NICKNAME}</strong></span>.
+ </p></li><li><p>
+ The following SSL options can be used when starting the broker:
+ </p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>--ssl-use-export-policy</strong></span></span></dt><dd><p>
+ Use NSS export policy
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-cert-password-file <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>
+ Required. Plain-text file containing password to use for accessing certificate database.
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-cert-db <em class="replaceable"><code>PATH</code></em></strong></span></span></dt><dd><p>
+ Required. Path to directory containing certificate database.
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-cert-name <em class="replaceable"><code>NAME</code></em></strong></span></span></dt><dd><p>
+ Name of the certificate to use. Default is <code class="literal">localhost.localdomain</code>.
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-port <em class="replaceable"><code>NUMBER</code></em></strong></span></span></dt><dd><p>
+ Port on which to listen for SSL connections. If no port is specified, port 5671 is used.
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-require-client-authentication</strong></span></span></dt><dd><p>
+ Require SSL client authentication (i.e. verification of a client certificate) during the SSL handshake. This occurs before SASL authentication, and is independent of SASL.
+ </p><p>
+ This option enables the <code class="literal">EXTERNAL</code> SASL mechanism for SSL connections. If the client chooses the <code class="literal">EXTERNAL</code> mechanism, the client's identity is taken from the validated SSL certificate, using the <code class="literal">CN</code>literal>, and appending any <code class="literal">DC</code>literal>s to create the domain. For instance, if the certificate contains the properties <code class="literal">CN=bob</code>, <code class="literal">DC=acme</code>, <code class="literal">DC=com</code>, the client's identity is <code class="literal">bob@acme.com</code>.
+ </p><p>
+ If the client chooses a different SASL mechanism, the identity take from the client certificate will be replaced by that negotiated during the SASL handshake.
+ </p></dd><dt><span class="term"><span class="command"><strong>--ssl-sasl-no-dict</strong></span></span></dt><dd><p>
+ Do not accept SASL mechanisms that can be compromised by dictionary attacks. This prevents a weaker mechanism being selected instead of <code class="literal">EXTERNAL</code>, which is not vulnerable to dictionary attacks.
+ </p></dd></dl></div><p>
+ Also relevant is the <span class="command"><strong>--require-encryption</strong></span> broker option. This will cause <span class="command"><strong>qpidd</strong></span> to only accept encrypted connections.
+ </p></li></ol></div><div class="variablelist"><a name="vari-Messaging_User_Guide-Encryption_using_SSL-Enabling_SSL_in_Clients"></a><p class="title"><b>Enabling SSL in Clients</b></p><dl><dt><span class="term">C++ clients:</span></dt><dd><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
+ In C++ clients, SSL is implemented in the <span class="command"><strong>sslconnector.so</strong></span> module. This module is installed and loaded by default in Qpid.
+ </p><p>
+ The following options can be specified for C++ clients using environment variables:
+ </p><div class="table"><a name="tabl-Messaging_User_Guide-Enabling_SSL_in_Clients-SSL_Client_Environment_Variables_for_C_clients"></a><p class="title"><b>Table 1.8. SSL Client Environment Variables for C++ clients</b></p><div class="table-contents"><table summary="SSL Client Environment Variables for C++ clients" border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th colspan="2" align="center">
+ SSL Client Options for C++ clients
+ </th></tr></thead><tbody><tr><td align="left">
+ <span class="command"><strong>QPID_SSL_USE_EXPORT_POLICY</strong></span>
+ </td><td align="left">
+ Use NSS export policy
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>QPID_SSL_CERT_PASSWORD_FILE <em class="replaceable"><code>PATH</code></em></strong></span>
+ </td><td align="left">
+ File containing password to use for accessing certificate database
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>QPID_SSL_CERT_DB <em class="replaceable"><code>PATH</code></em></strong></span>
+ </td><td align="left">
+ Path to directory containing certificate database
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>QPID_SSL_CERT_NAME <em class="replaceable"><code>NAME</code></em></strong></span>
+ </td><td align="left">
+ Name of the certificate to use. When SSL client authentication is enabled, a certificate name should normally be provided.
+ </td></tr></tbody></table></div></div><br class="table-break"></li><li><p>
+ When using SSL connections, clients must specify the location of the certificate database, a directory that contains the client's certificate and the public key of the Certificate Authority. This can be done by setting the environment variable <span class="command"><strong>QPID_SSL_CERT_DB</strong></span> to the full pathname of the directory. If a connection uses SSL client authentication, the client's password is also neededâthe password should be placed in a protected file, and the <span class="command"><strong>QPID_SSL_CERT_PASSWORD_FILE</strong></span> variable should be set to the location of the file containing this password.
+ </p></li><li><p>
+ To open an SSL enabled connection in the Qpid Messaging API, set the <em class="parameter"><code>protocol</code></em> connection option to <em class="parameter"><code>ssl</code></em>.
+ </p></li></ol></div><p>
+
+ </p></dd><dt><span class="term">Java clients:</span></dt><dd><p>
+ </p><div class="orderedlist"><ol type="1"><li><p>
+ For both server and client authentication, import the trusted CA to your trust store and keystore and generate keys for them. Create a certificate request using the generated keys and then create a certificate using the request. You can then import the signed certificate into your keystore. Pass the following arguments to the Java JVM when starting your client:
+</p><pre class="programlisting">
+-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks
+-Djavax.net.ssl.keyStorePassword=password
+-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
+-Djavax.net.ssl.trustStorePassword=password
+</pre><p>
+
+ </p></li><li><p>
+ For server side authentication only, import the trusted CA to your trust store and pass the following arguments to the Java JVM when starting your client:
+</p><pre class="programlisting">
+-Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
+-Djavax.net.ssl.trustStorePassword=password
+</pre><p>
+
+ </p></li><li><p>
+ Java clients must use the SSL option in the connection URL to enable SSL encryption, e.g.
+ </p><pre class="programlisting">amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?ssl='true''
+</pre></li><li><p>
+ If you need to debug problems in an SSL connection, enable Java's SSL debugging by passing the argument <code class="literal">-Djavax.net.debug=ssl</code> to the Java JVM when starting your client.
+ </p></li></ol></div><p>
+
+ </p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="chap-Messaging_User_Guide-Broker_Federation.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="ch01s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.4. Broker Federation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.6. LVQ - Last Value Queue</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