content/components/dispatch-router/release-0.1.html

<!DOCTYPE html>  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <meta charset="UTF-8"> <title>Qpid Dispatch Release 0.1 - Apache Qpid™</title> <meta http-equiv="X-UA-Compatible" content="IE=edge"/> <meta name="viewport" content="width=device-width, initial-scale=1.0"/> <link rel="stylesheet" href="/site.css" type="text/css" async="async"/> <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/> <script type="text/javascript">var _deferredFunctions = [];</script> <script type="text/javascript" src="/deferred.js" defer="defer"></script>   <meta name="go-import" content="qpid.apache.org git https://gitbox.apache.org/repos/asf/qpid-proton.git"/> <meta name="go-source" content="qpid.apache.org https://github.com/apache/qpid-proton/blob/go1/README.md https://github.com/apache/qpid-proton/tree/go1{/dir} https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/> </head> <body> <div id="-content"> <div id="-top" class="panel"> <a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a> <a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a> <ul id="-global-navigation"> <li><a id="-logotype" href="/index.html">Apache Qpid<sup>™</sup></a></li> <li><a href="/documentation.html">Documentation</a></li> <li><a href="/download.html">Download</a></li> <li><a href="/discussion.html">Discussion</a></li> </ul> </div> <div id="-menu" class="panel" style="display: none;"> <div class="flex"> <section> <h3>Project</h3> <ul> <li><a href="/overview.html">Overview</a></li> <li><a href="/components/index.html">Components</a></li> <li><a href="/releases/index.html">Releases</a></li> </ul> </section> <section> <h3>Messaging APIs</h3> <ul> <li><a href="/proton/index.html">Qpid Proton</a></li> <li><a href="/components/jms/index.html">Qpid JMS</a></li> <li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li> </ul> </section> <section> <h3>Servers and tools</h3> <ul> <li><a href="/components/broker-j/index.html">Broker-J</a></li> <li><a href="/components/cpp-broker/index.html">C++ broker</a></li> <li><a href="/components/dispatch-router/index.html">Dispatch router</a></li> </ul> </section> <section> <h3>Resources</h3> <ul> <li><a href="/dashboard.html">Dashboard</a></li> <li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li> <li><a href="/resources.html">More resources</a></li> </ul> </section> </div> </div> <div id="-search" class="panel" style="display: none;"> <form action="http://www.google.com/search" method="get"> <input type="hidden" name="sitesearch" value="qpid.apache.org"/> <input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/> <button type="submit">Search</button> <a href="/search.html">More ways to search</a> </form> </div> <div id="-middle" class="panel"> <ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/components/index.html">Components</a></li><li><a href="/components/dispatch-router/index.html">Dispatch Router</a></li><li>Qpid Dispatch Release 0.1</li></ul> <div id="-middle-content"> <h1 id="qpid-dispatch-release-01">Qpid Dispatch Release 0.1</h1> <h2 id="system-requirements-and-dependencies">System Requirements and Dependencies</h2> <ul> <li>Qpid Dispatch will only build and run on Posix-based operating systems (Linux, et. al.)</li> <li>Qpid Proton version 0.6 must be installed (including the Python bindings) to build Qpid Dispatch</li> </ul> <h2 id="documented-capabilities-available-in-version-01">Documented capabilities available in version 0.1</h2> <p>Some of the capabilities listed in these pages for Dispatch are for future releases and are supplied for the purpose of illustrating the potential of a message router. This section outlines the actual capabilities of version 0.1:</p> <ul> <li>Route computation uses a fixed constant cost for inter-router links. Therefore, cost is only determined by the number of hops from source to destination.</li> <li>Addressing semantics are constrained to multicast. If there are multiple consumers for a particular address, each consumer will receive a copy of every message produced to that address.</li> <li>Link-Routing is not supported in 0.1. All routing is message-based.</li> </ul> <h2 id="building-testing-and-installing">Building, Testing, and Installing</h2> <p>Download and extract the source tar file:</p> <pre><code>$ wget http://people.apache.org/~tross/qpid-dispatch-0.1rc5/qpid-dispatch-0.1.tar.gz $ tar -xzf qpid-dispatch-0.1.tar.gz </code></pre> <p>Source the build configuration:</p> <pre><code>$ cd qpid-dispatch-0.1 $ source config.sh </code></pre> <p>Build and test the package. This will create two directories: 'build' and 'install'. Dispatch will be built in the 'build' directory and installed in the 'install' directory. The regression and system test suites will then be run against the installed bits.</p> <pre><code>$ bin/test.sh </code></pre> <p>If you wish to change the build configuration, go into the build directory, use cmake to configure your build then rebuild and/or reinstall from there:</p> <pre><code>$ cd build $ cmake .. $ make $ make install </code></pre> <h2 id="configuration">Configuration</h2> <p>The default configuration file is installed in _install-prefix_/etc/qpid/qdrouterd.conf. This configuration file will cause the router to run in standalone mode, listening on the standard AMQP port (5672). Dispatch Router looks for the configuration file in the installed location by default. If you wish to use a different path, the "-c" command line option will instruct Dispatch Router as to which configuration to load.</p> <p>To run the router, invoke the executable:</p> <pre><code>$ qdrouterd </code></pre> <h2 id="client-compatibility">Client Compatibility</h2> <p>Dispatch Router should, in theory, work with any client that is compatible with AMQP 1.0. The following clients have been tested:</p> <table> <thead> <tr> <th>Client</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>qpid::messaging</td> <td>The Qpid messaging clients work with Dispatch Router as long as they are configured to use the 1.0 version of the protocol. To enable AMQP 1.0 in the C++ client, use the {protocol:amqp1.0} connection option.</td> </tr> <tr> <td>Proton Messenger</td> <td>Messenger works with Dispatch Router.</td> </tr> </tbody> </table> <h2 id="tools">Tools</h2> <p>Installed with the Dispatch Router kit is a command line tool called <em>qdstat</em>. This tool can be used to view manageable data inside Dispatch Router. The following options are useful for seeing that the router is doing:</p> <table> <thead> <tr> <th>Option</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>-l</td> <td>Print a list of AMQP links attached to the router. Links are unidirectional. Outgoing links are usually associated with a subscription address. The tool distinguishes between _endpoint_ links and _router_ links. Endpoint links are attached to clients using the router. Router links are attached to other routers in a network of routers.</td> </tr> <tr> <td>-a</td> <td>Print a list of addresses known to the router.</td> </tr> <tr> <td>-n</td> <td>Print a list of known routers in the network.</td> </tr> <tr> <td>-c</td> <td>Print a list of connections to the router.</td> </tr> </tbody> </table> <h2 id="features-and-examples">Features and Examples</h2> <h3 id="standalone-and-interior-modes">Standalone and Interior Modes</h3> <p>The router can operate stand-alone or as a node in a network of routers. The mode is configured in the _router_ section of the configuration file. In stand-alone mode, the router does not attempt to collaborate with any other routers and only routes messages among directly connected endpoints.</p> <p>If your router is running in stand-alone mode, _qdstat -a_ will look like the following:</p> <pre><code>$ qdstat -a Router Addresses class address in-proc local remote in out thru to-proc from-proc =============================================================================== local $management Y 0 0 1 0 0 1 0 local temp.AY81ga 1 0 0 0 0 0 0 </code></pre> <p>Note that there are two known addresses. _$management_ is the address of the router's embedded management agent. _temp.AY81ga_ is the temporary reply-to address of the _qdstat_ client making requests to the agent.</p> <p>If you change the mode to interior and restart the processs, the same command will yield two additional addresses which are used for inter-router communication:</p> <pre><code>$ qdstat -a Router Addresses class address in-proc local remote in out thru to-proc from-proc =============================================================================== local $management Y 0 0 1 0 0 1 0 local qdhello Y 0 0 0 0 0 0 3 local qdrouter Y 0 0 0 0 0 0 1 local temp.khOpGb 1 0 0 0 0 0 0 </code></pre> <h3 id="mobile-subscribers">Mobile Subscribers</h3> <p>The term "mobile subscriber" simply refers to the fact that a client may connect to the router and subscribe to an address to receive messages sent to that address. No matter where in the network the subscriber attaches, the messages will be routed to the appropriate destination.</p> <p>To illustrate a subscription on a stand-alone router, you can use the examples that are provided with Qpid Proton. Using the _recv.py_ example receiver:</p> <pre><code>$ recv.py amqp://0.0.0.0/my-address </code></pre> <p>This command creates a receiving link subscribed to the specified address. To verify the subscription:</p> <pre><code>$ qdstat -a Router Addresses class address in-proc local remote in out thru to-proc from-proc ================================================================================ local $management Y 0 0 1 0 0 1 0 mobile my-address 1 0 0 0 0 0 0 local temp.fDt8_a 1 0 0 0 0 0 0 </code></pre> <p>You can then, in a separate command window, run a sender to produce messages to that address:</p> <pre><code>$ send.py -a amqp://0.0.0.0/my-address </code></pre> <h3 id="dynamic-reply-to">Dynamic Reply-To</h3> <p>Dynamic reply-to can be used to obtain a reply-to address that routes back to a client's receiving link regardless of how many hops it has to take to get there. To illustrate this feature, see below a simple program (written in C++ against the qpid::messaging API) that queries the management agent of the attached router for a list of other known routers' management addresses.</p> <pre><code>#include <qpid/messaging/Address.h> #include <qpid/messaging/Connection.h> #include <qpid/messaging/Message.h> #include <qpid/messaging/Receiver.h> #include <qpid/messaging/Sender.h> #include <qpid/messaging/Session.h> using namespace qpid::messaging; using namespace qpid::types; using std::stringstream; using std::string; int main() { const char* url = "amqp:tcp:127.0.0.1:5672"; std::string connectionOptions = "{protocol:amqp1.0}"; Connection connection(url, connectionOptions); connection.open(); Session session = connection.createSession(); Sender sender = session.createSender("mgmt"); // create reply receiver and get the reply-to address Receiver receiver = session.createReceiver("#"); Address responseAddress = receiver.getAddress(); Message request; request.setReplyTo(responseAddress); request.setProperty("x-amqp-to", "amqp:/_local/$management"); request.setProperty("operation", "DISCOVER-MGMT-NODES"); request.setProperty("type", "org.amqp.management"); request.setProperty("name, "self"); sender.send(request); Message response = receiver.fetch(); Variant content(response.getContentObject()); std::cout << "Response: " << content << std::endl << std::endl; connection.close(); } </code></pre> <p>The equivalent program written in Python against the Proton Messenger API:</p> <pre><code>from proton import Messenger, Message def main(): host = "0.0.0.0:5672" messenger = Messenger() messenger.start() messenger.route("amqp:/*", "amqp://%s/$1" % host) reply_subscription = messenger.subscribe("amqp:/#") reply_address = reply_subscription.address request = Message() response = Message() request.address = "amqp:/_local/$management" request.reply_to = reply_address request.properties = {u'operation' : u'DISCOVER-MGMT-NODES', u'type' : u'org.amqp.management', u'name' : u'self'} messenger.put(request) messenger.send() messenger.recv() messenger.get(response) print "Response: %r" % response.body messenger.stop() main() </code></pre> <h2 id="known-issues-and-limitations">Known Issues and Limitations</h2> <p>This is an early test release. It is expected that users will find bugs and other various instabilities. The main goal of this release is to prove that the process can be run and that users can demonstrate basic functionality as described in this document. Nevertheless, the following are known issues with the 0.1 release:</p> <ul> <li>Subscriber addresses are not always cleaned up after a consumer disconnects. See <a href="https://issues.apache.org/jira/browse/QPID-4964">https://issues.apache.org/jira/browse/QPID-4964</a>.</li> <li>Dispatch Router does not currently use the target address of a client's sender link to route messages. It only looks at the "to" field in the message's headers. See <a href="https://issues.apache.org/jira/browse/QPID-5175">https://issues.apache.org/jira/browse/QPID-5175</a>.</li> <li>All subscription sources are treated as multicast addresses. There is currently no facility for provisioning different types of addresses. Multicast means that if there are multiple subscribers to the same address, they will all receive a copy of each message sent to that address.</li> <li>SSL connectors and listeners are supported but very lightly (and not recently) tested.</li> <li>SASL authentication is not currently integrated into any authentication framework. Use ANONYMOUS for testing.</li> </ul> <h2 id="issues-addressed-in-this-release">Issues Addressed in this Release</h2> <ul> <li><a href="https://issues.apache.org/jira/browse/QPID-4612">QPID-4612</a> Dispatch - Change server and container pattern to be consistent with other objects</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4613">QPID-4613</a> Dispatch Message API Improvements</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4614">QPID-4614</a> CTEST for Dispatch</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4788">QPID-4788</a> Dispatch - Re-schedule of an "immediate" timer causes crash</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4816">QPID-4816</a> dispatch-router crashes when incomplete (but valid) url specified by client.</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4853">QPID-4853</a> Connectors are not closed when connections are closed cleanly</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4913">QPID-4913</a> Dispatch - Add a configuration file reader to configure the service</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4963">QPID-4963</a> Dispatch - Excessive latency in timers under light load</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4967">QPID-4967</a> Dispatch - Distributed routing protocol to compute paths across a network of routers</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4968">QPID-4968</a> Dispatch - Generalized framework for embedded Python modules</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4974">QPID-4974</a> Dispatch - Improve the API for parsing and composing AMQP-typed fields</li> <li><a href="https://issues.apache.org/jira/browse/QPID-4997">QPID-4997</a> Dispatch - Thread safety issues in the usage of Proton</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5001">QPID-5001</a> Dispatch - A web page on the site for the Dispatch Router component</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5045">QPID-5045</a> Dispatch - Refactor the router data structures to allow both message-based and link-based routing that supports full link protocol</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5064">QPID-5064</a> Dispatch - make-install doesn't install the Python artifacts</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5066">QPID-5066</a> Dispatch - move Python code into the qpid.dispatch package</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5068">QPID-5068</a> Dispatch - Internal feature to easily add and update Delivery Annotations</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5096">QPID-5096</a> Dispatch - Install the configuration file</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5097">QPID-5097</a> Dispatch - create a source tarball</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5173">QPID-5173</a> [dispatch] cmake ignores overrides to CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5181">QPID-5181</a> Dispatch - Assign temporary source addresses for dynamic listener links</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5185">QPID-5185</a> Move the qpid-dispatch.conf file to /etc/qpid</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5186">QPID-5186</a> Installing Dispatch should also install the LICENSE, TODO and related files</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5189">QPID-5189</a> Add a config.sh file for Qpid Dispatch to set an environment for running the router</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5201">QPID-5201</a> Dispatch - Fix build errors in Release mode</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5212">QPID-5212</a> Dispatch - Add management access to data in the router module</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5213">QPID-5213</a> Dispatch - Add a CLI tool to display manageable data in Dispatch</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5216">QPID-5216</a> Dispatch - Stabilization in anticipation of an early release</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5217">QPID-5217</a> Dispatch - Cleanup of API inconsistencies and oddities</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5218">QPID-5218</a> [dispatch] Crash when outgoing window > 0 and multiple subscribed Messenger clients</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5220">QPID-5220</a> Dispatch - Define Modes of Operation for the router function</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5221">QPID-5221</a> Dispatch - Configured connections can be annotated as to their role</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5257">QPID-5257</a> Dispatch - Move the code from trunk/qpid/extras to dispatch</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5258">QPID-5258</a> Dispatch - Prepare for Release 0.1</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5267">QPID-5267</a> Examples aren't being installed</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5310">QPID-5310</a> copy the correlationID into management replies</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5313">QPID-5313</a> qpid-dxrouterd binary should install the /usr/sbin on *nix</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5319">QPID-5319</a> Add ability to get list of connections through server management agent</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5335">QPID-5335</a> Dispatch Python libraries need to install to a private directory.</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5338">QPID-5338</a> The Dispatch top-level Python package should be renamed</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5339">QPID-5339</a> Dispatch - Intermittent crashes during scripted six-node tests</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5343">QPID-5343</a> Dispatch does not properly handle the drain protocol on senders.</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5350">QPID-5350</a> Dispatch - Management queries that receive empty tables results in corrupt response</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5351">QPID-5351</a> Settle on one prefix for Dispatch names</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5352">QPID-5352</a> Installation of python code ignores prefix</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5365">QPID-5365</a> Clean up file locations in Dispatch</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5367">QPID-5367</a> Dispatch - Add man pages and stubs for other documentation</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5380">QPID-5380</a> Dispatch - Simplify use of non-system instances</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5381">QPID-5381</a> Dispatch - Use dynamic source address for the reply-to in qdstat tool</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5392">QPID-5392</a> Dispatch - Remove ChangeLog; use jira and our website release pages instead</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5393">QPID-5393</a> Dispatch - Allow qdstat to query any router in the network from a connection</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5397">QPID-5397</a> Dispatch - Crash occurs when linked deliveries are concurrently settled</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5403">QPID-5403</a> Dispatch - The router-specific annotations have reserved keys</li> <li><a href="https://issues.apache.org/jira/browse/QPID-5448">QPID-5448</a> qdstat does not have the correct Python path for the internal libraries</li> </ul> <hr/> <ul id="-apache-navigation"> <li><a href="http://www.apache.org/">Apache</a></li> <li><a href="http://www.apache.org/licenses/">License</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="/security.html">Security</a></li> <li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li> </ul> <p id="-legal"> Apache Qpid, Messaging built on AMQP; Copyright © 2015 The Apache Software Foundation; Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton, Proton, Apache, the Apache feather logo, and the Apache Qpid project logo are trademarks of The Apache Software Foundation; All other marks mentioned may be trademarks or registered trademarks of their respective owners </p> </div> </div> </div> </body> </html>

content/components/dispatch-router/release-0.1.html (382 lines of code) (raw):