[qpid-dispatch] branch master updated: DISPATCH-1162 - Added a book section for setting up router networks

[tr...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tross pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/qpid-dispatch.git


The following commit(s) were added to refs/heads/master by this push:
     new c85bb83  DISPATCH-1162 - Added a book section for setting up router networks
c85bb83 is described below

commit c85bb83dbd201cab969fb0275969168967ebc1fa
Author: Ted Ross <tr...@redhat.com>
AuthorDate: Tue Dec 18 15:10:06 2018 -0500

    DISPATCH-1162 - Added a book section for setting up router networks
---
 docs/books/user-guide/book.adoc                    |   6 +-
 .../user-guide/modules/network-topologies.adoc     | 113 +++++++++++++++++++++
 2 files changed, 116 insertions(+), 3 deletions(-)

diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc
index 6cd1873..e3a2c0e 100644
--- a/docs/books/user-guide/book.adoc
+++ b/docs/books/user-guide/book.adoc
@@ -47,12 +47,12 @@ include::configuration-security.adoc[leveloffset=+1]
 // Routing
 include::routing.adoc[leveloffset=+1]
 
-// Logging
-include::logging.adoc[leveloffset=+1]
-
 // Network Topologies
 include::modules/network-topologies.adoc[leveloffset=+1]
 
+// Logging
+include::logging.adoc[leveloffset=+1]
+
 // Management
 include::management.adoc[leveloffset=+1]
 
diff --git a/docs/books/user-guide/modules/network-topologies.adoc b/docs/books/user-guide/modules/network-topologies.adoc
index e18314e..aeab0ab 100644
--- a/docs/books/user-guide/modules/network-topologies.adoc
+++ b/docs/books/user-guide/modules/network-topologies.adoc
@@ -23,4 +23,117 @@ under the License
 [id='network-topologies-{context}']
 = Building Networks of Routers
 
+{RouterName} can be deployed as a single router or as many routers deployed in
+a network of arbitrary topology.  Regardless of how routers are deployed, the
+message routing behavior experienced by connected clients is always the same.
+Even in a multi-site or hybrid-cloud network of routers, the connected
+endpoints appear to be connected to the same logical router with the same
+behavior that would be experienced on a single router running on a laptop.
 
+Because of this independence of messaging behavior and underlying network
+topology, the true power of {RouterName} is realized when it is deployed in
+networks.
+
+This section will describe the various router modes and how they are used to
+create different kinds of networks.
+
+[id='network-topologies-modes-{context}']
+== Router Operating Modes
+
+There are three router operating modes, as specified in the `router` section
+of the configuration:
+
+* `standalone` - This mode is used when there is exactly one router deployed.
+  A standalone router will not attempt to establish connectivity to another
+  router and will always operate as the sole network node.  This mode is not
+  particularly interesting and will not be discussed further.
+
+* `interior` - This mode is used for each router in the interior of a network
+  of routers.  Interior routers are connected to each other using `connector`
+  and `listener` configurations in the `inter-router` role.  There is au upper
+  limit of 128 total interior routers in a network.  Interior routers that are
+  connected together in an arbitrary topology automatically compute the lowest
+  cost paths across the network.
+
+* `edge` - Edge routers can join a network by establishing an `edge`
+  connection to an interior router.  There is no limit to the number of edge
+  routers that may be deployed in a network.  Edge routers are connected to
+  interior routers using `connector` and `listener` configurations in the
+  `edge` role.  An edge router may be connected to more than one interior
+  router but only one of the edge connections shall be active at one time.
+  Edge routers may not establish connections to other edge routers.  They are
+  pure leaves in the overall network topology.  Because there are no limits to
+  the number of edge routers deployed, they may be proliferated in high
+  numbers as sidecars in a container environment or one-per-host or
+  one-per-virtual-machine in a data center.
+
+[id='network-topologies-security-{context}']
+== A Word About Security
+
+When deploying a {RouterName} network, it is very important that the security
+and integrity of that network be considered.  This is particularly true of the
+interior portion of the network.  The integrity, security, and availability of
+a network will be severely compromised if unauthorized routers are permitted
+to join the interior network, or worse, unauthorized endpoints assuming the
+role of a router by establishing an inter-router connection into the network.
+For this reason, it is recommended that the interior routers of a network use
+a strong authentication mechanism to identify themselves to each other.
+
+A good way to establish solid interior router security is to create an x.509
+certificate authority that oversees the network with individual certificates
+generated for each interior router in the network.  The inter-router listeners
+are then configured to use the certificate authority as the authenticator for
+each incoming inter-router connection (using SASL mechanism `EXTERNAL` to
+enable x.509 client certificate authentication).  Edge connections and direct
+endpoint connections can use different levels of security, depending on the
+needs of the deployment.
+
+Using this method, a new router cannot join the network until the owner of the
+certificate authority issues a new certificate for the new router.  And an
+intruder wishing to spoof an interior router cannot do so unless it has a
+valid x.509 certificate issued by the network's certificate authority.
+
+[id='network-topologies-connection-notes-{context}']
+== General Notes About Connections Between Routers
+
+When a connection is established between routers, message traffic flows in
+both directions across that connection.  Each connection has a client side
+(connector) and a server side (listener) for the purposes of connection
+establishment, but once the connection is established, the two sides become
+equal participants in a bi-directional connection.  For the purposes of
+routing AMQP traffic across the network, the direction of connection
+establishment is not relevant.
+
+When establishing inter-router connections, the deployed must choose which
+router will be the listener and which will be the connector.  There should ne
+only one connection between any pair of routers.  There is no need, and it is
+in fact undesirable, to create two connections in opposite directions between
+to routers.  Don't do it.
+
+The selection of connector vs. listener is sometimes arbitrary because it
+doesn't matter.  In other cases, the direction may be important because of IP
+network boundaries and firewalls.  For example, to connect a router in a
+private IP network to another router in a public location (i.e. a public cloud
+provider), the router in the private network must have the connector and the
+router in the public location must have the listener.  This is because the
+public location cannot reach the private location via TCP/IP without the use
+of VPNs or other firewall features designed to allow public-to-private access.
+
+Sometimes the choice of connector vs. listener is dictated by the shape of the
+topology.  For example, a star-topology that has a series of routers connected
+to one or two central "hub" routers would most easily be set up with listeners
+on the hub and connectors on the spokes.  This way, new spoke routers may be
+added without changing the configuration of the hub.
+
+[id='network-topologies-examples-{context}']
+== Example Router Networks
+
+=== A Router Pair for Availability
+
+=== A Network for Multiple Cloud Sites
+
+=== A Network for Multiple Geographies
+
+=== Edge Routers Per-Server in a Data Center
+
+=== Edge Router for Inter-Process-Communication with an Uplink


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org