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 2018/10/18 18:22:43 UTC
[1/2] qpid-dispatch git commit: DISPATCH-1144: Improve overview and
getting started doc This closes #391
Repository: qpid-dispatch
Updated Branches:
refs/heads/master ba7144822 -> 40de39316
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/supported-standards-protocols.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/supported-standards-protocols.adoc b/docs/books/user-guide/modules/supported-standards-protocols.adoc
new file mode 100644
index 0000000..35ee3c4
--- /dev/null
+++ b/docs/books/user-guide/modules/supported-standards-protocols.adoc
@@ -0,0 +1,39 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// overview.adoc
+
+[id='supported-standards-protocols-{context}']
+= Supported standards and protocols
+
+{RouterName} supports the following industry-recognized standards and network protocols:
+
+* Version 1.0 of the Advanced Message Queueing Protocol (AMQP)
+* Modern TCP with IPv6
+
+[NOTE]
+====
+The details of distributed transactions (XA) within AMQP are not provided in the 1.0 version of the specification. AMQ Interconnect does not support XA transactions.
+====
+
+.Additional resources
+
+* link:http://www.amqp.org/resources/download[OASIS AMQP 1.0 Specification]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc b/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc
new file mode 100644
index 0000000..80300fa
--- /dev/null
+++ b/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc
@@ -0,0 +1,98 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// getting-started.adoc
+
+[id='viewing-default-router-configuration-file-{context}']
+= Viewing the default router configuration file
+
+The router's configuration file (`qdrouterd.conf`) controls the way in which the router functions. The default configuration file contains the minimum number of settings required for the router to run. As you become more familiar with the router, you can add to or change these settings, or create your own configuration files.
+
+By default, the router configuration file defines the following settings for the router:
+
+* Operating mode
+* How it listens for incoming connections
+* Routing patterns for the message routing mechanism
+
+.Procedure
+
+. Open the following file: `/etc/qpid-dispatch/qdrouterd.conf`.
++
+--
+When {RouterName} is installed, `qdrouterd.conf` is installed in this directory. When the router is started, it runs with the settings defined in this file.
+--
+
+. Review the default settings in `qdrouterd.conf`.
++
+--
+.Default Configuration File
+[options="nowrap"]
+----
+router {
+ mode: standalone // <1>
+ id: Router.A // <2>
+}
+
+listener { // <3>
+ host: 0.0.0.0
+ port: amqp
+ authenticatePeer: no
+}
+
+address { // <4>
+ prefix: closest
+ distribution: closest
+}
+
+address {
+ prefix: multicast
+ distribution: multicast
+}
+
+address {
+ prefix: unicast
+ distribution: closest
+}
+
+address {
+ prefix: exclusive
+ distribution: closest
+}
+
+address {
+ prefix: broadcast
+ distribution: multicast
+}
+----
+<1> By default, the router operates in _standalone_ mode. This means that it can only communicate with endpoints that are directly connected to it. It cannot connect to other routers, or participate in a router network.
+<2> The unique identifier of the router. This ID is used as the `container-id` (container name) at the AMQP protocol level. It is required, and the router will not start if this attribute is not defined.
+<3> The `listener` entity handles incoming connections from client endpoints. By default, the router listens on all network interfaces on the default AMQP port (5672).
+<4> By default, the router is configured to use the message routing mechanism. Each `address` entity defines how messages that are received with a particular address `prefix` should be distributed. For example, all messages with addresses that start with `closest` will be distributed using the `closest` distribution pattern.
+
+[NOTE]
+====
+If a client requests a message with an address that is not defined in the router's configuration file, the `balanced` distribution pattern will be used automatically.
+====
+--
+
+.Additional resources
+
+* For more information about the router configuration file (including available entities and attributes), see the {qdrouterdManPageLink}.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/what-routers-are.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/what-routers-are.adoc b/docs/books/user-guide/modules/what-routers-are.adoc
new file mode 100644
index 0000000..7c27413
--- /dev/null
+++ b/docs/books/user-guide/modules/what-routers-are.adoc
@@ -0,0 +1,47 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// overview.adoc
+
+[id='what-routers-are-{context}']
+= What routers are
+
+{RouterName} is an application layer program running as a normal user program or as a daemon. A running instance of {RouterName} is called a _router_.
+
+Routers do not take responsibility for messages::
+Routers transfer messages between producers and consumers, but unlike message brokers, they do not take responsibility for messages. Instead, routers propagate message settlement and disposition across a network such that delivery guarantees are met. That is, the router network will deliver the message – possibly through several intermediate routers – and then route the consumer's acknowledgement of that message back across the same path. The responsibility for the message is transfered from the producer to the consumer as if they were directly connected.
+
+Routers are combined to form router networks::
+Routers are often deployed in topologies of multiple routers called a router network. Routers use link-state routing protocols and algorithms similar to the Open Shortest Path First (OSPF) and Intermediate System to Intermediate System (IS-IS) protocols to calculate the best path from every message source to every message destination, and to recover quickly from failures. A router network relies on redundant network paths to provide continued connectivity in case of system or network failure.
+
+Routers enhance both direct and indirect messaging patterns::
+A messaging client can make a single AMQP connection into a router network and, over that connection, exchange messages with one or more message brokers connected to any router in the network. At the same time, the client can exchange messages directly with other endpoints without involving a broker at all.
++
+.Enhancing the use of message brokers
+====
+Routers can enhance a cluster of message brokers that provide a scalable, distributed work queue.
+
+The router network makes the broker cluster appear as a single queue, with producers publishing to a single address, and consumers subscribing to a single address. The router network can distribute work to any broker in the cluster, and collect work from any broker for any consumer.
+
+The routers improve the scalability of the broker cluster, because brokers can be added or removed from the cluster without affecting the clients.
+
+The routers also solve the common difficulty of "stuck messages". Without the router network, if a consumer is connected to a broker that does not have any messages (but other brokers in the cluster do have messages), you must either transfer the messages or leave them "stuck". The routers solve this issue, however, because all of the consumers are connected to all of the brokers through the router network. A message on any broker can be delivered to any of the consumers.
+====
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/routing.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/routing.adoc b/docs/books/user-guide/routing.adoc
index 417012e..508153f 100644
--- a/docs/books/user-guide/routing.adoc
+++ b/docs/books/user-guide/routing.adoc
@@ -102,6 +102,7 @@ Link routing supports local transactions to a single broker. Distributed transac
+
With a link route, consumers can provide server-side selectors for broker subscriptions.
+[id='configuring-message-routing']
== Configuring Message Routing
With message routing, routing is performed on messages as producers send them to a router. When a message arrives on a router, the router routes the message and its _settlement_ based on the message's _address_ and _routing pattern_.
@@ -128,13 +129,109 @@ Addresses determine how messages flow through your router network. An address de
When a router receives a message, it uses the message's address to determine where to send the message (either its destination or one step closer to its destination).
-// Do we need to specify that these are AMQP addresses? Should they be distinguished from generic message addresses?
+==== Mobile Addresses
+
+Routers consider addresses to be mobile such that any users of an
+address may be directly connected to any router in a network and may
+move around the topology. In cases where messages are broadcast to or
+balanced across multiple consumers, the address users may be connected
+to multiple routers in the network.
+
+Mobile addresses are rendezvous points for senders and receivers.
+Messages arrive at the mobile address and are dispatched to their
+destinations according to the routing defined for the mobile address.
+The details of these routing patterns are discussed later.
+
+Mobile addresses may be discovered during normal router operation or
+configured through management settings.
+
+===== Discovered Mobile Addresses
+
+Mobile addresses are created when a client creates a link to a source
+or destination address that is unknown to the router network.
+
+Suppose a service provider wants to offer _my-service_ that clients
+may use. The service provider must open a receiver link with source
+address _my-service_. The router creates a mobile address
+_my-service_ and propagates the address so that it is known to every
+router in the network.
+
+Later a client wants to use the service and creates a sending link
+with target address _my-service_. The router matches the service
+provider's receiver having source address _my-service_ to the client's
+sender having target address _my-service_ and routes messages between
+the two.
+
+Any number of other clients can create links to the service as
+well. The clients do not have to know where in the router network the
+service provider is physically located nor are the clients required to
+connect to a specific router to use the service. Regardless of how
+many clients are using the service the service provider needs only a
+single connection and link into the router network.
+
+Another view of this same scenario is when a client tries to use the
+service before service provider has connected to the network. In this
+case the router network creates the mobile address _my-service_ as
+before. However, since the mobile address has only client sender links
+and no receiver links the router stalls the clients and prevents them
+from sending any messages. Later, after the service provider connects
+and creates the receiver link, the router will issue credits to the
+clients and the messages will begin to flow between the clients and
+the service.
+
+The service provider can connect, disconnect, and reconnect from a
+different location without having to change any of the clients or
+their connections. Imagine having the service running on a
+laptop. One day the connection is from corporate headquarters and the
+next day the connection is from some remote location. In this case the
+service provider's computer will typically have different host IP
+addresses for each connection. Using the router network the service
+provider connects to the router network and offers the named service
+and the clients connect to the router network and consume from the
+named service. The router network routes messages between the mobile
+addresses effectively masking host IP addresses of the service
+provider and the client systems.
+
+===== Configured Mobile Addresses
+
+Mobile addresses may be configured using the router _autoLink_
+object. An address created via an _autoLink_ represents a queue,
+topic, or other service in an external broker. Logically the
+_autoLink_ addresses are treated by the router network as if the
+broker had connected to the router and offered the services itself.
+
+For each configured mobile address the router will create a single
+link to the external resource. Messages flow between sender links and
+receiver links the same regardless if the mobile address was
+discovered or configured.
+
+Multiple _autoLink_ objects may define the same address on multiple
+brokers. In this case the router network creates a sharded resource
+split between the brokers. Any client can seamlessly send and receive
+messages from either broker.
+
+Note that the brokers do not need to be clustered or federated to
+receive this treatment. The brokers may even be from different vendors
+or be different versions of the same broker yet still work together to
+provide a larger service platform.
-// Need to add something here about the difference between discovered vs. configured mobile addresses so that it's clear that with message routing, the router can either be proactive or reactive in the way it routes messages.
[id='routing-patterns-overview']
=== Routing Patterns
+Routing patterns define the paths that a message with a mobile address
+can take across a network. These routing patterns can be used for both
+direct routing, in which the router distributes messages between
+clients without a broker, and indirect routing, in which the router
+enables clients to exchange messages through a broker.
+
+Routing patterns fall into two categories: Anycast
+(Balanced and Closest) and Multicast. There is no concept of
+"unicast" in which there is only one consumer for an address.
+
+Anycast distribution delivers each message to one consumer whereas
+multicast distribution delivers each message to all consumers.
+
Each address has one of the following routing patterns, which define the path that a message with the address can take across the messaging network:
Balanced:: An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network.
@@ -192,6 +289,38 @@ This means that the message did not reach its destination.
This means that the message might or might not have reached its destination. The delivery is considered to be "in-doubt" and should be re-sent if "at least once" delivery is required.
* The link, session, or connection to {RouterName} was dropped, and all deliveries are "in-doubt".
+=== Routing Pattern Reliability
+
+The following table describes the levels of reliability provided by each routing pattern:
+
+[options="header",cols="30,70"]
+|===
+| Routing pattern | Reliable?
+
+| Anycast (Balanced or Closest)
+a| Yes, when the message deliveries are unsettled.
+
+There is a reliability contract that the router network abides by when delivering unsettled messages to anycast addresses. For every such delivery sent by a producer, the router network guarantees that one of the following outcomes will occur:
+
+* The delivery shall be settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer.
+
+* The delivery shall be settled with RELEASED disposition, meaning that the message was not delivered to any consumer.
+
+* The delivery shall be settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent.
+
+* The connection to the producer shall be dropped, signifying that all unsettled deliveries should now be considered in-doubt by the producer and later re-sent.
+
+| Multicast
+a| No.
+
+If a producer sends an unsettled delivery, the disposition may be ACCEPTED or RELEASED.
+
+* If ACCEPTED, there is no guarantee that the message was delivered to any consumer.
+
+* If RELEASED, the message was definitely not delivered to any consumer.
+
+|===
+
[id='routing-messages-between-clients']
=== Routing Messages Between Clients
@@ -521,6 +650,7 @@ The command output shows that Phase 1 of the address was used to deliver all thr
Even in a multi-router network, and with multiple producers and consumers for `queue.first`, all deliveries are routed through the queue on the connected broker.
====
+[id='configuring-link-routing']
== Configuring Link Routing
Link routing provides an alternative strategy for brokered messaging. A link route represents a private messaging path between a sender and a receiver in which the router passes the messages between end points. You can think of a link route as a "virtual connection" or "tunnel" that travels from a sender, through the router network, to a receiver.
@@ -529,7 +659,11 @@ With link routing, routing is performed on link-attach frames, which are chained
=== Link Route Addresses
-A link route address represents a broker queue, topic, or other service. When a client attaches a link route address to a router, the router propagates a link attachment to the broker resource identified by the address.
+A link route address represents a broker queue, topic, or other service. When a client attaches a link route address to a router, the router propagates a link attachment to the broker resource identified by the address.
+
+Using link route addresses, the router network does not participate in
+aggregated message distribution. The router simply passes message
+delivery and settlement between the two end points.
=== Link Route Routing Patterns
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org
[2/2] qpid-dispatch git commit: DISPATCH-1144: Improve overview and
getting started doc This closes #391
Posted by tr...@apache.org.
DISPATCH-1144: Improve overview and getting started doc
This closes #391
Project: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/commit/40de3931
Tree: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/tree/40de3931
Diff: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/diff/40de3931
Branch: refs/heads/master
Commit: 40de3931637e6986563524776dacfdd15b8b6aad
Parents: ba71448
Author: Ben Hardesty <bh...@redhat.com>
Authored: Mon Aug 20 12:41:32 2018 -0400
Committer: Ted Ross <tr...@redhat.com>
Committed: Thu Oct 18 14:22:01 2018 -0400
----------------------------------------------------------------------
docs/books/_common/attributes.adoc | 87 ++++++++++++
docs/books/_common/document_conventions.adoc | 27 ++++
.../_common/fragment-router-install-intro.adoc | 25 ++++
.../_common/fragment-router-install-steps.adoc | 27 ++++
.../_common/fragment-router-sasl-para.adoc | 20 +++
.../_common/fragment-starting-router-step.adoc | 29 ++++
docs/books/_images/01-peer-to-peer.png | Bin 0 -> 20101 bytes
docs/books/_images/balanced-routing.png | Bin 0 -> 43261 bytes
docs/books/_images/brokered-messaging.png | Bin 0 -> 50206 bytes
docs/books/_images/closest-routing.png | Bin 0 -> 39803 bytes
docs/books/_images/console1.png | Bin 0 -> 40412 bytes
docs/books/_images/console_charts.png | Bin 0 -> 70070 bytes
docs/books/_images/console_entity.png | Bin 0 -> 69319 bytes
docs/books/_images/console_login.png | Bin 0 -> 39915 bytes
docs/books/_images/console_overview.png | Bin 0 -> 87960 bytes
docs/books/_images/console_schema.png | Bin 0 -> 68025 bytes
docs/books/_images/console_topology.png | Bin 0 -> 67338 bytes
docs/books/_images/link-routing.png | Bin 0 -> 46968 bytes
docs/books/_images/message-routing.png | Bin 0 -> 35861 bytes
docs/books/_images/multicast-routing.png | Bin 0 -> 44923 bytes
docs/books/_images/path-redundancy-01.png | Bin 0 -> 47995 bytes
docs/books/_images/path-redundancy-02.png | Bin 0 -> 42131 bytes
.../path-redundancy-temp-decoupling-01.png | Bin 0 -> 47766 bytes
.../path-redundancy-temp-decoupling-02.png | Bin 0 -> 49105 bytes
docs/books/_images/sharded-queue-01.png | Bin 0 -> 28383 bytes
docs/books/_images/sharded-queue-02.png | Bin 0 -> 62233 bytes
.../books/common/fragment-router-sasl-para.adoc | 20 ---
.../common/fragment-starting-router-step.adoc | 29 ----
docs/books/user-guide/_common | 1 +
docs/books/user-guide/_images | 1 +
docs/books/user-guide/assemblies/_common | 1 +
.../user-guide/assemblies/getting-started.adoc | 42 ++++++
.../assemblies/important-terms-concepts.adoc | 39 ++++++
docs/books/user-guide/assemblies/modules | 1 +
docs/books/user-guide/assemblies/overview.adoc | 35 +++++
docs/books/user-guide/attributes.adoc | 78 -----------
docs/books/user-guide/book.adoc | 15 +-
docs/books/user-guide/common | 1 -
.../user-guide/configuration-connections.adoc | 34 ++++-
.../user-guide/configuration-security.adoc | 2 +
.../books/user-guide/images/01-peer-to-peer.png | Bin 20101 -> 0 bytes
.../user-guide/images/balanced-routing.png | Bin 43261 -> 0 bytes
.../user-guide/images/brokered-messaging.png | Bin 50206 -> 0 bytes
.../books/user-guide/images/closest-routing.png | Bin 39803 -> 0 bytes
docs/books/user-guide/images/console1.png | Bin 40412 -> 0 bytes
docs/books/user-guide/images/console_charts.png | Bin 70070 -> 0 bytes
docs/books/user-guide/images/console_entity.png | Bin 69319 -> 0 bytes
docs/books/user-guide/images/console_login.png | Bin 39915 -> 0 bytes
.../user-guide/images/console_overview.png | Bin 87960 -> 0 bytes
docs/books/user-guide/images/console_schema.png | Bin 68025 -> 0 bytes
.../user-guide/images/console_topology.png | Bin 67338 -> 0 bytes
docs/books/user-guide/images/link-routing.png | Bin 46968 -> 0 bytes
.../books/user-guide/images/message-routing.png | Bin 35861 -> 0 bytes
.../user-guide/images/multicast-routing.png | Bin 44923 -> 0 bytes
.../user-guide/images/path-redundancy-01.png | Bin 47995 -> 0 bytes
.../user-guide/images/path-redundancy-02.png | Bin 42131 -> 0 bytes
.../path-redundancy-temp-decoupling-01.png | Bin 47766 -> 0 bytes
.../path-redundancy-temp-decoupling-02.png | Bin 49105 -> 0 bytes
.../user-guide/images/sharded-queue-01.png | Bin 28383 -> 0 bytes
.../user-guide/images/sharded-queue-02.png | Bin 62233 -> 0 bytes
docs/books/user-guide/modules/_common | 1 +
docs/books/user-guide/modules/_images | 1 +
.../modules/how-routers-connect-endpoints.adoc | 52 +++++++
.../modules/how-routers-route-messages.adoc | 73 ++++++++++
.../user-guide/modules/installing-router.adoc | 31 ++++
docs/books/user-guide/modules/key-features.adoc | 32 +++++
docs/books/user-guide/modules/link-routing.adoc | 43 ++++++
.../user-guide/modules/message-routing.adoc | 112 +++++++++++++++
docs/books/user-guide/modules/next-steps.adoc | 42 ++++++
.../user-guide/modules/overview-of-amqp.adoc | 46 ++++++
.../user-guide/modules/router-management.adoc | 49 +++++++
.../user-guide/modules/router-security.adoc | 43 ++++++
.../modules/sending-test-messages.adoc | 97 +++++++++++++
.../user-guide/modules/starting-router.adoc | 65 +++++++++
.../modules/supported-standards-protocols.adoc | 39 ++++++
...ewing-default-router-configuration-file.adoc | 98 +++++++++++++
.../user-guide/modules/what-routers-are.adoc | 47 +++++++
docs/books/user-guide/routing.adoc | 140 ++++++++++++++++++-
78 files changed, 1387 insertions(+), 138 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/attributes.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/attributes.adoc b/docs/books/_common/attributes.adoc
new file mode 100644
index 0000000..01e6f3f
--- /dev/null
+++ b/docs/books/_common/attributes.adoc
@@ -0,0 +1,87 @@
+////
+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
+////
+
+// Standard document attributes
+
+:data-uri!:
+:doctype: article
+:experimental:
+:idprefix:
+:imagesdir: _images
+:numbered:
+:sectanchors!:
+:sectnums:
+:source-highlighter: highlightjs
+:highlightjs-theme: solarized_dark
+:toc: left
+:linkattrs:
+:toclevels: 3
+
+// Component attributes
+
+:ProductName: Apache Qpid
+:RouterLongName: {ProductName} Dispatch Router
+:ClientAmqpPythonName: {ProductName} Proton Python
+:ConsoleName: {RouterLongName} Console
+:FragmentDir: _common
+:RouterName: Dispatch Router
+:RouterSchemaDir: ../../build/doc/book
+:DispatchRouterVersion: 1.0.1
+
+// Book names
+
+:RouterBook: Using {RouterLongName}
+
+// Doc links
+
+:DispatchRouterUrlBase: https://qpid.apache.org/releases/qpid-dispatch-{DispatchRouterVersion}
+
+:DispatchRouterDownloadUrl: https://qpid.apache.org/download.html
+:DispatchRouterDownloadLink: link:{DispatchRouterDownloadUrl}[Download page^]
+
+:DispatchRouterPackagesUrl: https://qpid.apache.org/packages.html
+:DispatchRouterPackagesLink: link:{DispatchRouterPackagesUrl}[Packages page^]
+
+:ManagementEntitiesUrl: {DispatchRouterUrlBase}/man/managementschema.html
+:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^]
+
+:RouterBookUrl: {DispatchRouterUrlBase}/book/book.html
+:RouterBookLink: link:{RouterBookUrl}[{RouterBook}]
+
+:qdmanageManPageUrl: {DispatchRouterUrlBase}/man/qdmanage.html
+:qdmanageManPageLink: link:{qdmanageManPageUrl}[qdmanage man page^]
+
+:qdrouterdManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.html
+:qdrouterdManPageLink: link:{qdrouterdManPageUrl}[qdrouterd man page^]
+
+:qdrouterdConfManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.conf.html
+:qdrouterdConfManPageLink: link:{qdrouterdConfManPageUrl}[qdrouterd.conf man page^]
+
+:qdstatManPageUrl: {DispatchRouterUrlBase}/man/qdstat.html
+:qdstatManPageLink: link:{qdstatManPageUrl}[qdstat man page^]
+
+:QpidDispatchReadmeUrl: https://git-wip-us.apache.org/repos/asf?p=qpid-dispatch.git;a=blob_plain;f=README;hb={DispatchRouterVersion}
+:QpidDispatchReadmeLink: link:{QpidDispatchReadmeUrl}[Qpid Dispatch README^]
+
+:ClientAmqpPythonUrl: https://qpid.apache.org/proton/
+
+// Other links
+
+:AmqpSpecUrl: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html
+:AmqpSpecLink: link:{AmqpSpecUrl}[AMQP 1.0 specification^]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/document_conventions.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/document_conventions.adoc b/docs/books/_common/document_conventions.adoc
new file mode 100644
index 0000000..7762cb9
--- /dev/null
+++ b/docs/books/_common/document_conventions.adoc
@@ -0,0 +1,27 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// overview.adoc
+
+[id='document-conventions-{context}']
+= Document conventions
+
+In this document, `sudo` is used for any command that requires root privileges. You should always exercise caution when using `sudo`, as any changes can affect the entire system.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-install-intro.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/fragment-router-install-intro.adoc b/docs/books/_common/fragment-router-install-intro.adoc
new file mode 100644
index 0000000..aa1d1fb
--- /dev/null
+++ b/docs/books/_common/fragment-router-install-intro.adoc
@@ -0,0 +1,25 @@
+////
+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
+////
+
+{RouterName} is distributed as a set of RPM packages, which are available for `yum`/`dnf`-based Linux distributions. Alternatively, you can build the {RouterName} from source.
+
+[NOTE]
+====
+{RouterName} will not build on Windows.
+====
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-install-steps.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/fragment-router-install-steps.adoc b/docs/books/_common/fragment-router-install-steps.adoc
new file mode 100644
index 0000000..21ccc81
--- /dev/null
+++ b/docs/books/_common/fragment-router-install-steps.adoc
@@ -0,0 +1,27 @@
+////
+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
+////
+
+* Do one of the following:
+
+** Download and build the {RouterName} source.
++
+To download the source, see {DispatchRouterDownloadLink}. For instructions on building the source, see the {QpidDispatchReadmeLink}.
+** Install the {RouterName} packages.
++
+Packages are available for `yum`/`dnf`-based Linux distributions. For more information, see the {DispatchRouterPackagesLink}.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-sasl-para.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/fragment-router-sasl-para.adoc b/docs/books/_common/fragment-router-sasl-para.adoc
new file mode 100644
index 0000000..c6264e4
--- /dev/null
+++ b/docs/books/_common/fragment-router-sasl-para.adoc
@@ -0,0 +1,20 @@
+////
+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
+////
+
+To see a list of Cyrus SASL plugins in a `dnf`-based Linux system, use the `dnf search cyrus-sasl` command. To install a Cyrus SASL plugin, use the `dnf install _PLUGIN_` command.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-starting-router-step.adoc
----------------------------------------------------------------------
diff --git a/docs/books/_common/fragment-starting-router-step.adoc b/docs/books/_common/fragment-starting-router-step.adoc
new file mode 100644
index 0000000..22142ac
--- /dev/null
+++ b/docs/books/_common/fragment-starting-router-step.adoc
@@ -0,0 +1,29 @@
+////
+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
+////
+
+. To start the router, use the *`qdrouterd`* command.
++
+--
+This example uses the default configuration to start the router as a daemon:
+
+[source,bash,options="nowrap"]
+----
+$ qdrouterd -d
+----
+--
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/01-peer-to-peer.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/01-peer-to-peer.png b/docs/books/_images/01-peer-to-peer.png
new file mode 100644
index 0000000..5c834aa
Binary files /dev/null and b/docs/books/_images/01-peer-to-peer.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/balanced-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/balanced-routing.png b/docs/books/_images/balanced-routing.png
new file mode 100644
index 0000000..fedcdbf
Binary files /dev/null and b/docs/books/_images/balanced-routing.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/brokered-messaging.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/brokered-messaging.png b/docs/books/_images/brokered-messaging.png
new file mode 100644
index 0000000..ae129d4
Binary files /dev/null and b/docs/books/_images/brokered-messaging.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/closest-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/closest-routing.png b/docs/books/_images/closest-routing.png
new file mode 100644
index 0000000..ba3f0a5
Binary files /dev/null and b/docs/books/_images/closest-routing.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console1.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console1.png b/docs/books/_images/console1.png
new file mode 100644
index 0000000..f131884
Binary files /dev/null and b/docs/books/_images/console1.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_charts.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_charts.png b/docs/books/_images/console_charts.png
new file mode 100644
index 0000000..169c2ca
Binary files /dev/null and b/docs/books/_images/console_charts.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_entity.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_entity.png b/docs/books/_images/console_entity.png
new file mode 100644
index 0000000..130c7e7
Binary files /dev/null and b/docs/books/_images/console_entity.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_login.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_login.png b/docs/books/_images/console_login.png
new file mode 100644
index 0000000..63e22c6
Binary files /dev/null and b/docs/books/_images/console_login.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_overview.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_overview.png b/docs/books/_images/console_overview.png
new file mode 100644
index 0000000..af25f36
Binary files /dev/null and b/docs/books/_images/console_overview.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_schema.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_schema.png b/docs/books/_images/console_schema.png
new file mode 100644
index 0000000..ba56c7b
Binary files /dev/null and b/docs/books/_images/console_schema.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_topology.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/console_topology.png b/docs/books/_images/console_topology.png
new file mode 100644
index 0000000..ae4b22a
Binary files /dev/null and b/docs/books/_images/console_topology.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/link-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/link-routing.png b/docs/books/_images/link-routing.png
new file mode 100644
index 0000000..0c1b9e4
Binary files /dev/null and b/docs/books/_images/link-routing.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/message-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/message-routing.png b/docs/books/_images/message-routing.png
new file mode 100644
index 0000000..42f4638
Binary files /dev/null and b/docs/books/_images/message-routing.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/multicast-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/multicast-routing.png b/docs/books/_images/multicast-routing.png
new file mode 100644
index 0000000..d4548a6
Binary files /dev/null and b/docs/books/_images/multicast-routing.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-01.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/path-redundancy-01.png b/docs/books/_images/path-redundancy-01.png
new file mode 100644
index 0000000..ba8f10d
Binary files /dev/null and b/docs/books/_images/path-redundancy-01.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-02.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/path-redundancy-02.png b/docs/books/_images/path-redundancy-02.png
new file mode 100644
index 0000000..6d4a1f5
Binary files /dev/null and b/docs/books/_images/path-redundancy-02.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-temp-decoupling-01.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/path-redundancy-temp-decoupling-01.png b/docs/books/_images/path-redundancy-temp-decoupling-01.png
new file mode 100644
index 0000000..c3c6631
Binary files /dev/null and b/docs/books/_images/path-redundancy-temp-decoupling-01.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-temp-decoupling-02.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/path-redundancy-temp-decoupling-02.png b/docs/books/_images/path-redundancy-temp-decoupling-02.png
new file mode 100644
index 0000000..ecab8b1
Binary files /dev/null and b/docs/books/_images/path-redundancy-temp-decoupling-02.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/sharded-queue-01.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/sharded-queue-01.png b/docs/books/_images/sharded-queue-01.png
new file mode 100644
index 0000000..ab25be0
Binary files /dev/null and b/docs/books/_images/sharded-queue-01.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/sharded-queue-02.png
----------------------------------------------------------------------
diff --git a/docs/books/_images/sharded-queue-02.png b/docs/books/_images/sharded-queue-02.png
new file mode 100644
index 0000000..7e73e6d
Binary files /dev/null and b/docs/books/_images/sharded-queue-02.png differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/common/fragment-router-sasl-para.adoc
----------------------------------------------------------------------
diff --git a/docs/books/common/fragment-router-sasl-para.adoc b/docs/books/common/fragment-router-sasl-para.adoc
deleted file mode 100644
index c6264e4..0000000
--- a/docs/books/common/fragment-router-sasl-para.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-////
-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
-////
-
-To see a list of Cyrus SASL plugins in a `dnf`-based Linux system, use the `dnf search cyrus-sasl` command. To install a Cyrus SASL plugin, use the `dnf install _PLUGIN_` command.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/common/fragment-starting-router-step.adoc
----------------------------------------------------------------------
diff --git a/docs/books/common/fragment-starting-router-step.adoc b/docs/books/common/fragment-starting-router-step.adoc
deleted file mode 100644
index 4e9117b..0000000
--- a/docs/books/common/fragment-starting-router-step.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-////
-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
-////
-
-. To start the router, use the *`qdrouterd`* command.
-+
---
-This example uses the default configuration to start the router as a daemon:
-
-[options="nowrap"]
-----
-$ qdrouterd -d
-----
---
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/_common
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/_common b/docs/books/user-guide/_common
new file mode 120000
index 0000000..7c77149
--- /dev/null
+++ b/docs/books/user-guide/_common
@@ -0,0 +1 @@
+../_common
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/_images
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/_images b/docs/books/user-guide/_images
new file mode 120000
index 0000000..6d8b580
--- /dev/null
+++ b/docs/books/user-guide/_images
@@ -0,0 +1 @@
+../_images
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/_common
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/assemblies/_common b/docs/books/user-guide/assemblies/_common
new file mode 120000
index 0000000..739f516
--- /dev/null
+++ b/docs/books/user-guide/assemblies/_common
@@ -0,0 +1 @@
+../../_common
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/getting-started.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/assemblies/getting-started.adoc b/docs/books/user-guide/assemblies/getting-started.adoc
new file mode 100644
index 0000000..019c05f
--- /dev/null
+++ b/docs/books/user-guide/assemblies/getting-started.adoc
@@ -0,0 +1,42 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// book.adoc
+
+[id='getting-started-{context}']
+= Getting started
+
+This section shows you how to install {RouterName} on a single host, start the router with the default configuration settings, and distribute messages between two clients.
+
+// Installing Dispatch Router
+include::modules/installing-router.adoc[leveloffset=+1]
+
+// Viewing the default router configuration file
+include::modules/viewing-default-router-configuration-file.adoc[leveloffset=+1]
+
+// Starting the router
+include::modules/starting-router.adoc[leveloffset=+1]
+
+// Sending some test messages
+include::modules/sending-test-messages.adoc[leveloffset=+1]
+
+// Next steps
+include::modules/next-steps.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/important-terms-concepts.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/assemblies/important-terms-concepts.adoc b/docs/books/user-guide/assemblies/important-terms-concepts.adoc
new file mode 100644
index 0000000..83a42ff
--- /dev/null
+++ b/docs/books/user-guide/assemblies/important-terms-concepts.adoc
@@ -0,0 +1,39 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// overview.adoc
+
+[id='important-terms-concepts-{context}']
+= Important terms and concepts
+
+Before using {RouterName}, you should be familiar with AMQP and understand some key concepts about {RouterName}.
+
+include::modules/overview-of-amqp.adoc[leveloffset=+1]
+
+include::modules/what-routers-are.adoc[leveloffset=+1]
+
+// include::modules/how-routers-connect-endpoints.adoc[leveloffset=+1]
+
+include::modules/how-routers-route-messages.adoc[leveloffset=+1]
+
+include::modules/router-security.adoc[leveloffset=+1]
+
+include::modules/router-management.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/modules
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/assemblies/modules b/docs/books/user-guide/assemblies/modules
new file mode 120000
index 0000000..464b823
--- /dev/null
+++ b/docs/books/user-guide/assemblies/modules
@@ -0,0 +1 @@
+../modules
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/overview.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/assemblies/overview.adoc b/docs/books/user-guide/assemblies/overview.adoc
new file mode 100644
index 0000000..3474443
--- /dev/null
+++ b/docs/books/user-guide/assemblies/overview.adoc
@@ -0,0 +1,35 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// book.adoc
+
+[id='overview-{context}']
+= Overview
+
+{RouterName} is a lightweight AMQP message router for building scalable, available, and performant messaging networks.
+
+include::modules/key-features.adoc[leveloffset=+1]
+
+include::modules/supported-standards-protocols.adoc[leveloffset=+1]
+
+include::important-terms-concepts.adoc[leveloffset=+1]
+
+include::_common/document_conventions.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/attributes.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/attributes.adoc b/docs/books/user-guide/attributes.adoc
deleted file mode 100644
index 0162710..0000000
--- a/docs/books/user-guide/attributes.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-////
-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
-////
-
-// Standard document attributes
-
-:data-uri!:
-:doctype: article
-:experimental:
-:idprefix:
-:imagesdir: images
-:numbered:
-:sectanchors!:
-:sectnums:
-:source-highlighter: highlightjs
-:highlightjs-theme: solarized_dark
-:toc: left
-:linkattrs:
-:toclevels: 3
-
-// Component attributes
-
-:ProductName: Apache Qpid
-:RouterLongName: {ProductName} Dispatch Router
-:ClientAmqpPythonName: {ProductName} Proton Python
-:ConsoleName: {RouterLongName} Console
-:FragmentDir: common
-:RouterName: Dispatch Router
-:RouterSchemaDir: ../../build/doc/book
-:DispatchRouterVersion: 1.0.1
-
-// Book names
-
-:RouterBook: Using {RouterLongName}
-
-// Doc links
-
-:DispatchRouterUrlBase: https://qpid.apache.org/releases/qpid-dispatch-{DispatchRouterVersion}
-
-:ManagementEntitiesUrl: {DispatchRouterUrlBase}/man/managementschema.html
-:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^]
-
-:RouterBookUrl: {DispatchRouterUrlBase}/book/book.html
-:RouterBookLink: link:{RouterBookUrl}[{RouterBook}]
-
-:qdmanageManPageUrl: {DispatchRouterUrlBase}/man/qdmanage.html
-:qdmanageManPageLink: link:{qdmanageManPageUrl}[qdmanage man page^]
-
-:qdrouterdManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.html
-:qdrouterdManPageLink: link:{qdrouterdManPageUrl}[qdrouterd man page^]
-
-:qdrouterdConfManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.conf.html
-:qdrouterdConfManPageLink: link:{qdrouterdConfManPageUrl}[qdrouterd.conf man page^]
-
-:qdstatManPageUrl: {DispatchRouterUrlBase}/man/qdstat.html
-:qdstatManPageLink: link:{qdstatManPageUrl}[qdstat man page^]
-
-:ClientAmqpPythonUrl: https://qpid.apache.org/proton/
-
-// Other links
-
-:AmqpSpecUrl: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html
-:AmqpSpecLink: link:{AmqpSpecUrl}[AMQP 1.0 specification^]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/book.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc
index 4ed6bdf..ca0f2c6 100644
--- a/docs/books/user-guide/book.adoc
+++ b/docs/books/user-guide/book.adoc
@@ -17,18 +17,23 @@ specific language governing permissions and limitations
under the License
////
-include::attributes.adoc[]
+include::_common/attributes.adoc[]
+
+:context: router
= {RouterBook}
+// Overview
+include::assemblies/overview.adoc[leveloffset=+1]
+
// Introduction
-include::introduction.adoc[leveloffset=+1]
+// include::introduction.adoc[leveloffset=+1]
// Theory of Operation
-include::theory_of_operation.adoc[leveloffset=+1]
+// include::theory_of_operation.adoc[leveloffset=+1]
-// Getting Started
-include::getting-started.adoc[leveloffset=+1]
+// Getting started
+include::assemblies/getting-started.adoc[leveloffset=+1]
// Configuration
include::understand-router-configuration.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/common
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/common b/docs/books/user-guide/common
deleted file mode 120000
index 60d3b0a..0000000
--- a/docs/books/user-guide/common
+++ /dev/null
@@ -1 +0,0 @@
-../common
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/configuration-connections.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/configuration-connections.adoc b/docs/books/user-guide/configuration-connections.adoc
index 26e10a2..5c24422 100644
--- a/docs/books/user-guide/configuration-connections.adoc
+++ b/docs/books/user-guide/configuration-connections.adoc
@@ -25,7 +25,21 @@ Connections define how the router communicates with clients, other routers, and
[id='adding-incoming-connections']
== Listening for Incoming Connections
-Listening for incoming connections involves setting the host and port on which the router should listen for traffic.
+{RouterName} provides _listeners_ that accept client connections.
+A client connecting to a router listener uses the
+same methods that it would use to connect to a broker. From the
+client's perspective, the router connection and link establishment are
+identical to broker connection and link establishment.
+
+Several types of listeners are defined by their role.
+
+[options="header",cols="20,80"]
+|===
+| Role | Description
+| normal | The connection is used for AMQP clients using normal message delivery.
+| inter-router | The connection is assumed to be to another router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.
+| route-container | The connection is a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the remote resource has created a connection.
+|===
.Procedure
@@ -56,7 +70,23 @@ If you have set up SSL/TLS or SASL in your environment, you can configure the ro
[id='adding-outgoing-connections']
== Adding Outgoing Connections
-Configuring outgoing connections involves setting the host and port on which the router connects to other routers and brokers.
+You can configure {RouterName} to create outbound connections to
+messaging brokers or other AMQP entities using _connectors_. A
+connector is defined with the network address of the broker and the
+name or names of the resources that are available in that broker. When
+a router connects to a broker through a connector, it uses the same
+methods a normal messaging client would use when connecting to the
+broker.
+
+Several types of connectors are defined by their role.
+
+[options="header",cols="20,80"]
+|===
+| Role | Description
+| normal | The connection is used for AMQP clients using normal message delivery. On this connector the router will initiate the connection but it will never create any links. Links are to be created by the peer that accepts the connection.
+| inter-router | The connection is assumed to be to another router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.
+| route-container | The connection is to a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the router has created a connection to the remote resource.
+|===
// Adding this here for now; in the future it might be better to have separate procedures for creating inter-router and route-container connections.
When a router connects to a broker, the broker might provide backup connection data that the router can use if the primary connection fails. If the primary connection fails, the router attempts to reconnect by using a combination of the primary and -- if provided -- backup connections in round-robin fashion until the connection is successful. For more information about viewing the backup connection data provided by the broker, see xref:managing-connectors[].
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/configuration-security.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/configuration-security.adoc b/docs/books/user-guide/configuration-security.adoc
index 8c632a6..a21c5d6 100644
--- a/docs/books/user-guide/configuration-security.adoc
+++ b/docs/books/user-guide/configuration-security.adoc
@@ -22,6 +22,7 @@ under the License
Securing your router network involves configuring authentication and authorization. You can authenticate and encrypt the router's connections using SSL/TLS or SASL. Additionally, you can authorize access to messaging resources by setting user connection restrictions and defining AMQP resource access control.
+[id='authenticating-remote-peers']
== Authenticating Remote Peers
You can configure {RouterName} to communicate with clients, routers, and brokers in a secure way by authenticating and encrypting the router's connections. {RouterName} supports the following security protocols:
@@ -440,6 +441,7 @@ listener {
For more information about these attributes, see xref:adding-sasl-authentication-to-incoming-connection[].
--
+[id='authorizing-access-to-messaging-resources']
== Authorizing Access to Messaging Resources
You can configure _policies_ to secure messaging resources in your messaging environment. Policies ensure that only authorized users can access messaging endpoints through the router network, and that the resources on those endpoints are used in an authorized way.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/01-peer-to-peer.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/01-peer-to-peer.png b/docs/books/user-guide/images/01-peer-to-peer.png
deleted file mode 100644
index 5c834aa..0000000
Binary files a/docs/books/user-guide/images/01-peer-to-peer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/balanced-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/balanced-routing.png b/docs/books/user-guide/images/balanced-routing.png
deleted file mode 100644
index fedcdbf..0000000
Binary files a/docs/books/user-guide/images/balanced-routing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/brokered-messaging.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/brokered-messaging.png b/docs/books/user-guide/images/brokered-messaging.png
deleted file mode 100644
index ae129d4..0000000
Binary files a/docs/books/user-guide/images/brokered-messaging.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/closest-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/closest-routing.png b/docs/books/user-guide/images/closest-routing.png
deleted file mode 100644
index ba3f0a5..0000000
Binary files a/docs/books/user-guide/images/closest-routing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console1.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console1.png b/docs/books/user-guide/images/console1.png
deleted file mode 100644
index f131884..0000000
Binary files a/docs/books/user-guide/images/console1.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_charts.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_charts.png b/docs/books/user-guide/images/console_charts.png
deleted file mode 100644
index 169c2ca..0000000
Binary files a/docs/books/user-guide/images/console_charts.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_entity.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_entity.png b/docs/books/user-guide/images/console_entity.png
deleted file mode 100644
index 130c7e7..0000000
Binary files a/docs/books/user-guide/images/console_entity.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_login.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_login.png b/docs/books/user-guide/images/console_login.png
deleted file mode 100644
index 63e22c6..0000000
Binary files a/docs/books/user-guide/images/console_login.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_overview.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_overview.png b/docs/books/user-guide/images/console_overview.png
deleted file mode 100644
index af25f36..0000000
Binary files a/docs/books/user-guide/images/console_overview.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_schema.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_schema.png b/docs/books/user-guide/images/console_schema.png
deleted file mode 100644
index ba56c7b..0000000
Binary files a/docs/books/user-guide/images/console_schema.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_topology.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/console_topology.png b/docs/books/user-guide/images/console_topology.png
deleted file mode 100644
index ae4b22a..0000000
Binary files a/docs/books/user-guide/images/console_topology.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/link-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/link-routing.png b/docs/books/user-guide/images/link-routing.png
deleted file mode 100644
index 0c1b9e4..0000000
Binary files a/docs/books/user-guide/images/link-routing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/message-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/message-routing.png b/docs/books/user-guide/images/message-routing.png
deleted file mode 100644
index 42f4638..0000000
Binary files a/docs/books/user-guide/images/message-routing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/multicast-routing.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/multicast-routing.png b/docs/books/user-guide/images/multicast-routing.png
deleted file mode 100644
index d4548a6..0000000
Binary files a/docs/books/user-guide/images/multicast-routing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-01.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/path-redundancy-01.png b/docs/books/user-guide/images/path-redundancy-01.png
deleted file mode 100644
index ba8f10d..0000000
Binary files a/docs/books/user-guide/images/path-redundancy-01.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-02.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/path-redundancy-02.png b/docs/books/user-guide/images/path-redundancy-02.png
deleted file mode 100644
index 6d4a1f5..0000000
Binary files a/docs/books/user-guide/images/path-redundancy-02.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png b/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png
deleted file mode 100644
index c3c6631..0000000
Binary files a/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png b/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png
deleted file mode 100644
index ecab8b1..0000000
Binary files a/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/sharded-queue-01.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/sharded-queue-01.png b/docs/books/user-guide/images/sharded-queue-01.png
deleted file mode 100644
index ab25be0..0000000
Binary files a/docs/books/user-guide/images/sharded-queue-01.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/sharded-queue-02.png
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/images/sharded-queue-02.png b/docs/books/user-guide/images/sharded-queue-02.png
deleted file mode 100644
index 7e73e6d..0000000
Binary files a/docs/books/user-guide/images/sharded-queue-02.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/_common
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/_common b/docs/books/user-guide/modules/_common
new file mode 120000
index 0000000..739f516
--- /dev/null
+++ b/docs/books/user-guide/modules/_common
@@ -0,0 +1 @@
+../../_common
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/_images
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/_images b/docs/books/user-guide/modules/_images
new file mode 120000
index 0000000..fe463e8
--- /dev/null
+++ b/docs/books/user-guide/modules/_images
@@ -0,0 +1 @@
+../../_images
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc b/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc
new file mode 100644
index 0000000..eb7e117
--- /dev/null
+++ b/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc
@@ -0,0 +1,52 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// important-terms-concepts.adoc
+
+[id='how-routers-connect-endpoints-{context}']
+= How routers connect endpoints
+
+{RouterName} connects clients, servers, AMQP services, and other routers through network connections. Routers use _listeners_ to accept incoming connections, and _connectors_ to establish outgoing connections.
+
+The following table describes how routers connect to clients, other routers, and message brokers:
+
+[cols="30,70",options="header"]
+|===
+| To connect to... | The router uses...
+
+| Clients
+| _Normal_ listeners and connectors.
+
+Clients can connect to a router using the same methods they would use to connect to a message broker. From the client's perspective, the connection to the router and link establishment are identical to a broker connection and link establishment.
+
+Routers can also connect to clients for normal message delivery. In this type of connection, the router initiates the connection, but does not create any links. Links are only created by the peer that accepts the connection.
+
+| Routers
+| _Inter-router_ listeners and connectors.
+
+Inter-router discovery and routing protocols are enabled over these types of connections.
+
+| Message brokers
+| _Route-container_ listeners and connectors.
+
+A router can accept connections from message brokers or any resource that hosts known AMQP addresses. Routers can also connect to these types of resources.
+
+|===
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/how-routers-route-messages.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/how-routers-route-messages.adoc b/docs/books/user-guide/modules/how-routers-route-messages.adoc
new file mode 100644
index 0000000..34c596b
--- /dev/null
+++ b/docs/books/user-guide/modules/how-routers-route-messages.adoc
@@ -0,0 +1,73 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// important-terms-concepts.adoc
+
+[id='how-routers-route-messages-{context}']
+= How routers route messages
+
+In a router network, _routing_ is the process by which messages are delivered to their destinations. To accomplish this, {RouterName} offers two different routing mechanisms:
+
+Message routing::
+Message routing enables you to distribute messages in anycast and multicast patterns. These patterns can be used for both direct routing, in which the router distributes messages between clients without a message broker, and indirect routing, in which the router enables clients to exchange messages through a message broker.
++
+Message routing is useful for the following types of requirements:
++
+--
+* Default, basic message routing
++
+{RouterName} automatically routes messages by default, so manual configuration is only required if you want routing behavior that is different than the default.
+
+* Message-based routing patterns
++
+Message routing supports both anycast and multicast routing patterns. You can load-balance individual messages across multiple consumers, and multicast (or fan-out) messages to multiple subscribers.
+
+* Sharding messages across multiple message brokers when message delivery order is not important
++
+Sharding messages from one producer might cause that producer’s messages to be received in a different order than the order in which they were sent.
+--
+
+Link routing::
+Link routing enables you to establish a dedicated, virtual "path" between a sender and receiver that travels through the router network. Link routes are typically used to connect clients to message brokers in scenarios in which a direct connection is unfeasible. Therefore, link routes enable messaging capabilities that are not possible with message routing, such as:
++
+--
+* Transactional messaging
++
+Link routing supports local transactions to a single broker. Distributed transactions are not supported.
+
+* Guaranteed message delivery order
++
+Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance.
+
+* End-to-end flow control
++
+Flow control is "real" in that credits flow across the link route from the receiver to the sender.
+
+* Server-side selectors
++
+With a link route, consumers can provide server-side selectors for broker subscriptions.
+--
+
+.Additional resources
+
+* xref:configuring-message-routing[]
+
+* xref:configuring-link-routing[]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/installing-router.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/installing-router.adoc b/docs/books/user-guide/modules/installing-router.adoc
new file mode 100644
index 0000000..f870357
--- /dev/null
+++ b/docs/books/user-guide/modules/installing-router.adoc
@@ -0,0 +1,31 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// getting-started.adoc
+
+[id='installing-router-{context}']
+= Installing {RouterName}
+
+include::{FragmentDir}/fragment-router-install-intro.adoc[]
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-install-steps.adoc[]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/key-features.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/key-features.adoc b/docs/books/user-guide/modules/key-features.adoc
new file mode 100644
index 0000000..808e910
--- /dev/null
+++ b/docs/books/user-guide/modules/key-features.adoc
@@ -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
+////
+
+// Module included in the following assemblies:
+//
+// overview.adoc
+
+[id='key-features-{context}']
+= Key features
+
+You can use {RouterName} to flexibly route messages between any AMQP-enabled endpoints, including clients, servers, and message brokers. {RouterName} provides the following benefits:
+
+* Connects clients and message brokers into an internet-scale messaging network with uniform addressing
+* Supports high-performance direct messaging
+* Uses redundant network paths to route around failures
+* Streamlines the management of large deployments
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/link-routing.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/link-routing.adoc b/docs/books/user-guide/modules/link-routing.adoc
new file mode 100644
index 0000000..d7fae9f
--- /dev/null
+++ b/docs/books/user-guide/modules/link-routing.adoc
@@ -0,0 +1,43 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// routing.adoc
+
+[id='link-routing-{context}']
+= Link routing
+
+Link routing enables you to establish a dedicated, virtual "path" between a sender and receiver that travels through the router network. Link routes are typically used to connect clients to message brokers in scenarios in which a direct connection is unfeasible. Therefore, link routes enable messaging capabilities that are not possible with message routing, such as:
+
+* Transactional messaging
++
+Link routing supports local transactions to a single broker. Distributed transactions are not supported.
+
+* Guaranteed message delivery order
++
+Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance.
+
+* End-to-end flow control
++
+Flow control is "real" in that credits flow across the link route from the receiver to the sender.
+
+* Server-side selectors
++
+With a link route, consumers can provide server-side selectors for broker subscriptions.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/message-routing.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/message-routing.adoc b/docs/books/user-guide/modules/message-routing.adoc
new file mode 100644
index 0000000..6aa9df9
--- /dev/null
+++ b/docs/books/user-guide/modules/message-routing.adoc
@@ -0,0 +1,112 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// routing.adoc
+
+[id='message-routing-{context}']
+= Message routing
+
+Message routing enables you to distribute messages in anycast and multicast patterns. These patterns can be used for both direct routing, in which the router distributes messages between clients without a message broker, and indirect routing, in which the router enables clients to exchange messages through a message broker.
+
+With message routing, messages are routed based on their _addresses_, and the _routing pattern_ defined for the address.
+
+[discrete]
+== Addresses
+
+An _address_ is the name of a message source or destination endpoint in the messaging network. AMQP addresses control the flow of messages across the router network.
+
+Addresses can designate various types of entities in a messaging network, such as:
+
+* Endpoint processes that consume data or offer a service
+* Topics that match multiple consumers to multiple producers
+* Entities within a message broker:
+** Queues
+** Durable Topics
+** Exchanges
+
+When a router receives a message, it uses the message’s address to determine where to send the message (either its destination or one step closer to its destination).
+
+[NOTE]
+====
+{RouterName} treats addresses as opaque strings. Therefore, when creating addresses, you can use whatever syntax makes the most sense for your environment.
+====
+
+[discrete]
+== What mobile addresses are
+
+Addresses used in message routing are sometimes called _mobile addresses_, because ...
+
+[discrete]
+== Routing patterns
+
+Routing patterns define the paths that a message with a mobile address can take across a network. These routing patterns can be used for both direct routing, in which the router distributes messages between clients without a broker, and indirect routing, in which the router enables clients to exchange messages through a broker.
+
+{RouterName} supports two categories of routing patterns: anycast and multicast.
+
+[NOTE]
+====
+{RouterName} does not provide a true "unicast" routing pattern in which there is only one consumer for an address.
+====
+
+[options="header"]
+|===
+| Routing pattern | Description | Reliability
+
+| Anycast
+a| Each message is delivered to one consumer. There are two types of anycast methods:
+
+* Balanced
++
+Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network. This method allows multiple consumers to use the same address.
+
+* Closest
++
+Each message is sent along the shortest path to reach the destination, even if there are other consumers for the same address.
+
+| Reliable for unsettled message deliveries.
+
+| Multicast
+| Each message is delivered to all consumers. Each consumer will receive one copy of the message.
+| Unreliable. If a producer sends an unsettled delivery, the router automatically settles the delivery with ACCEPTED disposition regardless of whether the message was delivered to any consumers.
+
+|===
+
+[discrete]
+== Quality of service for message deliveries
+
+{RouterName} can deliver messages with any of the following levels of reliability:
+
+* At most once
+* At least once
+* Exactly once
+
+The level of reliability is negotiated between the client and router when the client establishes a link to the router. The router achieves this negotiated level of reliability by treating messages as either _pre-settled_ or _unsettled_.
+
+Pre-settled::
+Sometimes called "fire and forget", the router settles the incoming and outgoing deliveries and propagates the settlement to the message’s destination. However, it does not guarantee delivery.
+
+Unsettled::
+The router propagates the settlement between the producer and consumer, and guarantees one of the following outcomes:
++
+* The delivery is settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer.
+* The delivery is settled with RELEASED disposition, meaning that the message was not delivered to any consumer.
+* The delivery is settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent.
+* The connection to the producer is dropped, signifying that all unsettled deliveries should now be considered in-doubt by the producer and re-sent.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/next-steps.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/next-steps.adoc b/docs/books/user-guide/modules/next-steps.adoc
new file mode 100644
index 0000000..83a1369
--- /dev/null
+++ b/docs/books/user-guide/modules/next-steps.adoc
@@ -0,0 +1,42 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// getting-started.adoc
+
+[id='next-steps-{context}']
+= Next steps
+
+After you successfully install a standalone router and use it to distribute messages between two clients, you can configure the router to make it production-ready, and add additional routers to form a router network.
+
+Configure the router::
+You can configure the router to meet the requirements of your production environment.
++
+--
+* Secure the router:
+** Add authentication to control which users can connect to the router
+** Add authorization to control what messaging resources those users can access
+* Configure addresses to specify routing patterns for direct-routed (brokerless) messaging
+* Connect the router to a message broker to enable clients to exchange messages with a broker queue.
+* Create link routes to define private messaging paths between endpoints.
+--
+
+Deploy a router network::
+After deploying a single router, you can deploy additional routers and connect them together to form a router network. Router networks can be any arbitrary topology.
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/overview-of-amqp.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/overview-of-amqp.adoc b/docs/books/user-guide/modules/overview-of-amqp.adoc
new file mode 100644
index 0000000..dcd2a12
--- /dev/null
+++ b/docs/books/user-guide/modules/overview-of-amqp.adoc
@@ -0,0 +1,46 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// important-terms-concepts.adoc
+
+[id='overview-of-amqp-{context}']
+= Overview of AMQP
+
+{RouterName} implements version 1.0 of the Advanced Message Queueing Protocol (AMQP) specification. Therefore, you should understand several key AMQP terms and concepts before deploying or configuring {RouterName}.
+
+Containers::
+AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. In AMQP, a container is any application that sends or receives messages, such as a client application or message broker.
++
+Containers connect to each other over _connections_, which are channels for communication.
+
+Nodes::
+Containers contain addressable entities called _nodes_ that are responsible for storing or delivering messages. For example, a queue on a message broker is a node.
+
+Links::
+Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages.
++
+Links are established over _sesssions_, which are contexts for sending and receiving messages. Sessions are established over connections.
+
+.Additional resources
+
+* link:http://www.amqp.org/resources/download[OASIS AMQP 1.0 Specification]
+* link:https://dzone.com/refcardz/amqp-essentials?chapter=1[AMQP Essentials Refcard]
+* link:https://channel9.msdn.com/Blogs/Subscribe/The-AMQP-10-Protocol-16-Overview[Video series introducing AMQP 1.0]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/router-management.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/router-management.adoc b/docs/books/user-guide/modules/router-management.adoc
new file mode 100644
index 0000000..91e0ca5
--- /dev/null
+++ b/docs/books/user-guide/modules/router-management.adoc
@@ -0,0 +1,49 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// important-terms-concepts.adoc
+
+[id='router-management-{context}']
+= Router management
+
+{RouterName} provides both graphical and CLI tools for monitoring and managing a router network.
+
+{RouterLongName} Console::
+A web console for monitoring the layout and health of the router network.
+
+qdstat::
+A command-line tool for monitoring the status of a router in the router network. Using this tool, you can view the following information about a router:
+
+* Incoming and outgoing connections
+* Incoming and outgoing links
+* Router network topology from the perspective of this router
+* Addresses known to this router
+* Link routes and autolinks
+* Memory consumption information
+
+qdmanage::
+A command-line tool for viewing and updating the configuration of a router at runtime.
+
+.Additional resources
+
+* xref:console-overview[]
+* xref:monitoring-using-qdstat[]
+* xref:managing-router[]
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/router-security.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/router-security.adoc b/docs/books/user-guide/modules/router-security.adoc
new file mode 100644
index 0000000..b11f928
--- /dev/null
+++ b/docs/books/user-guide/modules/router-security.adoc
@@ -0,0 +1,43 @@
+////
+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
+////
+
+// Module included in the following assemblies:
+//
+// important-terms-concepts.adoc
+
+[id='router-security-{context}']
+= Router security
+
+{RouterName} provides authentication and authorization mechanisms so that you can control who can access the router network, and what they can do with the messaging resources.
+
+Authentication::
+{RouterName} supports both SSL/TLS and SASL for encrypting and authenticating remote peers. Using these mechanisms, you can secure the router network in the following ways:
+
+* Authenticate incoming connections from remote peers (such as clients and message brokers)
+* Provide authentication credentials for outgoing connections to remote peers (such as clients and message brokers)
+* Secure the inter-router connections between the routers in the router network
+
+Authorization::
+{RouterName} provides a `policy` mechanism that you can use to enforce user connection restrictions and AMQP resource access control.
+
+.Additional resources
+
+* xref:authenticating-remote-peers[]
+
+* xref:authorizing-access-to-messaging-resources[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/sending-test-messages.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/sending-test-messages.adoc b/docs/books/user-guide/modules/sending-test-messages.adoc
new file mode 100644
index 0000000..85b9f44
--- /dev/null
+++ b/docs/books/user-guide/modules/sending-test-messages.adoc
@@ -0,0 +1,97 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// getting-started.adoc
+
+[id='sending-test-messages-{context}']
+= Sending test messages
+
+After starting the router, send some test messages to see how the router can connect two endpoints by distributing messages between them.
+
+This procedure demonstrates a simple configuration consisting of a single router with two clients connected to it: a sender and a receiver. The receiver wants to receive messages on a specific address, and the sender sends
+messages to that address.
+
+A broker is not used in this procedure, so there is no _"store and forward"_ mechanism in the middle. Instead, the messages flow from the sender, through the router, to the receiver only if the receiver is online, and the sender can confirm that the messages have arrived at their destination.
+
+.Prerequisites
+
+{ClientAmqpPythonName} must be installed. For more information, see {ClientAmqpPythonUrl}.
+
+.Procedure
+
+. Navigate to the {ClientAmqpPythonName} Python examples directory.
++
+--
+[source,bash,options="nowrap",subs="+quotes"]
+----
+$ cd __<install-dir>__/examples/python/
+----
+
+<install-dir>:: The directory where you installed {ClientAmqpPythonName}.
+--
+
+. Start the `simple_recv.py` receiver client.
++
+--
+[source,bash,options="nowrap"]
+----
+$ python simple_recv.py -a 127.0.0.1:5672/examples -m 5
+----
+
+This command starts the receiver and listens on the `examples` address (`127.0.0.1:5672/examples`). The receiver is also set to receive a maximum of five messages.
+
+[NOTE]
+====
+In practice, the order in which you start senders and receivers does not matter. In both cases, messages will be sent as soon as the receiver comes online.
+====
+--
+
+. In a new terminal window, navigate to the Python examples directory and run the `simple_send.py` example:
++
+--
+[source,bash,options="nowrap",subs="+quotes"]
+----
+$ cd __<install-dir>__/examples/python/
+$ python simple_send.py -a 127.0.0.1:5672/examples -m 5
+----
+
+This command sends five auto-generated messages to the `examples` address (`127.0.0.1:5672/examples`) and then confirms that they were delivered and acknowledged by the receiver:
+
+[source,bash,options="nowrap"]
+----
+all messages confirmed
+----
+--
+
+. Verify that the receiver client received the messages.
++
+--
+The receiver client should display the contents of the five messages:
+
+[source,bash,options="nowrap"]
+----
+{u'sequence': 1L}
+{u'sequence': 2L}
+{u'sequence': 3L}
+{u'sequence': 4L}
+{u'sequence': 5L}
+----
+--
http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/starting-router.adoc
----------------------------------------------------------------------
diff --git a/docs/books/user-guide/modules/starting-router.adoc b/docs/books/user-guide/modules/starting-router.adoc
new file mode 100644
index 0000000..14e8bdf
--- /dev/null
+++ b/docs/books/user-guide/modules/starting-router.adoc
@@ -0,0 +1,65 @@
+////
+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
+////
+
+// This assembly is included in the following assemblies:
+//
+// getting-started.adoc
+
+[id='starting-router-{context}']
+= Starting the router
+
+After installing {RouterName}, you start the router by using the `qdrouterd` command.
+
+.Procedure
+
+// Step 1 for starting the router.
+include::{FragmentDir}/fragment-starting-router-step.adoc[]
++
+The router starts, using the default configuration file stored at `/etc/qpid-dispatch/qdrouterd.conf`.
+
+. View the log to verify the router status:
++
+[source,bash,options="nowrap"]
+----
+$ qdstat --log
+----
++
+This example shows that the router was correctly installed, is running, and is ready to route traffic between clients:
++
+[options="nowrap"]
+----
+$ qdstat --log
+Fri May 20 09:38:03 2017 SERVER (info) Container Name: Router.A
+Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone mode
+Fri May 20 09:38:03 2017 ROUTER_CORE (info) Router Core thread running. 0/Router.A
+Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription M/$management
+Fri May 20 09:38:03 2017 AGENT (info) Activating management agent on $_management_internal
+Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$management
+Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$_management_internal
+Fri May 20 09:38:03 2017 DISPLAYNAME (info) Activating DisplayNameService on $displayname
+Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$displayname
+Fri May 20 09:38:03 2017 CONN_MGR (info) Configured Listener: 0.0.0.0:amqp proto=any role=normal
+Fri May 20 09:38:03 2017 POLICY (info) Policy configured maximumConnections: 0, policyFolder: '', access rules enabled: 'false'
+Fri May 20 09:38:03 2017 POLICY (info) Policy fallback defaultApplication is disabled
+Fri May 20 09:38:03 2017 SERVER (info) Operational, 4 Threads Running
+----
+
+.Additional resources
+
+* The {qdrouterdManPageLink}.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org