You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2011/02/09 22:39:32 UTC
svn commit: r1069126 [17/24] - in /qpid/site/docs/books:
0.7/AMQP-Messaging-Broker-CPP-Book/html-single/
0.7/AMQP-Messaging-Broker-CPP-Book/html/
0.7/AMQP-Messaging-Broker-CPP-Book/pdf/
0.7/AMQP-Messaging-Broker-Java-Book/AMQP-Messaging-Broker-Java-Boo...
Added: qpid/site/docs/books/trunk/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html?rev=1069126&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html (added)
+++ qpid/site/docs/books/trunk/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html Wed Feb 9 21:39:27 2011
@@ -0,0 +1,4614 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AMQP Messaging Broker (Implemented in C++)</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AMQP Messaging Broker (Implemented in C++)"><div class="titlepage"><div><div><h1 class="title"><a name="id2791952"></a>AMQP Messaging Broker (Implemented in C++)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id3037279">Introduction</a></span></dt><dt><span class="chapter"><a href="#id3037339">1.
+ Running the AMQP Messaging Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#section-Running-a-Qpid-CPP-Broker">1.1.
+ Running a Qpid C++ Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#RASC-BuildingtheCppBrokerandClientLibraries">1.1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </a></span></dt><dt><span class="section"><a href="#RASC-RunningtheCppBroker">1.1.2.
+ Running the C++ Broker
+ </a></span></dt><dt><span class="section"><a href="#RASC-Mostcommonquestionsgettingqpiddrunning">1.1.3.
+ Most
+ common questions getting qpidd running
+ </a></span></dt><dt><span class="section"><a href="#RASC-Authentication">1.1.4.
+ Authentication
+ </a></span></dt><dt><span class="section"><a href="#RASC-Slightlymorecomplexconfiguration">1.1.5.
+ Slightly more
+ complex configuration
+ </a></span></dt><dt><span class="section"><a href="#RASC-Loadingextramodules">1.1.6.
+ Loading extra modules
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3037149">1.2.
+ Cheat Sheet for configuring Queue Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions">1.2.1.
+ Configuring
+ Queue Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3037162">1.3.
+ Cheat Sheet for configuring Exchange Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">1.3.1.
+ Configuring Exchange Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-Broker_Federation">1.4. Broker Federation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Message_Routes">1.4.1. Message Routes</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies">1.4.2. Federation Topologies</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters">1.4.3. Federation among High Availability Message Clusters</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility">1.4.4. The qpid-route Utility</a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-Security">1.5. Security</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-User_A
uthentication">1.5.1. User Authentication</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-Authorization">1.5.2. Authorization</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-Encryption_using_SSL">1.5.3. Encryption using SSL</a></span></dt></dl></dd><dt><span class="section"><a href="#id3077972">1.6.
+ LVQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#LVQ-UnderstandingLVQ">1.6.1.
+ Understanding LVQ
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQsemantics-3A">1.6.2.
+ LVQ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQNOBROWSEsemantics-3A">1.6.3.
+ LVQ_NO_BROWSE
+ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-Examplesource">1.6.4.
+ LVQ Program Example
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#queue-state-replication">1.7.
+ Queue State Replication
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#queuestatereplication-AsynchronousReplicationofQueueState">1.7.1.
+ Asynchronous
+ Replication of Queue State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-High_Availability_Messaging_Clusters">1.8. High Availability Messaging Clusters</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Starting_a_Broker_in_a_Cluster">1.8.1. Starting a Broker in a Cluster</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-qpid_cluster">1.8.2. qpid-cluster</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Failover_in_Clients">1.8.3. Failover in Clients</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Error_handling_in_Clusters">1.8.4. Error handling in Clusters</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Persistence_in_High_Avail
ability_Message_Clusters">1.8.5. Persistence in High Availability Message Clusters</a></span></dt></dl></dd><dt><span class="section"><a href="#AMQP-Compatibility">1.9.
+ AMQP compatibility
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#AMQPcompatibility-AMQPCompatibilityofQpidreleases-3A">1.9.1.
+ AMQP
+ Compatibility of Qpid releases:
+ </a></span></dt><dt><span class="section"><a href="#AMQPcompatibility-InteroptablebyAMQPspecificationversion">1.9.2.
+ Interop
+ table by AMQP specification version
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation">1.10. Qpid Interoperability Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#QpidInteroperabilityDocumentation-SASL">1.10.1.
+ SASL
+ </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chapter-Managing-CPP-Broker">2.
+ Managing the AMQP Messaging Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#section-Managing-CPP-Broker">2.1. Managing the C++ Broker </a></span></dt><dd><dl><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidconfig">2.1.1.
+ Using qpid-config
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidroute">2.1.2.
+ Using qpid-route
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidtool">2.1.3.
+ Using qpid-tool
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidprintevents">2.1.4.
+ Using
+ qpid-printevents
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3074352">2.2.
+ Qpid Management Framework
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidManagementFramework-WhatIsQMF">2.2.1.
+ What Is QMF
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-GettingStartedwithQMF">2.2.2.
+ Getting
+ Started with QMF
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-QMFConcepts">2.2.3.
+ QMF Concepts
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-TheQMFProtocol">2.2.4.
+ The QMF
+ Protocol
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-HowtoWriteaQMFConsole">2.2.5.
+ How
+ to Write a QMF Console
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-HowtoWriteaQMFAgent">2.2.6.
+ How to
+ Write a QMF Agent
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3087820">2.3.
+ QMF Python Console Tutorial
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging">2.3.1.
+ Prerequisite
+ - Install Qpid Messaging
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-SynchronousConsoleOperations">2.3.2.
+ Synchronous
+ Console Operations
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-AsynchronousConsoleOperations">2.3.3.
+ Asynchronous
+ Console Operations
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable">2.3.4.
+ Discovering what Kinds of Objects are Available
+ </a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>1.1. <a href="#tabl-Messaging_User_Guide-The_qpid_route_Utility-qpid_route_options"><span class="command">qpid-route</span> options</a></dt><dt>1.2. <a href="#tabl-Messaging_User_Guide-Resilient_Connections-State_values_in_qpid_route_list_connections">State values in <span class="command">$ qpid-route list connections</span></a></dt><dt>1.3. <a href="#tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rules_permission">ACL Rules: permission</a></dt><dt>1.4. <a href="#tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesaction">ACL Rules:action</a></dt><dt>1.5. <a href="#tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesobject">ACL Rules:object</a></dt><dt>1.6. <a href="#tabl-Messaging_User_Guide-ACL_Syntax-ACL_Rulesproperty">ACL Rules:property</a></dt><dt>1.7. <a href="#tabl-Messaging_User_Guide-Enabling_SSL_in_Clients-SSL_Client_Environment_Variables_for_C_clients">SSL Client
Environment Variables for C++ clients</a></dt><dt>1.8. <a href="#tabl-Messaging_User_Guide-Starting_a_Broker_in_a_Cluster-Options_for_High_Availability_Messaging_Cluster">Options for High Availability Messaging Cluster</a></dt><dt>1.9. <a href="#id3045244">AMQP Version Support by Qpid Release</a></dt><dt>1.10. <a href="#id3043832">AMQP Version Support - alternate format</a></dt><dt>1.11. <a href="#id3050051">SASL Mechanism Support</a></dt><dt>1.12. <a href="#id3074410">SASL Custom Mechanisms</a></dt><dt>2.1. <a href="#id3077402">XML Attributes for QMF Properties and Statistics</a></dt><dt>2.2. <a href="#id3084186">QMF Datatypes</a></dt><dt>2.3. <a href="#id3079393">XML Schema Mapping for QMF Types</a></dt><dt>2.4. <a href="#id3082504">QMF Python Console Class Methods</a></dt></dl></div><div class="preface" title="Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="id3037279"></a>Introduction</h2></div></div></div><p>Qpid provides two AMQP messaging bro
kers:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Implemented in C++ - high performance, low latency, and RDMA support.</p></li><li class="listitem"><p>Implemented in Java - Fully JMS compliant, runs on any Java platform.</p></li></ul></div><p>Both AMQP messaging brokers support clients in multiple
+ languages, as long as the messaging client and the messaging
+ broker use the same version of AMQP. See <a class="link" href="#AMQP-Compatibility" title="1.9. AMQP compatibility">AMQP Compatibility</a> to see
+ which messaging clients work with each broker.</p><p>This manual contains information specific to the broker that is implemented in C++.</p></div><div class="chapter" title="Chapter 1. Running the AMQP Messaging Broker"><div class="titlepage"><div><div><h2 class="title"><a name="id3037339"></a>Chapter 1.
+ Running the AMQP Messaging Broker
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#section-Running-a-Qpid-CPP-Broker">1.1.
+ Running a Qpid C++ Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#RASC-BuildingtheCppBrokerandClientLibraries">1.1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </a></span></dt><dt><span class="section"><a href="#RASC-RunningtheCppBroker">1.1.2.
+ Running the C++ Broker
+ </a></span></dt><dt><span class="section"><a href="#RASC-Mostcommonquestionsgettingqpiddrunning">1.1.3.
+ Most
+ common questions getting qpidd running
+ </a></span></dt><dt><span class="section"><a href="#RASC-Authentication">1.1.4.
+ Authentication
+ </a></span></dt><dt><span class="section"><a href="#RASC-Slightlymorecomplexconfiguration">1.1.5.
+ Slightly more
+ complex configuration
+ </a></span></dt><dt><span class="section"><a href="#RASC-Loadingextramodules">1.1.6.
+ Loading extra modules
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3037149">1.2.
+ Cheat Sheet for configuring Queue Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions">1.2.1.
+ Configuring
+ Queue Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id3037162">1.3.
+ Cheat Sheet for configuring Exchange Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">1.3.1.
+ Configuring Exchange Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-Broker_Federation">1.4. Broker Federation</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Message_Routes">1.4.1. Message Routes</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Federation_Topologies">1.4.2. Federation Topologies</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-Federation_among_High_Availability_Message_Clusters">1.4.3. Federation among High Availability Message Clusters</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Broker_Federation-The_qpid_route_Utility">1.4.4. The qpid-route Utility</a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-Security">1.5. Security</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-User_A
uthentication">1.5.1. User Authentication</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-Authorization">1.5.2. Authorization</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-Security-Encryption_using_SSL">1.5.3. Encryption using SSL</a></span></dt></dl></dd><dt><span class="section"><a href="#id3077972">1.6.
+ LVQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#LVQ-UnderstandingLVQ">1.6.1.
+ Understanding LVQ
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQsemantics-3A">1.6.2.
+ LVQ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQNOBROWSEsemantics-3A">1.6.3.
+ LVQ_NO_BROWSE
+ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-Examplesource">1.6.4.
+ LVQ Program Example
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#queue-state-replication">1.7.
+ Queue State Replication
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#queuestatereplication-AsynchronousReplicationofQueueState">1.7.1.
+ Asynchronous
+ Replication of Queue State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#chap-Messaging_User_Guide-High_Availability_Messaging_Clusters">1.8. High Availability Messaging Clusters</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Starting_a_Broker_in_a_Cluster">1.8.1. Starting a Broker in a Cluster</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-qpid_cluster">1.8.2. qpid-cluster</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Failover_in_Clients">1.8.3. Failover in Clients</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Error_handling_in_Clusters">1.8.4. Error handling in Clusters</a></span></dt><dt><span class="section"><a href="#sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Persistence_in_High_Avail
ability_Message_Clusters">1.8.5. Persistence in High Availability Message Clusters</a></span></dt></dl></dd><dt><span class="section"><a href="#AMQP-Compatibility">1.9.
+ AMQP compatibility
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#AMQPcompatibility-AMQPCompatibilityofQpidreleases-3A">1.9.1.
+ AMQP
+ Compatibility of Qpid releases:
+ </a></span></dt><dt><span class="section"><a href="#AMQPcompatibility-InteroptablebyAMQPspecificationversion">1.9.2.
+ Interop
+ table by AMQP specification version
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#QpidInteroperabilityDocumentation-QpidInteroperabilityDocumentation">1.10. Qpid Interoperability Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="#QpidInteroperabilityDocumentation-SASL">1.10.1.
+ SASL
+ </a></span></dt></dl></dd></dl></div><div class="section" title="1.1. Running a Qpid C++ Broker"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-Running-a-Qpid-CPP-Broker"></a>1.1.
+ Running a Qpid C++ Broker
+ </h2></div></div></div><div class="section" title="1.1.1. Building the C++ Broker and Client Libraries"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-BuildingtheCppBrokerandClientLibraries"></a>1.1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </h3></div></div></div><p>
+ The root directory for the C++ distribution is named
+ qpidc-0.4. The README file in that directory gives
+ instructions for building the broker and client libraries. In
+ most cases you will do the following:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ ./configure
+[qpidc-0.4]$ make
+</pre></div><div class="section" title="1.1.2. Running the C++ Broker"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-RunningtheCppBroker"></a>1.1.2.
+ Running the C++ Broker
+ </h3></div></div></div><p>
+ Once you have built the broker and client libraries, you can
+ start the broker from the command line:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd
+</pre><p>
+ Use the --daemon option to run the broker as a daemon
+ process:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --daemon
+</pre><p>
+ You can stop a running daemon with the --quit option:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --quit
+</pre><p>
+ You can see all available options with the --help option
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --help
+</pre></div><div class="section" title="1.1.3. Most common questions getting qpidd running"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Mostcommonquestionsgettingqpiddrunning"></a>1.1.3.
+ Most
+ common questions getting qpidd running
+ </h3></div></div></div><div class="section" title='1.1.3.1. Error when starting broker: "no data directory"'><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"></a>1.1.3.1.
+ Error
+ when starting broker: "no data directory"
+ </h4></div></div></div><p>
+ The qpidd broker requires you to set a data directory or specify
+ --no-data-dir (see help for more details). The data
+ directory is used for the journal, so it is important when
+ reliability counts. Make sure your process has write permission
+ to the data directory.
+ </p><p>
+ The default location is
+ </p><pre class="programlisting">
+/lib/var/qpidd
+</pre><p>
+ An alternate location can be set with --data-dir
+ </p></div><div class="section" title='1.1.3.2. Error when starting broker: "that process is locked"'><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"></a>1.1.3.2.
+ Error
+ when starting broker: "that process is locked"
+ </h4></div></div></div><p>
+ Note that when qpidd starts it creates a lock file is data
+ directory are being used. If you have a un-controlled exit,
+ please mail
+ the trace from the core to the dev@qpid.apache.org mailing list.
+ To clear the lock run
+ </p><pre class="programlisting">
+./qpidd -q
+</pre><p>
+ It should also be noted that multiple brokers can be run on the
+ same host. To do so set alternate data directories for each qpidd
+ instance.
+ </p></div><div class="section" title="1.1.3.3. Using a configuration file"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Usingaconfigurationfile"></a>1.1.3.3.
+ Using a configuration
+ file
+ </h4></div></div></div><p>
+ Each option that can be specified on the command line can also be
+ specified in a configuration file. To see available options, use
+ --help on the command line:
+ </p><pre class="programlisting">
+./qpidd --help
+</pre><p>
+ A configuration file uses name/value pairs, one on each line. To
+ convert a command line option to a configuration file entry:
+ </p><p>
+ a.) remove the '--' from the beginning of the option.
+ b.) place a '=' between the option and the value (use
+ <span class="emphasis"><em>yes</em></span> or <span class="emphasis"><em>true</em></span> to enable options that take no
+ value when specified on the command line).
+ c.) place one option per line.
+ </p><p>
+ For instance, the --daemon option takes no value, the
+ --log-to-syslog option takes the values yes or
+ no. The following configuration file sets these two
+ options:
+ </p><pre class="programlisting">
+daemon=yes
+log-to-syslog=yes
+</pre></div><div class="section" title="1.1.3.4. Can I use any Language client with the C++ Broker?"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-CanIuseanyLanguageclientwiththeCppBroker-3F"></a>1.1.3.4.
+ Can I use
+ any Language client with the C++ Broker?
+ </h4></div></div></div><p>
+ Yes, all the clients work with the C++ broker; it is written in
+ C+<span class="emphasis"><em>, but uses the AMQP wire protocol. Any broker can be used
+ with any client that uses the same AMQP version. When running the
+ C</em></span>+ broker, it is highly recommended to run AMQP 0-10.
+ </p><p>
+ Note that JMS also works with the C++ broker.
+ </p></div></div><div class="section" title="1.1.4. Authentication"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Authentication"></a>1.1.4.
+ Authentication
+ </h3></div></div></div><div class="section" title="1.1.4.1. Linux"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Linux"></a>1.1.4.1.
+ Linux
+ </h4></div></div></div><p>
+ The PLAIN authentication is done on a username+password, which is
+ stored in the sasldb_path file. Usernames and passwords can be
+ added to the file using the command:
+ </p><pre class="programlisting">
+saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER>
+</pre><p>
+ The REALM is important and should be the same as the
+ --auth-realm
+ option to the broker. This lets the broker properly find the user
+ in
+ the sasldb file.
+ </p><p>
+ Existing user accounts may be listed with:
+ </p><pre class="programlisting">
+sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
+</pre><p>
+ NOTE: The sasldb file must be readable by the user running the
+ qpidd daemon, and should be readable only by that user.
+ </p></div><div class="section" title="1.1.4.2. Windows"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Windows"></a>1.1.4.2.
+ Windows
+ </h4></div></div></div><p>
+ On Windows, the users are authenticated against the local
+ machine. You should add the appropriate users using the standard
+ Windows tools (Control Panel->User Accounts). To run many of
+ the examples, you will need to create a user "guest" with
+ password "guest".
+ </p><p>
+ If you cannot or do not want to create new users, you can run
+ without authentication by specifying the no-auth option to the
+ broker.
+ </p></div></div><div class="section" title="1.1.5. Slightly more complex configuration"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Slightlymorecomplexconfiguration"></a>1.1.5.
+ Slightly more
+ complex configuration
+ </h3></div></div></div><p>
+ The easiest way to get a full listing of the broker's options are
+ to use the --help command, run it locally for the latest set of
+ options. These options can then be set in the conf file for
+ convenience (see above)
+ </p><pre class="programlisting">
+./qpidd --help
+
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+Module options:
+ --module-dir DIR (/usr/lib/qpidd) Load all .so modules in this directory
+ --load-module FILE Specifies additional module(s) to be loaded
+ --no-module-dir Don't load modules from module directory
+
+Broker Options:
+ --data-dir DIR (/var/lib/qpidd) Directory to contain persistent data generated by the broker
+ --no-data-dir Don't use a data directory. No persistent
+ configuration will be loaded or stored
+ -p [ --port ] PORT (5672) Tells the broker to listen on PORT
+ --worker-threads N (3) Sets the broker thread pool size
+ --max-connections N (500) Sets the maximum allowed connections
+ --connection-backlog N (10) Sets the connection backlog limit for the
+ server socket
+ --staging-threshold N (5000000) Stages messages over N bytes to disk
+ -m [ --mgmt-enable ] yes|no (1) Enable Management
+ --mgmt-pub-interval SECONDS (10) Management Publish Interval
+ --ack N (0) Send session.ack/solicit-ack at least every
+ N frames. 0 disables voluntary ack/solitict
+ -ack
+
+Daemon options:
+ -d [ --daemon ] Run as a daemon.
+ -w [ --wait ] SECONDS (10) Sets the maximum wait time to initialize the
+ daemon. If the daemon fails to initialize, prints
+ an error and returns 1
+ -c [ --check ] Prints the daemon's process ID to stdout and
+ returns 0 if the daemon is running, otherwise
+ returns 1
+ -q [ --quit ] Tells the daemon to shut down
+Logging options:
+ --log-output FILE (stderr) Send log output to FILE. FILE can be a file name
+ or one of the special values:
+ stderr, stdout, syslog
+ -t [ --trace ] Enables all logging
+ --log-enable RULE (error+) Enables logging for selected levels and component
+ s. RULE is in the form 'LEVEL+:PATTERN'
+ Levels are one of:
+ trace debug info notice warning error critical
+ For example:
+ '--log-enable warning+' logs all warning, error
+ and critical messages.
+ '--log-enable debug:framing' logs debug messages
+ from the framing namespace. This option can be
+ used multiple times
+ --log-time yes|no (1) Include time in log messages
+ --log-level yes|no (1) Include severity level in log messages
+ --log-source yes|no (0) Include source file:line in log messages
+ --log-thread yes|no (0) Include thread ID in log messages
+ --log-function yes|no (0) Include function signature in log messages
+</pre></div><div class="section" title="1.1.6. Loading extra modules"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Loadingextramodules"></a>1.1.6.
+ Loading extra modules
+ </h3></div></div></div><p>
+ By default the broker will load all the modules in the module
+ directory, however it will NOT display options for modules that
+ are not loaded. So to see the options for extra modules loaded
+ you need to load the module and then add the help command like
+ this:
+ </p><pre class="programlisting">
+./qpidd --load-module libbdbstore.so --help
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+
+ / .... non module options would be here ... /
+
+
+Store Options:
+ --store-directory DIR Store directory location for persistence (overrides
+ --data-dir)
+ --store-async yes|no (1) Use async persistence storage - if store supports
+ it, enables AIO O_DIRECT.
+ --store-force yes|no (0) Force changing modes of store, will delete all
+ existing data if mode is changed. Be SURE you want
+ to do this!
+ --num-jfiles N (8) Number of files in persistence journal
+ --jfile-size-pgs N (24) Size of each journal file in multiples of read
+ pages (1 read page = 64kiB)
+</pre></div></div><div class="section" title="1.2. Cheat Sheet for configuring Queue Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3037149"></a>1.2.
+ Cheat Sheet for configuring Queue Options
+ </h2></div></div></div><div class="section" title="1.2.1. Configuring Queue Options"><div class="titlepage"><div><div><h3 class="title"><a name="CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions"></a>1.2.1.
+ Configuring
+ Queue Options
+ </h3></div></div></div><p>
+ The C++ Broker M4 or later supports the following additional
+ Queue constraints.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions" title="1.2.1. Configuring Queue Options">Section 1.2.1, “
+ Configuring
+ Queue Options
+ ”</a>
+ </p></li><li class="listitem"><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints" title="1.2.1.1. Applying Queue Sizing Constraints">Section 1.2.1.1, “
+ Applying Queue Sizing Constraints
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29" title="1.2.1.2. Changing the Queue ordering Behaviors (FIFO/LVQ)">Section 1.2.1.2, “
+ Changing the Queue ordering Behaviors (FIFO/LVQ)
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors" title="1.2.1.3. Setting additional behaviors">Section 1.2.1.3, “
+ Setting additional behaviors
+ ”</a>
+ </p></li><li class="listitem"><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-PersistLastNode" title="1.2.1.3.1. Persist Last Node">Section 1.2.1.3.1, “
+ Persist
+ Last Node
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-Queueeventgeneration" title="1.2.1.3.2. Queue event generation">Section 1.2.1.3.2, “
+ Queue
+ event generation
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-OtherClients" title="1.2.1.4. Other Clients">Section 1.2.1.4, “
+ Other
+ Clients
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li></ul></div><div class="section" title="1.2.1.1. Applying Queue Sizing Constraints"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"></a>1.2.1.1.
+ Applying Queue Sizing Constraints
+ </h4></div></div></div><p>
+ This allows to specify how to size a queue and what to do when
+ the sizing constraints have been reached. The queue size can be
+ limited by the number messages (message depth) or byte depth on
+ the queue.
+ </p><p>
+ Once the Queue meets/ exceeds these constraints the follow
+ policies can be applied
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>REJECT - Reject the published message
+ </p></li><li class="listitem"><p>FLOW_TO_DISK - Flow the messages to disk, to preserve memory
+ </p></li><li class="listitem"><p>RING - start overwriting messages in a ring based on sizing.
+ If head meets tail, advance head
+ </p></li><li class="listitem"><p>RING_STRICT - start overwriting messages in a ring based on
+ sizing. If head meets tail, AND the consumer has the tail message
+ acquired it will reject
+ </p></li></ul></div><p>
+ Examples:
+ </p><p>
+ Create a queue an auto delete queue that will support 100 000
+ bytes, and then REJECT
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setSizePolicy(REJECT,100000,0);
+
+ session.queueDeclare(arg::queue=queue, arg::autoDelete=true, arg::arguments=qo);
+</pre><p>
+ Create a queue that will support 1000 messages into a RING buffer
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setSizePolicy(RING,0,1000);
+
+ session.queueDeclare(arg::queue=queue, arg::arguments=qo);
+</pre></div><div class="section" title="1.2.1.2. Changing the Queue ordering Behaviors (FIFO/LVQ)"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29"></a>1.2.1.2.
+ Changing the Queue ordering Behaviors (FIFO/LVQ)
+ </h4></div></div></div><p>
+ The default ordering in a queue in Qpid is FIFO. However
+ additional ordering semantics can be used namely LVQ (Last Value
+ Queue). Last Value Queue is define as follows.
+ </p><p>
+ If I publish symbols RHT, IBM, JAVA, MSFT, and then publish RHT
+ before the consumer is able to consume RHT, that message will be
+ over written in the queue and the consumer will receive the last
+ published value for RHT.
+ </p><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setOrdering(LVQ);
+
+ session.queueDeclare(arg::queue=queue, arg::arguments=qo);
+
+ .....
+ string key;
+ qo.getLVQKey(key);
+
+ ....
+ for each message, set the into application headers before transfer
+ message.getHeaders().setString(key,"RHT");
+
+</pre><p>
+ Notes:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Messages that are dequeued and the re-queued will have the
+ following exceptions. a.) if a new message has been queued with
+ the same key, the re-queue from the consumer, will combine these
+ two messages. b.) If an update happens for a message of the same
+ key, after the re-queue, it will not update the re-queued
+ message. This is done to protect a client from being able to
+ adversely manipulate the queue.
+ </p></li><li class="listitem"><p>Acquire: When a message is acquired from the queue, no matter
+ it's position, it will behave the same as a dequeue
+ </p></li><li class="listitem"><p>LVQ does not support durable messages. If the queue or
+ messages are declared durable on an LVQ, the durability will be
+ ignored.
+ </p></li></ul></div><p>
+ A fully worked <a class="xref" href="#LVQ-Examplesource" title="1.6.4. LVQ Program Example">Section 1.6.4, “
+ LVQ Program Example
+ ”</a> can be found here
+ </p></div><div class="section" title="1.2.1.3. Setting additional behaviors"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"></a>1.2.1.3.
+ Setting additional behaviors
+ </h4></div></div></div><div class="section" title="1.2.1.3.1. Persist Last Node"><div class="titlepage"><div><div><h5 class="title"><a name="CheatSheetforconfiguringQueueOptions-PersistLastNode"></a>1.2.1.3.1.
+ Persist
+ Last Node
+ </h5></div></div></div><p>
+ This option is used in conjunction with clustering. It allows for
+ a queue configured with this option to persist transient messages
+ if the cluster fails down to the last node. If additional nodes
+ in the cluster are restored it will stop persisting transient
+ messages.
+ </p><p>
+ Note
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>if a cluster is started with only one active node, this mode
+ will not be triggered. It is only triggered the first time the
+ cluster fails down to 1 node.
+ </p></li><li class="listitem"><p>The queue MUST be configured durable
+ </p></li></ul></div><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.clearPersistLastNode();
+
+ session.queueDeclare(arg::queue=queue, arg::durable=true, arg::arguments=qo);
+</pre></div><div class="section" title="1.2.1.3.2. Queue event generation"><div class="titlepage"><div><div><h5 class="title"><a name="CheatSheetforconfiguringQueueOptions-Queueeventgeneration"></a>1.2.1.3.2.
+ Queue
+ event generation
+ </h5></div></div></div><p>
+ This option is used to determine whether enqueue/dequeue events
+ representing changes made to queue state are generated. These
+ events can then be processed by plugins such as that used for
+ <a class="xref" href="#queue-state-replication" title="1.7. Queue State Replication">Section 1.7, “
+ Queue State Replication
+ ”</a>.
+ </p><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions options;
+ options.enableQueueEvents(1);
+ session.queueDeclare(arg::queue="my-queue", arg::arguments=options);
+</pre><p>
+ The boolean option indicates whether only enqueue events should
+ be generated. The key set by this is
+ 'qpid.queue_event_generation' and the value is and integer value
+ of 1 (to replicate only enqueue events) or 2 (to replicate both
+ enqueue and dequeue events).
+ </p></div></div><div class="section" title="1.2.1.4. Other Clients"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-OtherClients"></a>1.2.1.4.
+ Other
+ Clients
+ </h4></div></div></div><p>
+ Note that these options can be set from any client. QueueOptions
+ just correctly formats the arguments passed to the QueueDeclare()
+ method.
+ </p></div></div></div><div class="section" title="1.3. Cheat Sheet for configuring Exchange Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3037162"></a>1.3.
+ Cheat Sheet for configuring Exchange Options
+ </h2></div></div></div><div class="section" title="1.3.1. Configuring Exchange Options"><div class="titlepage"><div><div><h3 class="title"><a name="CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions"></a>1.3.1.
+ Configuring Exchange Options
+ </h3></div></div></div><p>
+ The C++ Broker M4 or later supports the following additional
+ Exchange options in addition to the standard AMQP define options
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exchange Level Message sequencing
+ </p></li><li class="listitem"><p>Initial Value Exchange
+ </p></li></ul></div><p>
+ Note that these features can be used on any exchange type, that
+ has been declared with the options set.
+ </p><p>
+ It also supports an additional option to the bind operation on a
+ direct exchange
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exclusive binding for key
+ </p></li></ul></div><div class="section" title="1.3.1.1. Exchange Level Message sequencing"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-ExchangeLevelMessagesequencing"></a>1.3.1.1.
+ Exchange Level Message sequencing
+ </h4></div></div></div><p>
+ This feature can be used to place a sequence number into each
+ message's headers, based on the order they pass through an
+ exchange. The sequencing starts at 0 and then wraps in an AMQP
+ int64 type.
+ </p><p>
+ The field name used is "qpid.msg_sequence"
+ </p><p>
+ To use this feature an exchange needs to be declared specifying
+ this option in the declare
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.msg_sequence",1);
+
+...
+ // now declare the exchange
+ session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
+</pre><p>
+ Then each message passing through that exchange will be numbers
+ in the application headers.
+ </p><pre class="programlisting">
+ unit64_t seqNo;
+ //after message transfer
+ seqNo = message.getHeaders().getAsInt64("qpid.msg_sequence");
+</pre></div><div class="section" title="1.3.1.2. Initial Value Exchange"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-InitialValueExchange"></a>1.3.1.2.
+ Initial
+ Value Exchange
+ </h4></div></div></div><p>
+ This feature caches a last message sent to an exchange. When a
+ new binding is created onto the exchange it will then attempt to
+ route this cached messaged to the queue, based on the binding.
+ This allows for topics or the creation of configurations where a
+ new consumer can receive the last message sent to the broker,
+ with matching routing.
+ </p><p>
+ To use this feature an exchange needs to be declared specifying
+ this option in the declare
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.ive",1);
+
+...
+ // now declare the exchange
+ session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
+</pre><p>
+ now use the exchange in the same way you would use any other
+ exchange.
+ </p></div><div class="section" title="1.3.1.3. Exclusive binding for key"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-Exclusivebindingforkey"></a>1.3.1.3.
+ Exclusive
+ binding for key
+ </h4></div></div></div><p>
+ Direct exchanges in qpidd support a qpid.exclusive-binding option
+ on the bind operation that causes the binding specified to be the
+ only one for the given key. I.e. if there is already a binding at
+ this exchange with this key it will be atomically updated to bind
+ the new queue. This means that the binding can be changed
+ concurrently with an incoming stream of messages and each message
+ will be routed to exactly one queue.
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.exclusive-binding",1);
+
+ //the following will cause the only binding from amq.direct with 'my-key'
+ //to be the one to 'my-queue'; if there were any previous bindings for that
+ //key they will be removed. This is atomic w.r.t message routing through the
+ //exchange.
+ session.exchangeBind(arg::exchange="amq.direct", arg::queue="my-queue",
+ arg::bindingKey="my-key", arg::arguments=args);
+
+...
+</pre></div></div></div><div class="section" title="1.4. Broker Federation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><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 class="itemizedlist" type="disc"><li class="listitem"><p>
+ Geography: Customer requests may be routed to a processing location close to the customer.
+ </p></li><li class="listitem"><p>
+ Service Type: High value customers may be routed to more responsive servers.
+ </p></li><li class="listitem"><p>
+ Load balancing: Routing among brokers may be changed dynamically to account for changes in actual or anticipated load.
+ </p></li><li class="listitem"><p>
+ High Availability: Routing may be changed to a new broker if an existing broker becomes unavailable.
+ </p></li><li class="listitem"><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 class="listitem"><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 class="listitem"><p>
+ Replicated Exchanges: High-function exchanges like the XML exchange can be replicated to scale performance.
+ </p></li><li class="listitem"><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" title="1.4.1. Message Routes"><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" title="1.4.1.1. Queue Routes"><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" title="1.4.1.2. Exchange Routes"><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" title="1.4.1.3. Dynamic Exchange Routes"><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" title="1.4.2. Federation Topologies"><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" title="1.4.3. Federation among High Availability Message Clusters"><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" title="1.4.4. The qpid-route Utility"><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.1. <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 class="itemizedlist" type="disc"><li class="listitem"><p>
+ tcp (default)
+ </p></li><li class="listitem"><p>
+ ssl
+ </p></li><li class="listitem"><p>
+ rdma
+ </p></li></ul></div>
+
+ </td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="1.4.4.1. Creating and Deleting Queue Routes"><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" title="1.4.4.2. Creating and Deleting Exchange Routes"><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" title="1.4.4.3. Deleting all routes for a broker"><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" title="1.4.4.4. Creating and Deleting Dynamic Exchange Routes"><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" title="1.4.4.5. Viewing Routes"><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" title="1.4.4.6. Resilient Connections"><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.2. 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 class="section" title="1.5. Security"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><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" title="1.5.1. User Authentication"><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" title="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="#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" title="1.5.1.1. Configuring SASL"><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" title="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" title="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" title="1.5.1.2. Kerberos"><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 class="procedure" type="1"><li class="step" title="Step 1"><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 class="step" title="Step 2"><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 class="step" title="Step 3"><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>
[... 3551 lines stripped ...]
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org