docs/books/modules/user-guide/network-topologies.adoc - qpid-dispatch - Git at Google

 ////
 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:
 //

 [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 an 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 deployer must choose which
 router will be the listener and which will be the connector.  There should be
 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
 two 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.
	////
	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:
	//

	[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 an 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 deployer must choose which
	router will be the listener and which will be the connector. There should be
	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
	two 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.