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-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org