You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by tr...@apache.org on 2015/03/19 21:20:28 UTC
svn commit: r1667867 - in /qpid/dispatch/trunk/doc/book: basic_usage.rst
client_compatibility.rst default_config.rst link_routing.rst
technical_details.rst tools.rst
Author: tross
Date: Thu Mar 19 20:20:28 2015
New Revision: 1667867
URL: http://svn.apache.org/r1667867
Log:
DISPATCH-128 - New files for the book
Added:
qpid/dispatch/trunk/doc/book/basic_usage.rst
qpid/dispatch/trunk/doc/book/client_compatibility.rst
qpid/dispatch/trunk/doc/book/default_config.rst
qpid/dispatch/trunk/doc/book/link_routing.rst
qpid/dispatch/trunk/doc/book/technical_details.rst
qpid/dispatch/trunk/doc/book/tools.rst
Added: qpid/dispatch/trunk/doc/book/basic_usage.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/basic_usage.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/basic_usage.rst (added)
+++ qpid/dispatch/trunk/doc/book/basic_usage.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,190 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Basic Usage and Examples
+========================
+
+Standalone and Interior Modes
+-----------------------------
+
+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.
+
+If your router is running in stand-alone mode, *qdstat -a* will look
+like the following:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 Y 0 0 1 0 0 1 0
+ local temp.4Q3i01lWbs 1 0 0 0 0 0 0
+
+Note that there are two known addresses. *$management* is the address of
+the router's embedded management agent. *temp.4Q3i01lWbs* is the temporary
+reply-to address of the *qdstat* client making requests to the agent.
+
+If you change the mode to interior and restart the processs, the same
+command will yield additional addresses which are used for
+inter-router communication:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 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 qdrouter.ma Y 0 0 0 0 0 0 0
+ local temp.2ot2AWsnYz 1 0 0 0 0 0 0
+
+Mobile Subscribers
+------------------
+
+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.
+
+To illustrate a subscription on a stand-alone router, you can use the
+examples that are provided with Qpid Proton. Using the *simple_recv.py* example
+receiver:
+
+::
+
+ $ python ./simple_recv.py -a 127.0.0.1/my-address
+
+This command creates a receiving link subscribed to the specified
+address. To verify the subscription:
+
+::
+
+ $ qdstat -a
+ Router Addresses
+ class address phase in-proc local remote in out thru to-proc from-proc
+ ===========================================================================================
+ local $management Y 0 0 0 0 0 0 0
+ mobile $management 0 Y 0 0 1 0 0 1 0
+ mobile my-address 0 1 0 0 0 0 0 0
+ local temp.JAgKj1+iB8 1 0 0 0 0 0 0
+
+
+You can then, in a separate command window, run a sender to produce
+messages to that address:
+
+::
+
+ $ python ./simple_send.py -a 127.0.0.1/my-address
+
+Dynamic Reply-To
+----------------
+
+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.
+
+::
+
+ #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();
+ }
+
+The equivalent program written in Python against the Proton Messenger
+API:
+
+::
+
+ 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()
+
Added: qpid/dispatch/trunk/doc/book/client_compatibility.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/client_compatibility.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/client_compatibility.rst (added)
+++ qpid/dispatch/trunk/doc/book/client_compatibility.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,45 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Client Compatibility
+====================
+
+Dispatch Router should, in theory, work with any client that is
+compatible with AMQP 1.0. The following clients have been tested:
+
++-----------------+------------------------------------------------------------------+
+| *Client* | *Notes* |
++=================+==================================================================+
+| qpid::messaging |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. |
+| | |
++-----------------+------------------------------------------------------------------+
+| Proton Reactor | The Proton Reactor API is compatible with Dispatch Router. |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
+| | |
++-----------------+------------------------------------------------------------------+
+| Proton Messenger| Messenger works with Dispatch Router. |
+| | |
+| | |
++-----------------+------------------------------------------------------------------+
Added: qpid/dispatch/trunk/doc/book/default_config.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/default_config.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/default_config.rst (added)
+++ qpid/dispatch/trunk/doc/book/default_config.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,33 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Configuration
+=============
+
+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.
+
+To run the router, invoke the executable: qdrouterd [-c my-config-file]
+
+For more details of the configuration file see the `qdrouterd.conf(5)`
+man page.
+
Added: qpid/dispatch/trunk/doc/book/link_routing.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/link_routing.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/link_routing.rst (added)
+++ qpid/dispatch/trunk/doc/book/link_routing.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,145 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Link Routing
+============
+
+This feature was introduced in Qpid Dispatch 0.4.
+
+Link-routing is an alternative strategy for routing messages across a
+network of routers. With the existing message-routing strategy, each
+router makes a routing decision on a per-message basis when the
+message is delivered. Link-routing is different because it makes
+routing decisions when link-attach frames arrive. A link is
+effectively chained across the network of routers from the
+establishing node to the destination node. Once the link is
+established, the transfer of message deliveries, flow frames, and
+dispositions is performed across the routed link.
+
+The main benefit to link-routing is that endpoints can use the full link
+protocol to interact with other endpoints in far-flung parts of the
+network. For example, a client can establish a receiver across the
+network to a queue on a remote broker and use link credit to control
+the flow of messages from the broker.
+
+Why would one want to do this? One reason is to provide client
+isolation. A network like the following can be deployed:
+
+::
+
+ Public Network
+ +-----------------+
+ | +-----+ |
+ | B1 | Rp | |
+ | +/--\-+ |
+ | / \ |
+ | / \ |
+ +----/--------\---+
+ / \
+ / \
+ / \
+ Private Net A / \ Private Net B
+ +--------------/--+ +---\-------------+
+ | +---/-+ | | +--\--+ |
+ | B2 | Ra | | | | Rb | C1 |
+ | +-----+ | | +-----+ |
+ | | | |
+ | | | |
+ +-----------------+ +-----------------+
+
+The clients in Private Net B can be constrained (by firewall policy)
+to only connect to the Router in their own network. Using
+link-routing, these clients can access queues, topics, and other AMQP
+services that are in the Public Network or even in Private Net A.
+
+For example, The router Ra can be configured to expose queues in
+broker B2 to the network. Client C1 can then establish a connection
+to Rb, the local router, open a subscribing link to "b2.event-queue",
+and receive messages stored on that queue in broker B2.
+
+C1 is unable to create a TCP/IP connection to B1 because of its
+isolation (and because B2 is itself in a private network). However,
+with link routing, C1 can interact with B2 using the AMQP link
+protocol.
+
+Note that in this case, neither C1 nor B2 have been modified in any
+way and neither need be aware of the fact that there is a
+message-router network between them.
+
+Configuration
+-------------
+
+Starting with the configured topology shown above, how is link-routing
+configured to support the example described above?
+
+First, router Ra needs to be told how to make a connection to the
+broker B2:
+
+::
+
+ connector {
+ name: broker
+ role: on-demand
+ addr: <B2-url>
+ port: <B2-port>
+ sasl-mechanisms: ANONYMOUS
+ }
+
+This *on-demand* connector tells the router how to connect to an
+external AMQP container when it is needed. The name "broker" will be
+used later to refer to this connection.
+
+Now, the router must be configured to route certain addresses to B2:
+
+::
+
+ linkRoutePattern {
+ prefix: b2.
+ connector: broker
+ }
+
+
+The linkRoutePattern tells router Ra that any sender or receiver that
+is attached with a target or source (respectively) whos address begins
+with "b2.", should be routed to the broker B2 (via the on-demand
+connector).
+
+When the on-demand connector is configured, router Ra establishes a
+connection to the broker. Once the connection is open, Ra tells the
+other routers (Rp and Rb) that it is a valid destination for
+link-routes to the "b2." prefix. This means that sender or receiver
+links attached to Rb or Rp will be routed via the shortest path to Ra
+where they are then routed outbound to the broker B2.
+
+On Rp and Rb, it is advisable to add the following configuration:
+
+::
+
+ linkRoutePattern {
+ prefix: b2.
+ }
+
+This configuration tells the routers that link-routing is intended to
+be available for targets and sources starting with "b2.". This is
+important because it is possible that B2 might be unavailable or shut
+off. If B2 is unreachable, Ra will not advertize itself as a
+destination for "b2." and the other routers might never know that
+"b2." was intended for link-routing.
+
+The above configuration allows Rb and Rp to reject attaches that
+should be routed to B2 with an error message that indicates that there
+is no route available to the destination.
Added: qpid/dispatch/trunk/doc/book/technical_details.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/technical_details.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/technical_details.rst (added)
+++ qpid/dispatch/trunk/doc/book/technical_details.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,32 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. Qpid Dispatch documentation master file, created by
+ sphinx-quickstart on Tue Feb 24 11:25:59 2015.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Technical Details and Specifications
+====================================
+
+.. toctree::
+ :maxdepth: 3
+
+ client_compatibility
+ addressing
+ amqp-mapping
+ schema
Added: qpid/dispatch/trunk/doc/book/tools.rst
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/tools.rst?rev=1667867&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/tools.rst (added)
+++ qpid/dispatch/trunk/doc/book/tools.rst Thu Mar 19 20:20:28 2015
@@ -0,0 +1,75 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Tools
+=====
+
+qdstat
+------
+
+*qdstat* is a command line tool that lets you view the status of a
+Dispatch Router. The following options are useful for seeing that the
+router is doing:
+
++----------+-----------------------------------------------------------------------------+
+| *Option* | *Description* |
++==========+=============================================================================+
+| -l |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 routbers. |
+| | |
++----------+-----------------------------------------------------------------------------+
+| -a |Print a list of addresses known to the router. |
++----------+-----------------------------------------------------------------------------+
+| -n |Print a list of known routers in the network. |
++----------+-----------------------------------------------------------------------------+
+| -c |Print a list of connections to the router. |
++----------+-----------------------------------------------------------------------------+
+
+For complete details see the `qdstat(8)` man page and the output of
+`qdstat --help`.
+
+qdmanage
+--------
+
+*qdmanage* is a general-purpose AMQP management client that allows you
+to not only view but modify the configuration of a running dispatch
+router.
+
+For example you can query all the connection entities in the router::
+
+ $ qdrouterd query --type connection
+
+To enable logging debug and higher level messages by default::
+
+ $ qdrouter update log/DEFAULT enable=debug+
+
+In fact, everything that can be configured in the configuration file can
+also be created in a running router via management. For example to
+create a new listener in a running router::
+
+ $ qdrouter create type=listener port=5555
+
+Now you can connect to port 5555, for exampple::
+
+ $ qdrouterd query -b localhost:5555 --type listener
+
+For complete details see the `qdmanage(8)` man page and the output of
+`qdmanage --help`. Also for details of what can be configured see the
+`qdrouterd.conf(5)` man page.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org