| .. 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. |
| This feature was significantly updated in Qpid Dispatch 0.6. |
| |
| 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. Similarly, a receiver can |
| establish a link to a topic on a remote broker using a server-side |
| filter. |
| |
| 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: route-container |
| addr: <B2-url> |
| port: <B2-port> |
| sasl-mechanisms: ANONYMOUS |
| } |
| |
| This *route-container* 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: |
| |
| :: |
| |
| linkRoute { |
| prefix: b2 |
| dir: in |
| connection: broker |
| } |
| |
| linkRoute { |
| prefix: b2 |
| dir: out |
| connection: broker |
| } |
| |
| |
| The linkRoute 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 route-container |
| connector). |
| |
| Note that receiving and sending links are configured and routed |
| separately. This allows configuration of link routes for listeners |
| only or senders only. A direction of "in" matches client senders |
| (i.e. links that carry messages inbound to the router network). |
| Direction "out" matches client receivers. |
| |
| Examples of addresses that "begin with 'b2'" include: |
| - b2 |
| - b2.queues |
| - b2.queues.app1 |
| |
| When the route-container 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 identical configuration. It |
| is permissible for a linkRoute configuration to reference a connection |
| that does not exist. |
| |
| 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. |