You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by gm...@apache.org on 2019/06/08 02:39:17 UTC
[qpid-dispatch] branch master updated: DISPATCH-1338 - Improvements
to edge router documentation. This closes #512
This is an automated email from the ASF dual-hosted git repository.
gmurthy 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 b055c12 DISPATCH-1338 - Improvements to edge router documentation. This closes #512
b055c12 is described below
commit b055c12e19cc75063b5ac5669e1221c1eb62e91d
Author: Ben Hardesty <bh...@redhat.com>
AuthorDate: Fri May 24 16:04:53 2019 -0400
DISPATCH-1338 - Improvements to edge router documentation. This closes #512
---
docs/books/_common/attributes.adoc | 5 +-
.../fragment-router-open-config-file-step.adoc | 2 +
.../configuring-network-connections.adoc | 46 ++
.../user-guide/assemblies/configuring-router.adoc | 47 ++
.../creating-router-network-topology.adoc | 49 ++
.../planning-router-network.adoc} | 26 +-
.../securing-incoming-client-connections.adoc | 44 ++
.../assemblies/securing-network-connections.adoc | 45 ++
.../assemblies/securing-outgoing-connections.adoc | 42 ++
...figuration-security.adoc => authorization.adoc} | 504 +++------------------
docs/books/user-guide/book.adoc | 39 +-
docs/books/user-guide/configuration-security.adoc | 454 +------------------
docs/books/user-guide/management.adoc | 14 +-
.../modules/adding-routers-router-network.adoc | 69 +++
.../modules/configuring-router-properties.adoc | 64 +++
...onnecting-routers-external-amqp-containers.adoc | 57 +++
.../user-guide/modules/connecting-routers.adoc | 89 ++++
...ecting-using-mutual-ssl-tls-authentication.adoc | 78 ++++
...cting-using-one-way-ssl-tls-authentication.adoc | 65 +++
...ing-using-username-password-authentication.adoc | 58 +++
.../user-guide/modules/connection-failover.adoc | 51 +--
.../enabling-ssl-tls-client-authentication.adoc | 62 +++
.../modules/enabling-ssl-tls-encryption.adoc | 82 ++++
.../enabling-username-password-authentication.adoc | 78 ++++
.../example-router-network-topologies.adoc} | 24 +-
.../modules/integrating-with-kerberos.adoc | 87 ++++
.../modules/listening-client-connections.adoc | 61 +++
docs/books/user-guide/modules/next-steps.adoc | 19 +-
.../modules/router-connection-considerations.adoc | 45 ++
.../user-guide/modules/router-management.adoc | 4 +-
.../router-network-security-considerations.adoc | 47 ++
.../user-guide/modules/router-operating-modes.adoc | 36 ++
docs/books/user-guide/modules/router-security.adoc | 4 +-
.../securing-connections-between-routers.adoc | 118 +++++
.../user-guide/modules/sending-test-messages.adoc | 4 +-
docs/books/user-guide/modules/starting-router.adoc | 2 +-
docs/books/user-guide/routing.adoc | 98 +++-
37 files changed, 1586 insertions(+), 1033 deletions(-)
diff --git a/docs/books/_common/attributes.adoc b/docs/books/_common/attributes.adoc
index 37caae5..8fd1341 100644
--- a/docs/books/_common/attributes.adoc
+++ b/docs/books/_common/attributes.adoc
@@ -42,7 +42,8 @@ under the License
:FragmentDir: _common
:RouterName: Dispatch Router
:RouterSchemaDir: ../../build/doc/book
-:DispatchRouterVersion: 1.0.1
+:RouterConfigFile: /etc/qpid-dispatch/qdrouterd.conf
+:DispatchRouterVersion: 1.7.0
// Book names
@@ -59,7 +60,7 @@ under the License
:DispatchRouterPackagesLink: link:{DispatchRouterPackagesUrl}[Packages page^]
:ManagementEntitiesUrl: {DispatchRouterUrlBase}/man/managementschema.html
-:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^]
+:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^]
:RouterBookUrl: {DispatchRouterUrlBase}/book/book.html
:RouterBookLink: link:{RouterBookUrl}[{RouterBook}]
diff --git a/docs/books/_common/fragment-router-open-config-file-step.adoc b/docs/books/_common/fragment-router-open-config-file-step.adoc
new file mode 100644
index 0000000..5fcf33f
--- /dev/null
+++ b/docs/books/_common/fragment-router-open-config-file-step.adoc
@@ -0,0 +1,2 @@
+
+. Open the `{RouterConfigFile}` configuration file.
diff --git a/docs/books/user-guide/assemblies/configuring-network-connections.adoc b/docs/books/user-guide/assemblies/configuring-network-connections.adoc
new file mode 100644
index 0000000..74a21ed
--- /dev/null
+++ b/docs/books/user-guide/assemblies/configuring-network-connections.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
+////
+
+// This assembly is included in the following assemblies:
+//
+// adding-routers-router-network.adoc
+
+[id='configuring-network-connections-{context}']
+= Configuring network connections
+
+{RouterName} connects clients, servers, AMQP services, and other routers through network connections. To connect the router to other messaging endpoints, you configure _listeners_ to accept connections, and _connectors_ to make outbound connections. However, connections are bidirectional - once the connection is established, message traffic flows in both directions.
+
+You can configure the following types of connections:
+
+`inter-router`:: The connection is for another interior router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.
+`normal`:: The connection is for AMQP clients using normal message delivery.
+`edge`:: The connection is between an edge router and an interior router.
+`route-container`:: The connection is for a broker or other resource that holds known addresses.
+
+// Connecting routers
+include::modules/connecting-routers.adoc[leveloffset=+1]
+
+// Listening for client connections
+include::modules/listening-client-connections.adoc[leveloffset=+1]
+
+// Creating a connection to an external AMQP container
+include::modules/connecting-routers-external-amqp-containers.adoc[leveloffset=+1]
+
+// Connection failover
+include::modules/connection-failover.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/assemblies/configuring-router.adoc b/docs/books/user-guide/assemblies/configuring-router.adoc
new file mode 100644
index 0000000..25b15a6
--- /dev/null
+++ b/docs/books/user-guide/assemblies/configuring-router.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
+////
+
+// This assembly is included in the following assemblies:
+//
+// book.adoc
+
+[id='configuring-router-{context}']
+= Configuring a router
+
+Each {RouterName} router contains a `qdrouterd.conf` configuration file. You edit this file to define how the router should operate.
+
+You can configure the following entities:
+
+* Essential router properties
+* Network connections
+* Security settings (authentication and authorization)
+* Routing (message routing and link routing)
+* Logging
+
+// Configuring router properties
+include::modules/configuring-router-properties.adoc[leveloffset=+1]
+
+// Configuring network connections
+include::configuring-network-connections.adoc[leveloffset=+1]
+
+// Securing network connections
+include::securing-network-connections.adoc[leveloffset=+1]
+
+// Authorizing access to messaging resources
+include::../authorization.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/assemblies/creating-router-network-topology.adoc b/docs/books/user-guide/assemblies/creating-router-network-topology.adoc
new file mode 100644
index 0000000..ae7242c
--- /dev/null
+++ b/docs/books/user-guide/assemblies/creating-router-network-topology.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
+////
+
+// This assembly is included in the following assemblies:
+//
+// book.adoc
+
+[id='creating-router-network-topology-{context}']
+= Creating a router network topology
+
+You can deploy {RouterName} as a single standalone router, or as multiple routers connected together in a router network. Router networks may represent any arbitrary topology, enabling you to design the network to best fit your requirements.
+
+With {RouterName}, the router network topology is independent from the message routing. This means that messaging clients always experience the same message routing behavior regardless of the underlying network topology. Even in a multi-site or hybrid cloud router network, the connected endpoints behave as if they were connected to a single, logical router.
+
+To create the router network topology, complete the following:
+
+. xref:planning-router-network-router[Plan the router network].
++
+You should understand the different router operating modes you can deploy in your topology, and be aware of security requirements for the interior portion of the router network.
+
+. xref:adding-routers-router-network-router[Build the router network by adding routers one at a time].
++
+For each router, you must configure the following:
+
+.. Router properties
+.. Network connections (incoming and outgoing)
+.. Security (authentication and authorization)
+
+// Planning a router network
+include::planning-router-network.adoc[leveloffset=+1]
+
+// Adding routers to the router network
+include::modules/adding-routers-router-network.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/management.adoc b/docs/books/user-guide/assemblies/planning-router-network.adoc
similarity index 54%
copy from docs/books/user-guide/management.adoc
copy to docs/books/user-guide/assemblies/planning-router-network.adoc
index fa933de..36f0268 100644
--- a/docs/books/user-guide/management.adoc
+++ b/docs/books/user-guide/assemblies/planning-router-network.adoc
@@ -17,22 +17,20 @@ specific language governing permissions and limitations
under the License
////
-= Management
+// This assembly is included in the following assemblies:
+//
+// creating-router-networks.adoc
-You can manage {RouterName} using both graphical and command-line tools.
+[id='planning-router-network-{context}']
+= Planning a router network
-{ConsoleName}:: A graphical tool for monitoring and managing {RouterName} routers.
-`qdstat`:: A command-line tool for monitoring the status of {RouterName} routers.
-`qdmanage`:: A command-line tool for viewing and updating the configuration of {RouterName} routers.
+To plan your router network and design the network topology, you must first understand the different router modes and how you can use them to create different types of networks.
-// Using the Console
-include::using-console.adoc[leveloffset=+1]
+// Router operating modes
+include::modules/router-operating-modes.adoc[leveloffset=+1]
-// Monitoring Using qdstat
-include::monitoring-using-qdstat.adoc[leveloffset=+1]
+// Security considerations
+include::modules/router-network-security-considerations.adoc[leveloffset=+1]
-// Managing Using qdmanage
-include::managing-using-qdmanage.adoc[leveloffset=+1]
-
-// Management Entities
-include::management-entities.adoc[leveloffset=+1]
+// Example router network topologies
+// include::modules/example-router-network-topologies.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/assemblies/securing-incoming-client-connections.adoc b/docs/books/user-guide/assemblies/securing-incoming-client-connections.adoc
new file mode 100644
index 0000000..b3d77c1
--- /dev/null
+++ b/docs/books/user-guide/assemblies/securing-incoming-client-connections.adoc
@@ -0,0 +1,44 @@
+////
+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 is included in the following assemblies:
+//
+// securing-network-connections.adoc
+
+[id='securing-incoming-client-connections-{context}']
+= Securing incoming client connections
+
+You can use SSL/TLS and SASL to provide the appropriate level of security for client traffic into the router network. You can use the following methods to secure incoming connections to a router from AMQP clients, external containers, or edge routers:
+
+* xref:enabling-ssl-tls-encryption-router[Enabling SSL/TLS encryption]
+* xref:enabling-ssl-tls-client-authentication-router[Enabling SSL/TLS client authentication]
+* xref:enabling-username-password-authentication-router[Enabling user name and password authentication]
+* xref:integrating-with-kerberos-router[Integrating with Kerberos]
+
+// Enabling SSL/TLS encryption
+include::modules/enabling-ssl-tls-encryption.adoc[leveloffset=+1]
+
+// Enabling SSL/TLS client authentication
+include::modules/enabling-ssl-tls-client-authentication.adoc[leveloffset=+1]
+
+// Enabling username/password authentication
+include::modules/enabling-username-password-authentication.adoc[leveloffset=+1]
+
+// Integrating with Kerberos
+include::modules/integrating-with-kerberos.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/assemblies/securing-network-connections.adoc b/docs/books/user-guide/assemblies/securing-network-connections.adoc
new file mode 100644
index 0000000..846e50a
--- /dev/null
+++ b/docs/books/user-guide/assemblies/securing-network-connections.adoc
@@ -0,0 +1,45 @@
+////
+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:
+//
+// adding-routers-router-network.adoc
+
+[id='securing-network-connections-{context}']
+= Securing network connections
+
+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:
+
+* SSL/TLS for certificate-based encryption and mutual authentication
+* SASL for authentication with mechanisms
+
+To secure the router network, you configure SSL/TLS, SASL (or a combination of both) to secure each of the following types of connections:
+
+* xref:securing-connections-between-routers-router[Connections between routers]
+* xref:securing-incoming-client-connections-router[Incoming client connections]
+* xref:securing-outgoing-connections-router[Outgoing connections]
+
+// Securing connections between routers
+include::modules/securing-connections-between-routers.adoc[leveloffset=+1]
+
+// Securing incoming client connections
+include::securing-incoming-client-connections.adoc[leveloffset=+1]
+
+// Securing outgoing connections
+include::securing-outgoing-connections.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/assemblies/securing-outgoing-connections.adoc b/docs/books/user-guide/assemblies/securing-outgoing-connections.adoc
new file mode 100644
index 0000000..a0c0c7d
--- /dev/null
+++ b/docs/books/user-guide/assemblies/securing-outgoing-connections.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
+////
+
+// Module is included in the following assemblies:
+//
+// securing-network-connections.adoc
+
+[id='securing-outgoing-connections-{context}']
+= Securing outgoing connections
+
+If a router is configured to create connections to external AMQP containers (such as message brokers), you can configure the connections to use the appropriate level of security.
+
+You can configure a router to create outgoing connections using:
+
+* xref:connecting-using-one-way-ssl-tls-authentication-router[SSL/TLS encryption (one-way authentication)]
+* xref:connecting-using-mutual-ssl-tls-authentication-router[SSL/TLS mutual authentication]
+* xref:connecting-using-username-password-authentication-router[User name and password authentication (with or without SSL/TLS encryption)]
+
+// Connecting using SSL/TLS encryption
+include::modules/connecting-using-one-way-ssl-tls-authentication.adoc[leveloffset=+1]
+
+// Connecting using SSL/TLS mutual authentication
+include::modules/connecting-using-mutual-ssl-tls-authentication.adoc[leveloffset=+1]
+
+// Connecting using user name and password authentication
+include::modules/connecting-using-username-password-authentication.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/configuration-security.adoc b/docs/books/user-guide/authorization.adoc
similarity index 57%
copy from docs/books/user-guide/configuration-security.adoc
copy to docs/books/user-guide/authorization.adoc
index a3a936c..6364be3 100644
--- a/docs/books/user-guide/configuration-security.adoc
+++ b/docs/books/user-guide/authorization.adoc
@@ -17,432 +17,8 @@ specific language governing permissions and limitations
under the License
////
-[id='security-config']
-= Security
-
-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:
-
-* _SSL/TLS_ for certificate-based encryption and mutual authentication
-* _SASL_ for authentication and payload encryption
-
-[id='setting-up-ssl-for-encryption-and-authentication']
-=== Setting Up SSL/TLS for Encryption and Authentication
-
-Before you can secure incoming and outgoing connections using SSL/TLS encryption and authentication, you must first set up the SSL/TLS profile in the router's configuration file.
-
-.Prerequisites
-
-You must have the following files in PEM format:
-
-* An X.509 CA certificate (used for signing the router certificate for the SSL/TLS server authentication feature).
-* A private key (with or without password protection) for the router.
-* An X.509 router certificate signed by the X.509 CA certificate.
-
-.Procedure
-
-* In the router's configuration file, add an `sslProfile` section:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-sslProfile {
- name: _NAME_
- ciphers: _CIPHERS_
- protocols: _PROTOCOL_
- caCertFile: _PATH_.pem
- certFile: _PATH_.pem
- privateKeyFile: _PATH_.pem
- password: _PASSWORD/PATH_TO_PASSWORD_FILE_
- ...
-}
-----
-
-`name`:: A name for the SSL/TLS profile. You can use this name to refer to the profile from the incoming and outgoing connections.
-+
-For example:
-+
-[options="nowrap"]
-----
-name: router-ssl-profile
-----
-
-`ciphers`:: The SSL cipher suites that can be used by this SSL/TLS profile. If certain ciphers are unsuitable for your environment, you can use this attribute to restrict them from being used.
-+
-To enable a cipher list, enter one or more cipher strings separated by colons (`:`).
-+
-.Enabling a Cipher List
-====
-[options="nowrap"]
-----
-ciphers: ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
-----
-====
-+
-To see the full list of available ciphers, use the `openssl ciphers` command. For more information about each cipher, see the link:https://www.openssl.org/docs/manmaster/man1/ciphers.html[ciphers man page^].
-
-`protocols`:: The SSL/TLS protocols that this router can use. You can specify a list of one or more of the following values: TLSv1, TLSv1.1, or TLSv1.2.
-+
-To specify multiple protocols, separate the protocols with a space.
-+
-.Specifying Multiple Protocols
-====
-This example permits the SSL/TLS profile to use TLS v1.1 and TLS v1.2 only:
-
-[options="nowrap"]
-----
-protocols: TLSv1.1 TLSv1.2
-----
-====
-+
-If you do not specify a value, the router will use the TLS protocol specified by the system-wide configuration.
-+
-[NOTE]
-====
-When setting the TLS protocol versions for the router, you should also consider the TLS protocol version (or versions) used by your client applications. If a subset of TLS protocol versions does not exist between a client and the router, the client will not be able to connect to the router.
-====
-
-`caCertFile`:: The absolute path to the file that contains the public certificates of trusted certificate authorities (CA).
-+
-For example:
-+
-[options="nowrap"]
-----
-caCertFile: /qdrouterd/ssl_certs/ca-cert.pem
-----
-
-`certFile`:: The absolute path to the file containing the PEM-formatted public certificate to be used on the local end of any connections using this profile.
-+
-For example:
-+
-[options="nowrap"]
-----
-certFile: /qdrouterd/ssl_certs/router-cert-pwd.pem
-----
-
-`privateKeyFile`:: The absolute path to the file containing the PEM-formatted private key for the above certificate.
-+
-For example:
-+
-[options="nowrap"]
-----
-privateKeyFile: /qdrouterd/ssl_certs/router-key-pwd.pem
-----
-
-`passwordFile` or `password`:: If the private key is password-protected, you must provide the password by either specifying the absolute path to a file containing the password that unlocks the certificate key, or entering the password directly in the configuration file.
-+
-For example:
-+
-[options="nowrap"]
-----
-password: routerKeyPassword
-----
-
-For information about additional `sslProfile` attributes, see link:{qdrouterdConfManPageUrl}#_sslprofile[sslProfile] in the `qdrouterd.conf` man page.
---
-
-[id='setting-up-sasl-for-authentication-and-payload-encryption']
-=== Setting Up SASL for Authentication and Payload Encryption
-
-If you plan to use SASL to authenticate connections, you must first add the SASL attributes to the `router` entity in the router's configuration file. These attributes define a set of SASL parameters that can be used by the router's incoming and outgoing connections.
-
-.Prerequisites
-
-Before you can set up SASL, you must have the following:
-
-* xref:generating-sasl-database[The SASL database is generated.]
-* xref:configuring-sasl-database[The SASL configuration file is configured.]
-* The Cyrus SASL plugin is installed for each SASL mechanism you plan to use.
-+
-Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed. For example, you need the `cyrus-sasl-plain` plugin to use SASL PLAIN authentication.
-+
---
-// Note about searching for an installing SASL plugins.
-include::{FragmentDir}/fragment-router-sasl-para.adoc[]
---
-
-.Procedure
-
-* In the router's configuration file, add the following attributes to the `router` section:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-router {
- ...
- saslConfigDir: _PATH_
- saslConfigName: _FILE_NAME_
-}
-----
-
-`saslConfigDir`:: The absolute path to the SASL configuration file.
-+
-For example:
-+
-[options="nowrap"]
-----
-saslConfigDir: /qdrouterd/security
-----
-
-`saslConfigName`:: The name of the SASL configuration file. This name should _not_ include the `.conf` file extension.
-+
-For example:
-+
-[options="nowrap"]
-----
-saslConfigName: qdrouterd_sasl
-----
---
-
-[id='securing-incoming-connections']
-=== Securing Incoming Connections
-
-You can secure incoming connections by configuring each connection's `listener` entity for encryption, authentication, or both.
-
-.Prerequisites
-
-Before securing incoming connections, the security protocols you plan to use should be set up.
-
-.Choices
-
-* xref:adding-ssl-encryption-to-incoming-connection[Add SSL/TLS encryption]
-* xref:adding-sasl-authentication-to-incoming-connection[Add SASL authentication]
-* xref:adding-ssl-client-authentication-to-incoming-connection[Add SSL/TLS client authentication]
-* xref:adding-sasl-payload-encryption-to-incoming-connection[Add SASL payload encryption]
-
-[id='adding-ssl-encryption-to-incoming-connection']
-==== Adding SSL/TLS Encryption to an Incoming Connection
-
-You can configure an incoming connection to accept encrypted connections only. By adding SSL/TLS encryption, to connect to this router, a remote peer must first start an SSL/TLS handshake with the router and be able to validate the server certificate received by the router during the handshake.
-
-.Procedure
-
-* In the router's configuration file, add the following attributes to the connection's `listener` entity:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-listener {
- ...
- sslProfile: _SSL_PROFILE_NAME_
- requireSsl: yes
-}
-----
-
-`sslProfile`:: The name of the SSL/TLS profile you set up.
-
-`requireSsl`:: Enter `yes` to require all clients connecting to the router on this connection to use encryption.
---
-
-[id='adding-sasl-authentication-to-incoming-connection']
-==== Adding SASL Authentication to an Incoming Connection
-
-You can configure an incoming connection to authenticate the client using SASL. You can use SASL authentication with or without SSL/TLS encryption.
-
-.Procedure
-
-* In the router's configuration file, add the following attributes to the connection's `listener` section:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-listener {
- ...
- authenticatePeer: yes
- saslMechanisms: _MECHANISMS_
-}
-----
-
-`authenticatePeer`:: Set this attribute to `yes` to require the router to authenticate the identity of a remote peer before it can use this incoming connection.
-
-`saslMechanisms`:: The SASL authentication mechanism (or mechanisms) to use for peer authentication. You can choose any of the Cyrus SASL authentication mechanisms _except_ for `ANONYMOUS`. To specify multiple authentication mechanisms, separate each mechanism with a space.
-+
-For a full list of supported Cyrus SASL authentication mechanisms, see link:https://www.cyrusimap.org/sasl/sasl/authentication_mechanisms.html[Authentication Mechanisms^].
---
-
-[id='adding-ssl-client-authentication-to-incoming-connection']
-==== Adding SSL/TLS Client Authentication to an Incoming Connection
-
-You can configure an incoming connection to authenticate the client using SSL/TLS.
-
-The base SSL/TLS configuration provides content encryption and server authentication, which means that remote peers can verify the router's identity, but the router cannot verify a peer's identity.
-
-However, you can require an incoming connection to use SSL/TLS client authentication, which means that remote peers must provide an additional certificate to the router during the SSL/TLS handshake. By using this certificate, the router can verify the client's identity without using a username and password.
-
-You can use SSL/TLS client authentication with or without SASL authentication.
-
-.Procedure
-
-* In the router's configuration, file, add the following attribute to the connection's `listener` entity:
-+
---
-[options="nowrap"]
-----
-listener {
- ...
- authenticatePeer: yes
-}
-----
-
-`authenticatePeer`:: Set this attribute to `yes` to require the router to authenticate the identity of a remote peer before it can use this incoming connection.
---
-
-[id='adding-sasl-payload-encryption-to-incoming-connection']
-==== Adding SASL Payload Encryption to an Incoming Connection
-
-If you do not use SSL/TLS, you can still encrypt the incoming connection by using SASL payload encryption.
-
-.Procedure
-
-* In the router's configuration file, add the following attributes to the connection's `listener` section:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-listener {
- ...
- requireEncryption: yes
- saslMechanisms: _MECHANISMS_
-}
-----
-
-`requireEncryption`:: Set this attribute to `yes` to require the router to use SASL payload encryption for the connection.
-
-`saslMechanisms`:: The SASL mechanism to use. You can choose any of the Cyrus SASL authentication mechanisms. To specify multiple authentication mechanisms, separate each mechanism with a space.
-+
-For a full list of supported Cyrus SASL authentication mechanisms, see link:https://www.cyrusimap.org/sasl/sasl/authentication_mechanisms.html[Authentication Mechanisms^].
---
-
-[id='securing-outgoing-connections']
-=== Securing Outgoing Connections
-
-You can secure outgoing connections by configuring each connection's `connector` entity for encryption, authentication, or both.
-
-.Prerequisites
-
-Before securing outgoing connections, the security protocols you plan to use should be set up.
-
-.Choices
-
-* xref:adding-ssl-authentication-to-outgoing-connection[Add SSL/TLS authentication]
-* xref:adding-sasl-authentication-to-outgoing-connection[Add SASL authentication]
-
-[id='adding-ssl-authentication-to-outgoing-connection']
-==== Adding SSL/TLS Client Authentication to an Outgoing Connection
-
-If an outgoing connection connects to an external client configured with mutual authentication, you should ensure that the outgoing connection is configured to provide the external client with a valid security certificate during the SSL/TLS handshake.
-
-You can use SSL/TLS client authentication with or without SASL authentication.
-
-.Procedure
-
-* In the router's configuration file, add the `sslProfile` attribute to the connection's `connector` entity:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-connector {
- ...
- sslProfile: _SSL_PROFILE_NAME_
-}
-----
-
-`sslProfile`:: The name of the SSL/TLS profile you set up.
---
-
-[id='adding-sasl-authentication-to-outgoing-connection']
-==== Adding SASL Authentication to an Outgoing Connection
-
-You can configure an outgoing connection to provide authentication credentials to the external container. You can use SASL authentication with or without SSL/TLS encryption.
-
-.Procedure
-
-* In the router's configuration file, add the `saslMechanisms` attribute to the connection's `connector` entity:
-+
---
-[options="nowrap",subs="+quotes"]
-----
-connector {
- ...
- saslMechanisms: _MECHANISMS_
- saslUsername: _USERNAME_
- saslPassword: _PASSWORD_
-}
-----
-
-`saslMechanisms`:: One or more SASL mechanisms to use to authenticate the router to the external container. You can choose any of the Cyrus SASL authentication mechanisms. To specify multiple authentication mechanisms, separate each mechanism with a space.
-+
-For a full list of supported Cyrus SASL authentication mechanisms, see link:https://www.cyrusimap.org/sasl/sasl/authentication_mechanisms.html[Authentication Mechanisms^].
-`saslUsername`:: If any of the SASL mechanisms uses username/password authentication, then provide the username to connect to the external container.
-`saslPassword`:: If any of the SASL mechanisms uses username/password authentication, then provide the password to connect to the external container.
---
-
-[id='integrating-with-kerberos']
-=== Integrating with Kerberos
-
-By using the `GSSAPI` SASL mechanism, you can configure {RouterName} to authenticate incoming connections using Kerberos.
-
-.Prerequisites
-
-* A Kerberos infrastructure must be deployed in your environment.
-
-* In the Kerberos environment, a service principal of `amqp/_HOSTNAME_@_REALM_` must be configured.
-+
-This is the service principal that {RouterName} uses.
-
-* The `cyrus-sasl-gssapi` package must be installed on each client and router host machine.
-
-* xref:setting-up-sasl-for-authentication-and-payload-encryption[SASL must be set up for {RouterName}].
-
-.Procedure
-
-. On the router's host machine, open the `/etc/sasl2/qdrouterd.conf` configuration file.
-+
---
-.An `/etc/sasl2/qdrouterd.conf` Configuration File
-====
-[options="nowrap"]
-----
-pwcheck_method: auxprop
-auxprop_plugin: sasldb
-sasldb_path: qdrouterd.sasldb
-keytab: /etc/krb5.keytab
-mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
-----
-====
---
-
-. Verify the following:
-** The `mech_list` attribute contains the `GSSAPI` mechanism.
-** The `keytab` attribute points to the location of the keytab file.
-
-
-. Open the router's configuration file.
-
-. For each incoming connection that should use Kerberos for authentication, set the router's `listener` to use the `GSSAPI` mechanism.
-+
---
-.A `listener` in the Router Configuration File
-====
-[options="nowrap"]
-----
-listener {
- ...
- authenticatePeer: yes
- saslMechanisms: GSSAPI
-}
-----
-====
-
-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
+= 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.
@@ -456,7 +32,7 @@ Connection and AMQP resource limits for a messaging endpoint (called an AMQP vir
The resource limits defined in global and vhost policies are applied to user connections only. The limits do not affect inter-router connections or router connections that are outbound to waypoints.
-=== How {RouterName} Enforces Connection and Resource Limits
+== How {RouterName} Enforces Connection and Resource Limits
{RouterName} uses policies to determine whether to permit a connection, and if it is permitted, to apply the appropriate resource limits.
@@ -468,7 +44,7 @@ When a client creates a connection to the router, the router first determines wh
If the connection is allowed, the router assigns the user (the authenticated user name from the connection) to a user group, and enforces the user group’s resource limits for the lifetime of the connection.
-=== Setting Global Connection Limits
+== Setting Global Connection Limits
You can set the incoming connection limit for the router. This limit defines the total number of concurrent client connections that can be open for this router.
@@ -487,9 +63,9 @@ policy {
This limit is always enforced, even if no other policy settings have been defined. The limit is applied to all incoming connections regardless of remote host, authenticated user, or targeted vhost. The default (and the maximum) value is `65535`.
--
-=== Setting Connection and Resource Limits for Messaging Endpoints
+== Setting Connection and Resource Limits for Messaging Endpoints
-You can define the connection limit and AMQP resource limits for a messaging endpoint by configuring a _vhost policy_. Vhost policies define what resources clients are permitted to access on a messaging endpoint over a particular connection.
+You can define the connection limit and AMQP resource limits for a messaging endpoint by configuring a _vhost policy_. Vhost policies define what resources clients are permitted to access on a messaging endpoint over a particular connection.
[NOTE]
====
@@ -502,7 +78,7 @@ You can create vhost policies using either of the following methods:
* xref:configuring-vhost-policies-json[Configure vhost policies as JSON files]
[id='enabling-vhost-policies']
-==== Enabling Vhost Policies
+=== Enabling Vhost Policies
You must enable the router to use vhost policies before you can create the policies.
@@ -531,7 +107,7 @@ The name of the default vhost policy, which is applied to any connection for whi
--
[id='configuring-vhost-policies-router']
-==== Configuring Vhost Policies in the Router Configuration File
+=== Configuring Vhost Policies in the Router Configuration File
You can configure vhost policies in the router configuration file by configuring `vhost` entities. However, if multiple routers in your router network should be configured with the same vhost configuration, you will need to add the vhost configuration to each router’s configuration file.
@@ -600,7 +176,7 @@ vhost {
remoteHosts: *
sources: myqueue1, myqueue2
targets: myqueue1, myqueue2
- }
+ }
$default: {
remoteHosts: *
allowDynamicSource: true,
@@ -652,7 +228,7 @@ A list of AMQP target addresses from which users in this group may send messages
The advanced user group settings enable you to define resource limits based on the AMQP connection open, session begin, and link attach phases of the connection. For more information, see link:{qdrouterdConfManPageUrl}#_vhost[vhost^] in the `qdrouterd.conf` man page.
[id='configuring-vhost-policies-json']
-==== Configuring Vhost Policies as JSON Files
+=== Configuring Vhost Policies as JSON Files
As an alternative to using the router configuration file, you can configure vhost policies in JSON files. If you have multiple routers that need to share the same vhost configuration, you can put the vhost configuration JSON files in a location accessible to each router, and then configure the routers to apply the vhost policies defined in these JSON files.
@@ -718,8 +294,62 @@ For more information about these attributes, see xref:configuring-vhost-policies
====
--
+[id='pattern-matching-vhost-policy-hostnames']
+=== Pattern Matching for Vhost Policy Hostnames
+
+In a vhost policy, vhost hostnames can be either literal hostnames or patterns that cover a range of hostnames.
+
+A hostname pattern is a sequence of words with one or more of the following wildcard characters:
+
+* `*` represents exactly one word
+* `#` represents zero or more words
+
+The following table shows some examples of hostname patterns:
+
+[options="header"]
+|===
+| This pattern... | Matches... | But not...
+
+a| `*.example.com`
+a| `www.example.com`
+a| `example.com`
+`srv2.www.example.com`
+
+a| `#.example.com`
+a| `example.com`
+`www.example.com`
+`a.b.c.d.example.com`
+a| `myhost.com`
+
+a| `www.*.test.example.com`
+a| `www.a.test.example.com`
+a| `www.test.example.com`
+`www.a.b.c.test.example.com`
+
+a| `www.#.test.example.com`
+a| `www.test.example.com`
+`www.a.test.example.com`
+`www.a.b.c.test.example.com`
+a| `test.example.com`
+|===
+
+Vhost hostname pattern matching applies the following precedence rules:
+
+[options="header"]
+|===
+| Policy pattern | Precedence
+| Exact match | High
+| * | Medium
+| # | Low
+|===
+
+[NOTE]
+====
+{RouterName} does not permit you to create vhost hostname patterns that conflict with existing patterns. This includes patterns that can be reduced to be the same as an existing pattern. For example, you would not be able to create the `\#.#.\#.#.com` pattern if `#.com` already exists.
+====
+
[id='methods-for-specifying-vhost-policy-source-target-addresses']
-==== Methods for Specifying Vhost Policy Source and Target Addresses
+=== Methods for Specifying Vhost Policy Source and Target Addresses
If you want to allow or deny access to multiple addresses on a vhost, there are several methods you can use to match multiple addresses without having to specify each address individually.
@@ -758,7 +388,7 @@ a| Use the `${user}` username substitution token. You can use this token with `s
====
You can only specify the `${user}` token once in an AMQP address name or pattern. If there are multiple tokens in an address, only the leftmost token will be substituted.
====
-
+
.Receive from a User-Specific Address
====
This definition allows the users in the user group to receive messages from any address that meets any of the following rules:
@@ -792,7 +422,7 @@ In an address pattern (`sourcePattern` or `targetPattern`), the username substit
|===
-==== Vhost Policy Examples
+=== Vhost Policy Examples
These examples demonstrate how to use vhost policies to authorize access to messaging resources.
@@ -849,7 +479,7 @@ In this example, a vhost policy defines resource limits for clients connecting t
====
By using the advanced vhost policy attributes, you can control how much system buffer memory a user connection can potentially consume.
-In this example, a stock trading site provides services for stock traders. However, the site must also accept high-capacity, automated data feeds from stock exchanges. To prevent trading activity from consuming memory needed for the feeds, a larger amount of system buffer memory is allotted to the feeds than to the traders.
+In this example, a stock trading site provides services for stock traders. However, the site must also accept high-capacity, automated data feeds from stock exchanges. To prevent trading activity from consuming memory needed for the feeds, a larger amount of system buffer memory is allotted to the feeds than to the traders.
This example uses the `maxSessions` and `maxSessionWindow` attributes to set the buffer memory consumption limits for each AMQP session. These settings are passed directly to the AMQP connection and session negotiations, and do not require any processing cycles on the router.
diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc
index e3a2c0e..bb22571 100644
--- a/docs/books/user-guide/book.adoc
+++ b/docs/books/user-guide/book.adoc
@@ -26,44 +26,27 @@ include::_common/attributes.adoc[]
// Overview
include::assemblies/overview.adoc[leveloffset=+1]
-// Introduction
-// include::introduction.adoc[leveloffset=+1]
-
-// Theory of Operation
-// include::theory_of_operation.adoc[leveloffset=+1]
-
// Getting started
include::assemblies/getting-started.adoc[leveloffset=+1]
-// Configuration
-include::understand-router-configuration.adoc[leveloffset=+1]
+// Configuring a router network topology
+include::assemblies/creating-router-network-topology.adoc[leveloffset=+1]
-// Network Connections
-include::configuration-connections.adoc[leveloffset=+1]
+// Configuring a router
+include::assemblies/configuring-router.adoc[leveloffset=+1]
-// Security
-include::configuration-security.adoc[leveloffset=+1]
-
-// Routing
+// Routing messages through the router network
include::routing.adoc[leveloffset=+1]
-// Network Topologies
-include::modules/network-topologies.adoc[leveloffset=+1]
-
-// Logging
-include::logging.adoc[leveloffset=+1]
-
-// Management
-include::management.adoc[leveloffset=+1]
-
-// Reliability
-include::reliability.adoc[leveloffset=+1]
+[id="monitoring-managing-router-network"]
+== Monitoring and managing the router network
+include::logging.adoc[leveloffset=+2]
+include::using-console.adoc[leveloffset=+2]
+include::monitoring-using-qdstat.adoc[leveloffset=+2]
+include::managing-using-qdmanage.adoc[leveloffset=+2]
// Technical Details and Specifications
include::technical-details-specifications.adoc[leveloffset=+1]
-[appendix]
-include::cyrus-sasl.adoc[leveloffset=+1]
-
// Revision information
include::revision-info.adoc[]
diff --git a/docs/books/user-guide/configuration-security.adoc b/docs/books/user-guide/configuration-security.adoc
index a3a936c..d0e4018 100644
--- a/docs/books/user-guide/configuration-security.adoc
+++ b/docs/books/user-guide/configuration-security.adoc
@@ -73,7 +73,7 @@ name: router-ssl-profile
`ciphers`:: The SSL cipher suites that can be used by this SSL/TLS profile. If certain ciphers are unsuitable for your environment, you can use this attribute to restrict them from being used.
+
-To enable a cipher list, enter one or more cipher strings separated by colons (`:`).
+To enable a cipher list, enter one or more cipher strings separated by colons (`:`).
+
.Enabling a Cipher List
====
@@ -440,455 +440,3 @@ 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.
-
-{RouterName} provides the following types of policies:
-
-Global policies::
-Settings for the router. A global policy defines the maximum number of incoming user connections for the router (across all messaging endpoints), and defines how the router should use vhost policies.
-
-Vhost policies::
-Connection and AMQP resource limits for a messaging endpoint (called an AMQP virtual host, or vhost). A vhost policy defines what a client can access on a messaging endpoint over a particular connection.
-
-The resource limits defined in global and vhost policies are applied to user connections only. The limits do not affect inter-router connections or router connections that are outbound to waypoints.
-
-=== How {RouterName} Enforces Connection and Resource Limits
-
-{RouterName} uses policies to determine whether to permit a connection, and if it is permitted, to apply the appropriate resource limits.
-
-When a client creates a connection to the router, the router first determines whether to allow or deny the connection. This decision is based on the following criteria:
-
-* Whether the connection will exceed the router’s global connection limit (defined in the global policy)
-
-* Whether the connection will exceed the vhost’s connection limits (defined in the vhost policy that matches the host to which the connection is directed)
-
-If the connection is allowed, the router assigns the user (the authenticated user name from the connection) to a user group, and enforces the user group’s resource limits for the lifetime of the connection.
-
-=== Setting Global Connection Limits
-
-You can set the incoming connection limit for the router. This limit defines the total number of concurrent client connections that can be open for this router.
-
-.Procedure
-
-* In the router configuration file, add a `policy` section and set the `maxConnections`.
-+
---
-[options="nowrap",subs="+quotes"]
-----
-policy {
- maxConnections: 10000
-}
-----
-`maxConnections`::
-This limit is always enforced, even if no other policy settings have been defined. The limit is applied to all incoming connections regardless of remote host, authenticated user, or targeted vhost. The default (and the maximum) value is `65535`.
---
-
-=== Setting Connection and Resource Limits for Messaging Endpoints
-
-You can define the connection limit and AMQP resource limits for a messaging endpoint by configuring a _vhost policy_. Vhost policies define what resources clients are permitted to access on a messaging endpoint over a particular connection.
-
-[NOTE]
-====
-A vhost is typically the name of the host to which the client connection is directed. For example, if a client application opens a connection to the `amqp://mybroker.example.com:5672/queue01` URL, the vhost would be `mybroker.example.com`.
-====
-
-You can create vhost policies using either of the following methods:
-
-* xref:configuring-vhost-policies-router[Configure vhost policies directly in the router configuration file]
-* xref:configuring-vhost-policies-json[Configure vhost policies as JSON files]
-
-[id='enabling-vhost-policies']
-==== Enabling Vhost Policies
-
-You must enable the router to use vhost policies before you can create the policies.
-
-.Procedure
-
-* In the router configuration file, add a `policy` section if one does not exist, and enable vhost policies for the router.
-+
---
-[options="nowrap",subs="+quotes"]
-----
-policy {
- ...
- enableVhostPolicy: true
- enableVhostNamePatterns: true | false
- defaultVhost: $default
-}
-----
-`enableVhostPolicy`::
-Enables the router to enforce the connection denials and resource limits defined in the configured vhost policies. The default is `false`, which means that the router will not enforce any vhost policies.
-
-`enableVhostNamePatterns`::
-Enables pattern matching for vhost hostnames. If set to `true`, you can use wildcards to specify a range of hostnames for a vhost. If set to `false`, vhost hostnames are treated as literal strings. This means that you must specify the exact hostname for each vhost. The default is `false`.
-
-`defaultVhost`::
-The name of the default vhost policy, which is applied to any connection for which a vhost policy has not been configured. The default is `$default`. If `defaultVhost` is not defined, then default vhost processing is disabled.
---
-
-[id='configuring-vhost-policies-router']
-==== Configuring Vhost Policies in the Router Configuration File
-
-You can configure vhost policies in the router configuration file by configuring `vhost` entities. However, if multiple routers in your router network should be configured with the same vhost configuration, you will need to add the vhost configuration to each router’s configuration file.
-
-.Prerequisites
-
-Vhost policies must be enabled for the router. For more information, see xref:enabling-vhost-policies[].
-
-.Procedure
-
-. Add a `vhost` section and define the connection limits for the messaging endpoint.
-+
---
-The connection limits apply to all users that are connected to the vhost. These limits control the number of users that can be connected simultaneously to the vhost.
-
-[options="nowrap",subs="+quotes"]
-----
-vhost {
- hostname: example.com
- maxConnections: 10000
- maxConnectionsPerUser: 100
- maxConnectionsPerHost: 100
- allowUnknownUser: true
- ...
-}
-----
-`hostname`::
-The literal hostname of the vhost (the messaging endpoint) or a pattern that matches the vhost hostname. This vhost policy will be applied to any client connection that is directed to the hostname that you specify. This name must be unique; you can only have one vhost policy per hostname.
-+
-If `enableVhostNamePatterns` is set to `true`, you can use wildcards to specify a pattern that matches a range of hostnames. For more information, see xref:pattern-matching-vhost-policy-hostnames[].
-
-`maxConnections`::
-The global maximum number of concurrent client connections allowed for this vhost. The default is 65535.
-
-`maxConnectionsPerUser`::
-The maximum number of concurrent client connections allowed for any user. The default is 65535.
-
-`maxConnectionsPerHost`::
-The maximum number of concurrent client connections allowed for any remote host (the host from which the client is connecting). The default is 65535.
-
-`allowUnknownUser`::
-Whether unknown users (users who are not members of a defined user group) are allowed to connect to the vhost. Unknown users are assigned to the $default user group and receive $default settings. The default is false, which means that unknown users are not allowed.
---
-
-. In the `vhost` section, beneath the connection settings that you added, add a `groups` entity to define the resource limits.
-+
---
-You define resource limits by user group. A user group specifies the messaging resources the members of the group are allowed to access.
-
-.User Groups in a Vhost Policy
-====
-This example shows three user groups: admin, developers, and $default:
-
-[options="nowrap",subs="+quotes"]
-----
-vhost {
- ...
- groups: {
- admin: {
- users: admin1, admin2
- remoteHosts: 127.0.0.1, ::1
- sources: *
- targets: *
- }
- developers: {
- users: dev1, dev2, dev3
- remoteHosts: *
- sources: myqueue1, myqueue2
- targets: myqueue1, myqueue2
- }
- $default: {
- remoteHosts: *
- allowDynamicSource: true,
- allowAdminStatusUpdate: true,
- sources: myqueue1, myqueue2
- targets: myqueue1, myqueue2
- }
- }
-}
-----
-`users`::
-A list of authenticated users for this user group. Use commas to separate multiple users. A user may belong to only one vhost user group.
-
-`remoteHosts`::
-A list of remote hosts from which the users may connect. A host can be a hostname, IP address, or IP address range. Use commas to separate multiple hosts. To allow access from all remote hosts, specify a wildcard `*`. To deny access from all remote hosts, leave this attribute blank.
-
-`allowDynamicSource`::
-If true, connections from users in this group are permitted to attach receivers to dynamic sources. This permits creation of listners to temporary addresses or termporary queues. If false, use of dynamic sources is forbidden.
-
-`allowAdminStatusUpdate`::
-If true, connections from users in this group are permitted to modify the adminStatus of connections. This permits termination of sender or receiver connections. If false, the users of this group are prohibited from terminating any connections. Inter-router connections can never be terminated by any user under any circumstance. Defaults to true, no policy required.
-
-
-`allowWaypointLinks`::
-If true, connections from users in this group are permitted to attach links using waypoint capabilities. This allows endpoints to act as waypoints (i.e. brokers) without the need for configuring auto-links. If false, use of waypoint capabilities is forbidden.
-
-`allowDynamicLinkRoutes`::
-If true, connections from users in this group may dynamically create connection-scoped link route destinations. This allows endpoints to act as link route destinations (i.e. brokers) without the need for configuring link-routes. If false, creation of dynamic link route destintations is forbidden.
-
-`allowFallbackLinks`::
-If true, connections from users in this group are permitted to attach links using fallback-link capabilities. This allows endpoints to act as fallback destinations (and sources) for addresses that have fallback enabled. If false, use of fallback-link capabilities is forbidden.
-
-`sources` | `sourcePattern`::
-A list of AMQP source addresses from which users in this group may receive messages.
-+
-Use `sources` to specify one or more literal addresses. To specify multiple addresses, use a comma-separated list. To prevent users in this group from receiving messages from any addresses, leave this attribute blank. To allow access to an address specific to a particular user, specify the `${user}` token. For more information, see xref:methods-for-specifying-vhost-policy-source-target-addresses[].
-+
-Alternatively, you can use `sourcePattern` to match one or more addresses that correspond to a pattern. A pattern is a sequence of words delimited by either a `.` or `/` character. You can use wildcard characters to represent a word. The `*` character matches exactly one word, and the `#` character matches any sequence of zero or more words.
-+
-To specify multiple address ranges, use a comma-separated list of address patterns. For more information, see xref:router-address-pattern-matching[Router Address Pattern Matching]. To allow access to address ranges that are specific to a particular user, specify the `${user}` token. For more information, see xref:methods-for-specifying-vhost-policy-source-target-addresses[].
-
-`targets` | `targetPattern`::
-A list of AMQP target addresses from which users in this group may send messages. You can specify multiple AMQP addresses and use user name substitution and address patterns the same way as with source addresses.
-====
---
-
-. If necessary, add any advanced user group settings to the vhost user groups.
-+
-The advanced user group settings enable you to define resource limits based on the AMQP connection open, session begin, and link attach phases of the connection. For more information, see link:{qdrouterdConfManPageUrl}#_vhost[vhost^] in the `qdrouterd.conf` man page.
-
-[id='configuring-vhost-policies-json']
-==== Configuring Vhost Policies as JSON Files
-
-As an alternative to using the router configuration file, you can configure vhost policies in JSON files. If you have multiple routers that need to share the same vhost configuration, you can put the vhost configuration JSON files in a location accessible to each router, and then configure the routers to apply the vhost policies defined in these JSON files.
-
-.Prerequisites
-
-* Vhost policies must be enabled for the router. For more information, see xref:enabling-vhost-policies[].
-
-.Procedure
-
-. In the router configuration file, specify the directory where you want to store the vhost policy definition JSON files.
-+
---
-[options="nowrap",subs="+quotes"]
-----
-policy {
- ...
- policyDir: __DIRECTORY_PATH__
-}
-----
-`policyDir`::
-The absolute path to the directory that holds vhost policy definition files in JSON format. The router processes all of the vhost policies in each JSON file that is in this directory.
---
-
-. In the vhost policy definition directory, create a JSON file for each vhost policy.
-+
---
-.Vhost Policy Definition JSON File
-====
-[source,json,options="nowrap"]
-----
-[
- ["vhost", {
- "hostname": "example.com",
- "maxConnections": 10000,
- "maxConnectionsPerUser": 100,
- "maxConnectionsPerHost": 100,
- "allowUnknownUser": true,
- "groups": {
- "admin": {
- "users": ["admin1", "admin2"],
- "remoteHosts": ["127.0.0.1", "::1"],
- "sources": "*",
- "targets": "*"
- },
- "developers": {
- "users": ["dev1", "dev2", "dev3"],
- "remoteHosts": "*",
- "sources": ["myqueue1", "myqueue2"],
- "targets": ["myqueue1", "myqueue2"]
- },
- "$default": {
- "remoteHosts": "*",
- "allowDynamicSource": true,
- "sources": ["myqueue1", "myqueue2"],
- "targets": ["myqueue1", "myqueue2"]
- }
- }
- }]
-]
-----
-
-For more information about these attributes, see xref:configuring-vhost-policies-router[].
-====
---
-
-[id='methods-for-specifying-vhost-policy-source-target-addresses']
-==== Methods for Specifying Vhost Policy Source and Target Addresses
-
-If you want to allow or deny access to multiple addresses on a vhost, there are several methods you can use to match multiple addresses without having to specify each address individually.
-
-The following table describes the methods you can use to specify multiple source and target addresses for a vhost:
-
-[cols="33,67",options="header"]
-|===
-| To... | Do this...
-
-| Allow all users in the user group to access all source or target addresses on the vhost
-a| Use a `*` wildcard character.
-
-.Receive from Any Address
-====
-[source,options="nowrap"]
-----
-sources: *
-----
-====
-
-| Prevent all users in the user group from accessing all source or target addresses on the vhost
-a| Do not specify a value.
-
-.Prohibit Message Transfers to All Addresses
-====
-[source,options="nowrap"]
-----
-targets:
-----
-====
-
-| Allow access to some resources specific to each user
-a| Use the `${user}` username substitution token. You can use this token with `source`, `target`, `sourcePattern`, and `targetPattern`.
-
-[NOTE]
-====
-You can only specify the `${user}` token once in an AMQP address name or pattern. If there are multiple tokens in an address, only the leftmost token will be substituted.
-====
-
-.Receive from a User-Specific Address
-====
-This definition allows the users in the user group to receive messages from any address that meets any of the following rules:
-
-* Starts with the prefix `tmp_` and ends with the user name
-* Starts with the prefix `temp` followed by any additional characters
-* Starts with the user name, is followed by `-home-`, and ends with any additional characters
-[source,options="nowrap"]
-----
-sources: tmp_${user}, temp*, ${user}-home-*
-----
-====
-
-.User-Specific Address Patterns
-====
-This definition allows the users in the user group to receive messages from any address that meets any of the following rules:
-
-* Starts with the prefix `tmp` and ends with the user name
-* Starts with the prefix `temp` followed by zero or more additional characters
-* Starts with the user name, is followed by `home`, and ends with one or more additional characters
-[source,options="nowrap"]
-----
-sourcePattern: tmp.${user}, temp/#, ${user}.home/*
-----
-====
-
-[NOTE]
-====
-In an address pattern (`sourcePattern` or `targetPattern`), the username substitution token must be either the first or last token in the pattern. The token must also be alone within its delimited field, which means that it cannot be concatenated with literal text prefixes or suffixes.
-====
-
-|===
-
-==== Vhost Policy Examples
-
-These examples demonstrate how to use vhost policies to authorize access to messaging resources.
-
-.Defining Basic Resource Limits for a Messaging Endpoint
-====
-In this example, a vhost policy defines resource limits for clients connecting to the `example.com` host.
-
-[source,json,options="nowrap"]
-----
-[
- ["vhost", {
- "hostname": "example.com", // <1>
- "maxConnectionsPerUser": 10, // <2>
- "allowUnknownUser": true, // <3>
- "groups": {
- "admin": {
- "users": ["admin1", "admin2"], // <4>
- "remoteHosts": ["127.0.0.1", "::1"], // <5>
- "sources": "*", // <6>
- "targets": "*" // <7>
- },
- "$default": {
- "remoteHosts": "*", // <8>
- "sources": ["news*", "sports*" "chat*"], // <9>
- "targets": "chat*" // <10>
- }
- }
- }]
-]
-----
-
-<1> The rules defined in this vhost policy will be applied to any user connecting to `example.com`.
-
-<2> Each user can open up to 10 connections to the vhost.
-
-<3> Any user can connect to this vhost. Users that are not part of the `admin` group are assigned to the `$default` group.
-
-<4> If the `admin1` or `admin2` user connects to the vhost, they are assigned to the `admin` user group.
-
-<5> Users in the `admin` user group must connect from localhost. If the admin user attempts to connect from any other host, the connection will be denied.
-
-<6> Users in the admin user group can receive from any address offered by the vhost.
-
-<7> Users in the admin user group can send to any address offered by the vhost.
-
-<8> Any non-admin user is permitted to connect from any host.
-
-<9> Non-admin users are permitted to receive messages from any addresses that start with the `news`, `sports`, or `chat` prefixes.
-
-<10> Non-admin users are permitted to send messages to any addresses that start with the `chat` prefix.
-====
-
-.Limiting Memory Consumption
-====
-By using the advanced vhost policy attributes, you can control how much system buffer memory a user connection can potentially consume.
-
-In this example, a stock trading site provides services for stock traders. However, the site must also accept high-capacity, automated data feeds from stock exchanges. To prevent trading activity from consuming memory needed for the feeds, a larger amount of system buffer memory is allotted to the feeds than to the traders.
-
-This example uses the `maxSessions` and `maxSessionWindow` attributes to set the buffer memory consumption limits for each AMQP session. These settings are passed directly to the AMQP connection and session negotiations, and do not require any processing cycles on the router.
-
-This example does not show the vhost policy settings that are unrelated to buffer allocation.
-
-[source,json,options="nowrap"]
-----
-[
- ["vhost", {
- "hostname": "traders.com", // <1>
- "groups": {
- "traders": {
- "users": ["trader1", "trader2"], // <2>
- "maxFrameSize": 10000,
- "maxSessionWindow": 5000000, // <3>
- "maxSessions": 1 // <4>
- },
- "feeds": {
- "users": ["nyse-feed", "nasdaq-feed"], // <5>
- "maxFrameSize": 60000,
- "maxSessionWindow": 1200000000, // <6>
- "maxSessions": 3 // <7>
- }
- }
- }]
-]
-----
-
-<1> The rules defined in this vhost policy will be applied to any user connecting to `traders.com`.
-
-<2> The `traders` group includes `trader1`, `trader2`, and any other user defined in the list.
-
-<3> At most, 5,000,000 bytes of data can be in flight on each session.
-
-<4> Only one session per connection is allowed.
-
-<5> The `feeds` group includes two users.
-
-<6> At most, 1,200,000,000 bytes of data can be in flight on each session.
-
-<7> Up to three sessions per connection are allowed.
-====
diff --git a/docs/books/user-guide/management.adoc b/docs/books/user-guide/management.adoc
index fa933de..b5e1f2a 100644
--- a/docs/books/user-guide/management.adoc
+++ b/docs/books/user-guide/management.adoc
@@ -17,19 +17,7 @@ specific language governing permissions and limitations
under the License
////
-= Management
-
-You can manage {RouterName} using both graphical and command-line tools.
-
-{ConsoleName}:: A graphical tool for monitoring and managing {RouterName} routers.
-`qdstat`:: A command-line tool for monitoring the status of {RouterName} routers.
-`qdmanage`:: A command-line tool for viewing and updating the configuration of {RouterName} routers.
-
-// Using the Console
-include::using-console.adoc[leveloffset=+1]
-
-// Monitoring Using qdstat
-include::monitoring-using-qdstat.adoc[leveloffset=+1]
+= Managing the router network
// Managing Using qdmanage
include::managing-using-qdmanage.adoc[leveloffset=+1]
diff --git a/docs/books/user-guide/modules/adding-routers-router-network.adoc b/docs/books/user-guide/modules/adding-routers-router-network.adoc
new file mode 100644
index 0000000..06df572
--- /dev/null
+++ b/docs/books/user-guide/modules/adding-routers-router-network.adoc
@@ -0,0 +1,69 @@
+////
+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:
+//
+// creating-router-network-topology.adoc
+
+[id='adding-routers-router-network-{context}']
+= Adding routers to the router network
+
+After planning the router network topology, you implement it by adding each router to the router network. You add routers one at a time.
+
+This procedure describes the workflow required to add a router to the router network.
+
+.Prerequisites
+
+* {RouterName} is installed on the host.
+
+.Procedure
+
+. xref:configuring-router-properties-router[Configure essential router properties].
++
+To participate in a router network, a router must be configured with a unique ID and an operating mode.
+
+. xref:configuring-network-connections-router[Configure network connections].
+
+.. Connect the router to any other routers in the router network.
++
+Repeat this step for each additional router to which you want to connect this router.
+
+.. If the router should connect with an AMQP client, configure a client connection.
+
+.. If the router should connect to an external AMQP container (such as a message broker), configure the connection.
+
+. xref:securing-network-connections-router[Secure each of the connections that you configured in the previous step].
+
+. (Optional) Configure any additional properties.
++
+These properties should be configured the same way on each router. Therefore, you should only configure each one once, and then copy the configuration to each additional router in the router network.
+
+** xref:authorizing-access-to-messaging-resources[Authorization]
++
+If necessary, configure policies to control which messaging resources clients are able to access on the router network.
+
+** xref:routing[Routing]
++
+{RouterName} automatically routes messages without any configuration: clients can send messages to the router network, and the router automatically routes them to their destinations. However, you can configure the routing to meet your exact requirements. You can configure the routing patterns to be used for certain addresses, create waypoints and autolinks to route messages through broker queues, and create link routes to connect clients to brokers.
+
+** xref:logging[Logging]
++
+You can set the default logging configuration to ensure that events are logged at the correct level for your environment.
+
+. Start the router.
diff --git a/docs/books/user-guide/modules/configuring-router-properties.adoc b/docs/books/user-guide/modules/configuring-router-properties.adoc
new file mode 100644
index 0000000..1c3adb6
--- /dev/null
+++ b/docs/books/user-guide/modules/configuring-router-properties.adoc
@@ -0,0 +1,64 @@
+////
+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:
+//
+// adding-routers-router-network.adoc
+
+[id='configuring-router-properties-{context}']
+= Configuring router properties
+
+By default, {RouterName} operates in `standalone` mode with a randomly-generated ID. If you want to use this router in a router network, you must change these properties.
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. In the `router` section, specify the mode and ID.
++
+--
+This example shows a router configured to operate in `interior` mode:
+
+[options="nowrap",subs="+quotes"]
+----
+router {
+ mode: interior
+ id: Router.A
+}
+----
+
+`mode`:: Specify one of the following modes:
++
+* `standalone` - Use this mode if the router does not communicate with
+other routers and is not part of a router network. When operating in
+this mode, the router only routes messages between directly connected
+endpoints.
+* `interior` - Use this mode if the router is part of a router network
+and needs to collaborate with other routers.
+* `edge` - Use this mode if the router is an edge router that will
+connect to a network of interior routers.
+
+`id`:: The unique
+identifier for the router. This ID will also be the container name at
+the AMQP protocol level.
+--
+
+. If necessary, configure any additional properties for the router.
++
+For information about additional attributes, see link:{qdrouterdConfManPageUrl}#_router[router] in the `qdrouterd.conf` man page.
diff --git a/docs/books/user-guide/modules/connecting-routers-external-amqp-containers.adoc b/docs/books/user-guide/modules/connecting-routers-external-amqp-containers.adoc
new file mode 100644
index 0000000..0fb7516
--- /dev/null
+++ b/docs/books/user-guide/modules/connecting-routers-external-amqp-containers.adoc
@@ -0,0 +1,57 @@
+////
+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 is included in the following assemblies:
+//
+// configuring-network-connections.adoc
+
+[id='connecting-to-external-amqp-containers-{context}']
+= Connecting to external AMQP containers
+
+To enable a router to establish a connection to an external AMQP container (such as a message broker), you configure a `connector`.
+
+[NOTE]
+====
+Instead of configuring a `connector` to initiate connections to the AMQP container, you can configure a `listener` to listen for connections from the AMQP container. However, in this case, the addresses on the AMQP container are available for routing only after the AMQP container has created a connection.
+====
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. Configure a `connector` with the `route-container` role.
++
+--
+This example creates a `connector` that initiates connections to a broker. The addresses on the broker will be available for routing once the router creates the connection and it is accepted by the broker.
+
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ name: my-broker
+ host: 192.0.2.10
+ port: 5672
+ role: route-container
+ ...
+}
+----
+`name`:: The name of the `connector`. Specify a name that describes the entity to which the router will connect.
+`host`:: The IP address (IPv4 or IPv6) or hostname to which the router will connect.
+`port`:: The port number or symbolic service name to which the router will connect.
+`role`:: The role of the connection. Specify `route-container` to indicate that this connection is for an AMQP container that holds known addresses.
+--
diff --git a/docs/books/user-guide/modules/connecting-routers.adoc b/docs/books/user-guide/modules/connecting-routers.adoc
new file mode 100644
index 0000000..daab148
--- /dev/null
+++ b/docs/books/user-guide/modules/connecting-routers.adoc
@@ -0,0 +1,89 @@
+////
+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 is included in the following assemblies:
+//
+// configuring-network-connections.adoc
+
+[id='connecting-routers-{context}']
+= Connecting routers
+
+To connect a router to another router in the router network, you configure a `connector` on one router to create the outbound connection, and a `listener` on the other router to accept the connection.
+
+Because connections are bidirectional, there should only be one connection between any pair of routers. Once the connection is established, message traffic flows in both directions.
+
+This procedure describes how to connect a router to another router in the router network.
+
+.Procedure
+
+. Determine the direction of the connection.
++
+--
+Decide which router should be the "connector", and which should be the "listener". The direction of the connection establishment is sometimes arbitrary, but consider the following factors:
+
+IP network boundaries and firewalls::
+Generally, inter-router connections should always be established from more private to more public. For example, to connect a router in a private IP network to another router in a public location (such as a public cloud provider), the router in the private network must be the "connector" and the router in the public location must be the "listener". This is because the public location cannot reach the private location by TCP/IP without the use of VPNs or other firewall features designed to [...]
+
+Network topology::
+The topology of the router network may affect the direction in which connections should be established between the routers. For example, a star-topology that has a series of routers connected to one or two central "hub" routers should have "listeners" on the hub and "connectors" on the spokes. That way, new spoke routers may be added without changing the configuration of the hub.
+--
+
+. On the router that should create the connection, open the `{RouterConfigFile}` configuration file and add a `connector`.
++
+--
+This example creates a `connector` for an inter-router connection between two interior routers:
+
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ host: 192.0.2.1
+ port: 5001
+ role: inter-router
+ ...
+}
+----
+
+`host`:: The IP address (IPv4 or IPv6) or hostname on which the router will connect.
+`port`:: The port number or symbolic service name on which the router will connect.
+`role`:: The role of the connection. If the connection is between two interior routers, specify `inter-router`. If the connection is between an interior router and an edge router, specify `edge`.
+--
+
+. On the router that should accept the connection establishment, open the `{RouterConfigFile}` configuration file and verify that an inter-router `listener` is configured.
++
+--
+This example creates a `listener` to accept the connection establishment configured in the previous step:
+
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: 0.0.0.0
+ port: 5001
+ role: inter-router
+ ...
+}
+----
+
+`host`:: The IP address (IPv4 or IPv6) or hostname on which the router will listen.
+`port`:: The port number or symbolic service name on which the router will listen.
+`role`:: The role of the connection. If the connection is between two interior routers, specify `inter-router`. If the connection is between an interior router and an edge router, specify `edge`.
+--
+
+. If the router should connect to any other routers, repeat this procedure.
++
+Edge routers can only connect to interior routers. They cannot connect to other edge routers.
diff --git a/docs/books/user-guide/modules/connecting-using-mutual-ssl-tls-authentication.adoc b/docs/books/user-guide/modules/connecting-using-mutual-ssl-tls-authentication.adoc
new file mode 100644
index 0000000..6bc9e05
--- /dev/null
+++ b/docs/books/user-guide/modules/connecting-using-mutual-ssl-tls-authentication.adoc
@@ -0,0 +1,78 @@
+////
+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 is included in the following assemblies:
+//
+// securing-outgoing-connections.adoc
+
+[id='connecting-using-mutual-ssl-tls-authentication-{context}']
+= Connecting using mutual SSL/TLS authentication
+
+You can connect to an external AMQP container (such as a broker) using mutual SSL/TLS authentication. With this method, the router, acting as a client, provides a certificate to the external AMQP container so that it can verify the router's identity.
+
+.Prerequisites
+
+* An X.509 Certificate Authority (CA) must exist for the router.
+
+* A security certificate must be generated for the router and be signed by the CA.
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. If the router does not contain an `sslProfile` that defines the private keys and certificates to connect to the external AMQP container, then add one.
++
+--
+This `sslProfile` contains the locations of the private key and certificates that the router should use to authenticate with its peer.
+
+[options="nowrap",subs="+quotes"]
+----
+sslProfile {
+ name: broker-tls
+ certFile: /etc/qpid-dispatch-certs/tls.crt
+ privateKeyFile: /etc/qpid-dispatch-certs/tls.key
+ caCertFile: /etc/qpid-dispatch-certs/ca.crt
+ ...
+}
+----
+`name`:: A unique name that you can use to refer to this `sslProfile`.
+
+`certFile`:: The absolute path to the file containing the public certificate for this router.
+
+`privateKeyFile`:: The absolute path to the file containing the private key for this router's public certificate.
+
+`caCertFile`:: The absolute path to the CA certificate that was used to sign the router's certificate.
+--
+
+. Configure the `connector` for this connection to use the `sslProfile` that you created.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ host: 192.0.2.1
+ port: 5672
+ role: route-container
+ sslProfile: broker-tls
+ saslMechanisms: EXTERNAL
+ ...
+}
+----
+`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for the inter-router network.
+--
diff --git a/docs/books/user-guide/modules/connecting-using-one-way-ssl-tls-authentication.adoc b/docs/books/user-guide/modules/connecting-using-one-way-ssl-tls-authentication.adoc
new file mode 100644
index 0000000..f4b064e
--- /dev/null
+++ b/docs/books/user-guide/modules/connecting-using-one-way-ssl-tls-authentication.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
+////
+
+// Module is included in the following assemblies:
+//
+// securing-outgoing-connections.adoc
+
+[id='connecting-using-one-way-ssl-tls-authentication-{context}']
+= Connecting using one-way SSL/TLS authentication
+
+You can connect to an external AMQP container (such as a broker) using one-way SSL/TLS. With this method, the router validates the external AMQP container's server certificate to verify its identity.
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. If the router does not contain an `sslProfile` that defines a certificate that can be used to validate the external AMQP container's identity, then add one.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+sslProfile {
+ name: broker-tls
+ caCertFile: /etc/qpid-dispatch-certs/ca.crt
+ ...
+}
+----
+`name`:: A unique name that you can use to refer to this `sslProfile`.
+
+`caCertFile`:: The absolute path to the CA certificate used to verify the external AMQP container's identity.
+--
+
+. Configure the `connector` for this connection to use SSL/TLS to validate the server certificate received by the broker during the SSL handshake.
++
+--
+This example configures a `connector` to a broker. When the router connects to the broker, it will use the CA certificate defined in the `broker-tls` `sslProfile` to validate the server certificate received from the broker.
+
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ host: 192.0.2.1
+ port: 5672
+ role: route-container
+ sslProfile: broker-tls
+ ...
+}
+----
+`sslProfile`:: The name of the `sslProfile` that defines the certificate to use to validate the external AMQP container's identity.
+--
diff --git a/docs/books/user-guide/modules/connecting-using-username-password-authentication.adoc b/docs/books/user-guide/modules/connecting-using-username-password-authentication.adoc
new file mode 100644
index 0000000..cf3f254
--- /dev/null
+++ b/docs/books/user-guide/modules/connecting-using-username-password-authentication.adoc
@@ -0,0 +1,58 @@
+////
+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 is included in the following assemblies:
+//
+// securing-outgoing-connections.adoc
+
+[id='connecting-using-username-password-authentication-{context}']
+= Connecting using user name and password authentication
+
+You can use the SASL PLAIN mechanism to connect to an external AMQP container that requires a user name and password. You can use this method by itself, or you can combine it with SSL/TLS encryption.
+
+.Prerequisites
+
+* The `cyrus-sasl-plain` plugin is installed.
++
+Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed.
++
+--
+// Note about searching for an installing SASL plugins.
+include::{FragmentDir}/fragment-router-sasl-para.adoc[]
+--
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. Configure the `connector` for this connection to provide user name and password credentials to the external AMQP container.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ host: 192.0.2.1
+ port: 5672
+ role: route-container
+ saslMechanisms: PLAIN
+ saslUsername: user
+ saslPassword: password
+ }
+----
+--
diff --git a/docs/books/user-guide/modules/connection-failover.adoc b/docs/books/user-guide/modules/connection-failover.adoc
index 7efdfe5..249359d 100644
--- a/docs/books/user-guide/modules/connection-failover.adoc
+++ b/docs/books/user-guide/modules/connection-failover.adoc
@@ -18,48 +18,21 @@ under the License
////
// Module included in the following assemblies:
-//
+// configuring-network-connections.adoc
[id='connection-failover-{context}']
-= Connection Failover
+= Connection failover
-In {RouterName}, a connector attempts to maintain an open network transport
-connection to the configured remote host and port. If the connection cannot be
-established, the connector will continually retry until the connection is
-established. If an established connection is lost, the connector shall
-immediately attempt to re-establish the connection.
+If a connection between a router and a remote host fails, connection failover enables the connection to be reestablished automatically on an alternate URL.
-Connection Failover is a mechanism by which the remote host can provide
-alternate connection information for the connector to use in the event the
-established connection is lost. In this case, rather than attempting to
-re-establish the connection to the same host, the connector shall try the
-alternate hosts as well. This is useful in the case where the remote host is
-formed by a cluster or array of servers providing the same service.
+A router can use connection failover for both incoming and outgoing connections.
-{RouterName} can participate in Connection Failover as both a client (initiator
-of transport connections) and a server (recipient of transport connections). In
-the client role, connectors shall always honor the failover lists provided by
-connected servers. As a server, a listener may be configured to provide a
-failover list to the clients that connect to it.
-
-Listener attribute failoverUrls is an optional component that contains a
-comma-separated list of URLs to be used as backups for this listener. Each URL
-is of the form:
-
- [(amqp|amqps|ws|wss)://]host_or_ip[:port]
-
-When a client establishes a connection to this listener, it will be provided
-with this list of backup URLs to be used in the event that this connection is
-lost.
-
-As an example, a listener may be configured like this:
-
- listener {
- host: primary.domain.com
- port: amqp
- failoverUrls: secondary.domain.com:20000, tertiary.domain.com
- .
- .
- .
- }
+Connection failover for outgoing connections::
+By default, when you configure a `connector` on a router, the router attempts to maintain an open network transport connection to the configured remote host and port. If the connection cannot be established, the router continually retries until the connection is established. If the connection is established and then fails, the router immediately attempts to reestablish the connection.
++
+When the router establishes a connection to a remote host, the client may provide the router with alternate connection information (sometimes called failover lists) that it can use if the connection is lost. In these cases, rather than attempting to reestablish the connection on the same host, the router will also try the alternate hosts.
++
+Connection failover is particularly useful when the router establishes outgoing connections to a cluster of servers providing the same service.
+Connection failover for incoming connections::
+You can configure a `listener` on a router to provide a list of failover URLs to be used as backups. If the connection is lost, the client can use these failover URLs to reestablish the connection to the router.
diff --git a/docs/books/user-guide/modules/enabling-ssl-tls-client-authentication.adoc b/docs/books/user-guide/modules/enabling-ssl-tls-client-authentication.adoc
new file mode 100644
index 0000000..235d97b
--- /dev/null
+++ b/docs/books/user-guide/modules/enabling-ssl-tls-client-authentication.adoc
@@ -0,0 +1,62 @@
+////
+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 is included in the following assemblies:
+//
+// securing-incoming-client-connections.adoc
+
+[id='enabling-ssl-tls-client-authentication-{context}']
+= Enabling SSL/TLS client authentication
+
+In additional to SSL/TLS encryption, you can also use SSL/TLS to authenticate an incoming connection from a client. With this method, a clients must present its own X.509 certificate to the router, which the router uses to verify the client's identity.
+
+.Prerequisites
+
+* SSL/TLS encryption must be configured.
++
+For more information, see xref:enabling-ssl-tls-encryption-router[].
+
+* The client must have an X.509 certificate that it can use to authenticate to the router.
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. Configure the `listener` for this connection to use SSL/TLS to authenticate the client.
++
+--
+This example adds SSL/TLS authentication to a `normal` listener to authenticate incoming connections from a client. The client will only be able to connect to the router by presenting its own X.509 certificate to the router, which the router will use to verify the client's identity.
+
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: 0.0.0.0
+ port: 5672
+ role: normal
+ sslProfile: service-tls
+ requireSsl: yes
+ authenticatePeer: yes
+ saslMechanisms: EXTERNAL
+ ...
+}
+----
+`authenticatePeer`:: Specify `yes` to authenticate the client's identity.
+
+`saslMechanisms`:: Specify `EXTERNAL` to enable X.509 client certificate authentication.
+--
diff --git a/docs/books/user-guide/modules/enabling-ssl-tls-encryption.adoc b/docs/books/user-guide/modules/enabling-ssl-tls-encryption.adoc
new file mode 100644
index 0000000..5720f6c
--- /dev/null
+++ b/docs/books/user-guide/modules/enabling-ssl-tls-encryption.adoc
@@ -0,0 +1,82 @@
+////
+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 is included in the following assemblies:
+//
+// securing-incoming-client-connections.adoc
+
+[id='enabling-ssl-tls-encryption-{context}']
+= Enabling SSL/TLS encryption
+
+You can use SSL/TLS to encrypt an incoming connection from a client.
+
+.Prerequisites
+
+* An X.509 Certificate Authority (CA) must exist for the client connections.
+
+* A security certificate must be generated and signed by the CA.
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. If the router does not contain an `sslProfile` that defines the private keys and certificates for client connections, then add one.
++
+--
+This `sslProfile` contains the locations of the private key and certificates that the router should use to encrypt connections from clients.
+
+[options="nowrap",subs="+quotes"]
+----
+sslProfile {
+ name: service-tls
+ certFile: /etc/qpid-dispatch-certs/normal/tls.crt
+ privateKeyFile: /etc/qpid-dispatch-certs/normal/tls.key
+ caCertFile: /etc/qpid-dispatch-certs/client-ca/ca.crt
+ ...
+}
+----
+`name`:: A unique name that you can use to refer to this `sslProfile`.
+
+`certFile`:: The absolute path to the file containing the public certificate for this router.
+
+`privateKeyFile`:: The absolute path to the file containing the private key for this router's public certificate.
+
+`caCertFile`:: The absolute path to the CA certificate that was used to sign the router's certificate.
+--
+
+. Configure the `listener` for this connection to use SSL/TLS to encrypt the connection.
++
+--
+This example configures a `normal` listener to encrypt connections from clients.
+
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: 0.0.0.0
+ port: 5672
+ role: normal
+ sslProfile: inter_router_tls
+ requireSsl: yes
+ ...
+}
+----
+`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for client connections.
+
+`requireSsl`:: Specify `true` to encrypt the connection with SSL/TLS.
+--
diff --git a/docs/books/user-guide/modules/enabling-username-password-authentication.adoc b/docs/books/user-guide/modules/enabling-username-password-authentication.adoc
new file mode 100644
index 0000000..a4503ff
--- /dev/null
+++ b/docs/books/user-guide/modules/enabling-username-password-authentication.adoc
@@ -0,0 +1,78 @@
+////
+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 is included in the following assemblies:
+//
+// securing-incoming-client-connections.adoc
+
+[id='enabling-username-password-authentication-{context}']
+= Enabling user name and password authentication
+
+You can use the SASL PLAIN mechanism to authenticate incoming client connections against a set of user names and passwords. You can use this method by itself, or you can combine it with SSL/TLS encryption.
+
+.Prerequisites
+
+* A SASL database containing the usernames and passwords exists.
+
+* The SASL configuration file is configured.
++
+By default, this file should be `/etc/sasl2/qdrouterd.conf`.
+
+* The `cyrus-sasl-plain` plugin is installed.
++
+Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed.
++
+--
+// Note about searching for an installing SASL plugins.
+include::{FragmentDir}/fragment-router-sasl-para.adoc[]
+--
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. In the `router` section, specify the path to the SASL configuration file.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+router {
+ mode: interior
+ id: Router.A
+ saslConfigDir: /etc/sasl2/
+}
+----
+`saslConfigDir`:: The absolute path to the SASL configuration file that contains the path to the SASL database that stores the user names and passwords.
+--
+
+. Configure the `listener` for this connection to authenticate clients using SASL PLAIN.
++
+--
+This example configures basic user name and password authentication for a `listener`. In this case, no SSL/TLS encryption is being used.
+
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: 0.0.0.0
+ port: 5672
+ authenticatePeer: yes
+ saslMechanisms: PLAIN
+ }
+----
+--
diff --git a/docs/books/user-guide/management.adoc b/docs/books/user-guide/modules/example-router-network-topologies.adoc
similarity index 54%
copy from docs/books/user-guide/management.adoc
copy to docs/books/user-guide/modules/example-router-network-topologies.adoc
index fa933de..454f216 100644
--- a/docs/books/user-guide/management.adoc
+++ b/docs/books/user-guide/modules/example-router-network-topologies.adoc
@@ -17,22 +17,18 @@ specific language governing permissions and limitations
under the License
////
-= Management
+// Module included in the following assemblies:
+//
+// creating-router-networks.adoc
-You can manage {RouterName} using both graphical and command-line tools.
+[id='example-router-network-topologies-{context}']
+= Example router network topologies
-{ConsoleName}:: A graphical tool for monitoring and managing {RouterName} routers.
-`qdstat`:: A command-line tool for monitoring the status of {RouterName} routers.
-`qdmanage`:: A command-line tool for viewing and updating the configuration of {RouterName} routers.
+With {RouterName} you can deploy a router network of any arbitrary topology. Use the following examples to help design a topology that best fits your requirements.
-// Using the Console
-include::using-console.adoc[leveloffset=+1]
+[discrete]
+== Small mesh in a single site
-// Monitoring Using qdstat
-include::monitoring-using-qdstat.adoc[leveloffset=+1]
-// Managing Using qdmanage
-include::managing-using-qdmanage.adoc[leveloffset=+1]
-
-// Management Entities
-include::management-entities.adoc[leveloffset=+1]
+[discrete]
+== Multi-site mesh
diff --git a/docs/books/user-guide/modules/integrating-with-kerberos.adoc b/docs/books/user-guide/modules/integrating-with-kerberos.adoc
new file mode 100644
index 0000000..4385b26
--- /dev/null
+++ b/docs/books/user-guide/modules/integrating-with-kerberos.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
+////
+
+// Module is included in the following assemblies:
+//
+// securing-incoming-client-connections.adoc
+
+[id='integrating-with-kerberos-{context}']
+= Integrating with Kerberos
+
+If you have implemented Kerberos in your environment, you can use it with the `GSSAPI` SASL mechanism to authenticate incoming connections.
+
+.Prerequisites
+
+* A Kerberos infrastructure must be deployed in your environment.
+
+* In the Kerberos environment, a service principal of `amqp/<hostname>@<realm>` must be configured.
++
+This is the service principal that {RouterName} uses.
+
+* The `cyrus-sasl-gssapi` package must be installed on each client and the router host machine.
+
+.Procedure
+
+. On the router's host machine, open the `/etc/sasl2/qdrouterd.conf` configuration file.
++
+--
+This example shows a `/etc/sasl2/qdrouterd.conf` configuration file:
+
+[options="nowrap"]
+----
+pwcheck_method: auxprop
+auxprop_plugin: sasldb
+sasldb_path: qdrouterd.sasldb
+keytab: /etc/krb5.keytab
+mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI
+----
+--
+
+. Verify the following:
+** The `mech_list` attribute contains the `GSSAPI` mechanism.
+** The `keytab` attribute points to the location of the keytab file.
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. In the `router` section, specify the path to the SASL configuration file.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+router {
+ mode: interior
+ id: Router.A
+ saslConfigDir: /etc/sasl2/
+}
+----
+`saslConfigDir`:: The absolute path to the SASL configuration file that contains the path to the SASL database.
+--
+
+. For each incoming connection using Kerberos for authentication, set the `listener` to use the `GSSAPI` mechanism.
++
+--
+----
+listener {
+ host: 0.0.0.0
+ port: 5672
+ authenticatePeer: yes
+ saslMechanisms: GSSAPI
+ }
+----
+--
diff --git a/docs/books/user-guide/modules/listening-client-connections.adoc b/docs/books/user-guide/modules/listening-client-connections.adoc
new file mode 100644
index 0000000..9f0b4ca
--- /dev/null
+++ b/docs/books/user-guide/modules/listening-client-connections.adoc
@@ -0,0 +1,61 @@
+////
+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 is included in the following assemblies:
+//
+// configuring-router.adoc
+
+[id='listening-client-connections-{context}']
+= Listening for client connections
+
+To enable a router to listen for and accept connections from AMQP clients, you configure a `listener`.
+
+Once the connection is enabled on the router, clients can connect to it using the same methods they use to connect to a broker. From the client's perspective, the router connection and link establishment are identical to a broker connection and link establishment.
+
+[NOTE]
+====
+Instead of configuring a `listener` to listen for connections from the client, you can configure a `connector` to initiate connections to the client. In this case, the router will use the `connector` to initiate the connection, but it will not create any links. Links are only created by the peer that accepts the connection.
+====
+
+.Procedure
+
+include::{FragmentDir}/fragment-router-open-config-file-step.adoc[]
+
+. Configure a `listener` with the `normal` role.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: primary.example.com
+ port: 5672
+ role: normal
+ failoverUrls: secondary.example.com:20000, tertiary.example.com
+ ...
+}
+----
+`host`:: The IP address (IPv4 or IPv6) or hostname on which the router will listen.
+`port`:: The port number or symbolic service name on which the router will listen.
+`role`:: The role of the connection. Specify `normal` to indicate that this connection is used for message delivery for AMQP clients.
+`failoverUrls` (optional):: A comma-separated list of backup URLs the client can use to reconnect if the established connection is lost. Each URL must use the following form:
++
+`[(amqp|amqps|ws|wss)://](__HOST__|__IP ADDRESS__)[:port]`
++
+For more information, see xref:connection-failover-router[].
+--
diff --git a/docs/books/user-guide/modules/next-steps.adoc b/docs/books/user-guide/modules/next-steps.adoc
index 83a1369..4b340e1 100644
--- a/docs/books/user-guide/modules/next-steps.adoc
+++ b/docs/books/user-guide/modules/next-steps.adoc
@@ -17,26 +17,25 @@ specific language governing permissions and limitations
under the License
////
-// This assembly is included in the following assemblies:
+// This module 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.
+After you successfully install a standalone router and use it to distribute messages between two clients, you can configure a router network topology and route messages.
-Configure the router::
-You can configure the router to meet the requirements of your production environment.
+Configure a router network topology::
+After configuring a single router, you can deploy additional routers and connect them together to form a router network. Router networks can be any arbitrary topology.
+
+Route messages through the router network::
+Regardless of the underlying router network topology, you can configure how you want messages to be routed through the router network.
+
--
-* 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.
++
+For more information, see xref:routing[].
diff --git a/docs/books/user-guide/modules/router-connection-considerations.adoc b/docs/books/user-guide/modules/router-connection-considerations.adoc
new file mode 100644
index 0000000..9902951
--- /dev/null
+++ b/docs/books/user-guide/modules/router-connection-considerations.adoc
@@ -0,0 +1,45 @@
+////
+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:
+//
+// planning-router-network.adoc
+
+[id='router-connection-considerations-{context}']
+= Router connection considerations
+
+Before creating a router network, you should understand how routers connect to each other, and the factors that affect the direction in which an inter-router connection should be established.
+
+[discrete]
+== Inter-router connections are bidirectional
+
+When a connection is established between routers, message traffic flows in both directions across that connection. Each connection has a client side (a _connector_) and a server side (a _listener_) for the purposes of connection establishment. Once the connection is established, the two sides become equal participants in a bidirectional connection. For the purposes of routing AMQP traffic across the network, the direction of connection establishment is not relevant.
+
+[discrete]
+== Factors that affect the direction of connection establishment
+
+When establishing inter-router connections, you 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.
+
+When determining the direction of inter-router connections in the network topology, consider the following factors:
+
+IP network boundaries and firewalls::
+Generally, inter-router connections should always be established from more private to more public. For example, to connect a router in a private IP network to another router in a public location (such as 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 by TCP/IP without the use of VPNs or other firewall features designed to [...]
+
+Network topology::
+The topology of the router network may affect the direction in which connections should be established between the routers. For example, a star-topology that has a series of routers connected to one or two central "hub" routers should have listeners on the hub and connectors on the spokes. That way, new spoke routers may be added without changing the configuration of the hub.
diff --git a/docs/books/user-guide/modules/router-management.adoc b/docs/books/user-guide/modules/router-management.adoc
index 91e0ca5..f7901f2 100644
--- a/docs/books/user-guide/modules/router-management.adoc
+++ b/docs/books/user-guide/modules/router-management.adoc
@@ -44,6 +44,4 @@ A command-line tool for viewing and updating the configuration of a router at ru
.Additional resources
-* xref:console-overview[]
-* xref:monitoring-using-qdstat[]
-* xref:managing-router[]
+* xref:monitoring-managing-router-network[]
diff --git a/docs/books/user-guide/modules/router-network-security-considerations.adoc b/docs/books/user-guide/modules/router-network-security-considerations.adoc
new file mode 100644
index 0000000..5ec9ba2
--- /dev/null
+++ b/docs/books/user-guide/modules/router-network-security-considerations.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:
+//
+// planning-router-network.adoc
+
+[id='router-network-security-considerations-{context}']
+= Router network security considerations
+
+In the router network, the interior routers should be secured with a strong authentication mechanism in which they identify themselves to each other. You should choose and plan this authentication mechanism before creating the router network.
+
+[WARNING]
+====
+If the interior routers are not properly secured, unauthorized routers (or endpoints pretending to be routers) could join the router network, compromising its integrity and availability.
+====
+
+You can choose a security mechanism that best fits your requirements. However, you should consider the following recommendations:
+
+* Create an X.509 Certificate Authority (CA) to oversee the interior portion of the router network.
+
+* Generate an individual certificate for each interior router.
++
+Each interior router can be configured to use the CA to authenticate connections from any other interior routers.
++
+[NOTE]
+====
+Connections from edge routers and clients can use different levels of security, depending on your requirements.
+====
+
+By using these recommendations, a new interior router cannot join the network until the owner of the CA issues a new certificate for the new router. In addition, an intruder wishing to spoof an interior router cannot do so because it would not have a valid X.509 certificate issued by the network’s CA.
diff --git a/docs/books/user-guide/modules/router-operating-modes.adoc b/docs/books/user-guide/modules/router-operating-modes.adoc
new file mode 100644
index 0000000..ee1738b
--- /dev/null
+++ b/docs/books/user-guide/modules/router-operating-modes.adoc
@@ -0,0 +1,36 @@
+////
+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:
+//
+// planning-router-network.adoc
+
+[id='router-operating-modes-{context}']
+= Router operating modes
+
+In {RouterName}, each router can operate in _standalone_, _interior_, or _edge_ mode. In a router network, you deploy multiple interior routers or a combination of interior and edge routers to create the desired network topology.
+
+Standalone::
+The router operates as a single, standalone network node. A standalone router cannot be used in a router network - it does not establish connections with other routers, and only routes messages between directly-connected endpoints.
+
+Interior::
+The router is part of the interior of the router network. Interior routers establish connections with each other and automatically compute the lowest cost paths across the network. You can have up to 128 interior routers in the router network.
+
+Edge::
+The router maintains a single uplink connection to one or more interior routers. Edge routers do not participate in the routing protocol or route computation, but they enable you to efficiently scale the routing network. There are no limits to the number of edge routers you can deploy in a router network.
diff --git a/docs/books/user-guide/modules/router-security.adoc b/docs/books/user-guide/modules/router-security.adoc
index b11f928..257c4d8 100644
--- a/docs/books/user-guide/modules/router-security.adoc
+++ b/docs/books/user-guide/modules/router-security.adoc
@@ -38,6 +38,6 @@ Authorization::
.Additional resources
-* xref:authenticating-remote-peers[]
+* xref:securing-network-connections-{context}[]
-* xref:authorizing-access-to-messaging-resources[]
\ No newline at end of file
+* xref:authorizing-access-to-messaging-resources[]
diff --git a/docs/books/user-guide/modules/securing-connections-between-routers.adoc b/docs/books/user-guide/modules/securing-connections-between-routers.adoc
new file mode 100644
index 0000000..10e1460
--- /dev/null
+++ b/docs/books/user-guide/modules/securing-connections-between-routers.adoc
@@ -0,0 +1,118 @@
+////
+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 is included in the following assemblies:
+//
+// securing-network-connections.adoc
+
+[id='securing-connections-between-routers-{context}']
+= Securing connections between routers
+
+Connections between interior routers should be secured with SSL/TLS encryption and authentication (also called mutual authentication) to prevent unauthorized routers (or endpoints pretending to be routers) from joining the network.
+
+SSL/TLS mutual authentication requires an X.509 Certificate Authority (CA) with individual certificates generated for each interior router. Connections between the interior routers are encrypted, and the CA authenticates each incoming inter-router connection.
+
+This procedure describes how to secure a connection between two interior routers using SSL/TLS mutual authentication.
+
+.Prerequisites
+
+* An X.509 Certificate Authority must exist for the interior routers.
+
+* A security certificate must be generated for each router and be signed by the CA.
+
+* An inter-router connection must exist between the routers.
++
+For more information, see xref:connecting-routers-router[].
+
+.Procedure
+
+. On the router that establishes the connection, do the following:
+
+.. Open the `{RouterConfigFile}`.
+
+.. If the router does not contain an `sslProfile` that defines the private keys and certificates for the inter-router network, then add one.
++
+--
+This `sslProfile` contains the locations of the private key and certificates that the router uses to authenticate with its peer.
+
+[options="nowrap",subs="+quotes"]
+----
+sslProfile {
+ name: inter-router-tls
+ certFile: /etc/qpid-dispatch-certs/inter-router/tls.crt
+ privateKeyFile: /etc/qpid-dispatch-certs/inter-router/tls.key
+ caCertFile: /etc/qpid-dispatch-certs/inter-router/ca.crt
+ ...
+}
+----
+`name`:: A unique name that you can use to refer to this `sslProfile`.
+
+`certFile`:: The absolute path to the file containing the public certificate for this router.
+
+`privateKeyFile`:: The absolute path to the file containing the private key for this router's public certificate.
+
+`caCertFile`:: The absolute path to the CA certificate that was used to sign the router's certificate.
+--
+
+.. Configure the inter-router `connector` for this connection to use the `sslProfile` that you created.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+connector {
+ host: 192.0.2.1
+ port: 5001
+ role: inter-router
+ sslProfile: inter-router-tls
+ ...
+}
+----
+`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for the inter-router network.
+--
+
+. On the router that listens for the connection, do the following:
+
+.. Open the `{RouterConfigFile}`.
+
+.. If the router does not contain an `sslProfile` that defines the private keys and certificates for the inter-router network, then add one.
+
+.. Configure the inter-router `listener` for this connection to use SSL/TLS to secure the connection.
++
+--
+[options="nowrap",subs="+quotes"]
+----
+listener {
+ host: 0.0.0.0
+ port: 5001
+ role: inter-router
+ sslProfile: inter_router_tls
+ authenticatePeer: yes
+ requireSsl: yes
+ saslMechanisms: EXTERNAL
+ ...
+}
+----
+`sslProfile`:: The name of the `sslProfile` that defines the SSL/TLS private keys and certificates for the inter-router network.
+
+`authenticatePeer`:: Specify `yes` to authenticate the peer interior router's identity.
+
+`requireSsl`:: Specify `yes` to encrypt the connection with SSL/TLS.
+
+`saslMechanisms`:: Specify `EXTERNAL` to enable X.509 client certificate authentication.
+--
diff --git a/docs/books/user-guide/modules/sending-test-messages.adoc b/docs/books/user-guide/modules/sending-test-messages.adoc
index 85b9f44..fc2daaf 100644
--- a/docs/books/user-guide/modules/sending-test-messages.adoc
+++ b/docs/books/user-guide/modules/sending-test-messages.adoc
@@ -27,7 +27,7 @@ under the License
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.
+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.
@@ -37,7 +37,7 @@ A broker is not used in this procedure, so there is no _"store and forward"_ mec
.Procedure
-. Navigate to the {ClientAmqpPythonName} Python examples directory.
+. Navigate to the {ClientAmqpPythonName} examples directory.
+
--
[source,bash,options="nowrap",subs="+quotes"]
diff --git a/docs/books/user-guide/modules/starting-router.adoc b/docs/books/user-guide/modules/starting-router.adoc
index 7a36c42..c101a37 100644
--- a/docs/books/user-guide/modules/starting-router.adoc
+++ b/docs/books/user-guide/modules/starting-router.adoc
@@ -31,7 +31,7 @@ After installing {RouterName}, you start the router by using the `qdrouterd` com
// 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`.
+The router starts, using the default configuration file stored at `/etc/qpid-dispatch/qdrouterd.conf`.
. View the log to verify the router status:
+
diff --git a/docs/books/user-guide/routing.adoc b/docs/books/user-guide/routing.adoc
index 22533da..4bee9ed 100644
--- a/docs/books/user-guide/routing.adoc
+++ b/docs/books/user-guide/routing.adoc
@@ -18,7 +18,7 @@ under the License
////
[id='routing']
-= Routing
+= Routing messages through the router network
Routing is the process by which messages are delivered to their destinations. To accomplish this, {RouterName} provides two routing mechanisms: _message routing_ and _link routing_.
@@ -103,7 +103,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
+== 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_.
@@ -111,7 +111,7 @@ With message routing, you can do the following:
* Route messages between clients (direct-routed, or brokerless messaging)
+
-This involves configuring an address with a routing pattern. All messages sent to the address will be routed based on the routing pattern.
+This involves configuring an address with a routing pattern. All messages sent to the address will be routed based on the routing pattern.
* Route messages through a broker queue (brokered messaging)
+
This involves configuring a waypoint address to identify the broker queue and then connecting the router to the broker. All messages sent to the waypoint address will be routed to the broker queue.
@@ -298,7 +298,7 @@ The following table describes the levels of reliability provided by each routing
| Routing pattern | Reliable?
| Anycast (Balanced or Closest)
-a| Yes, when the message deliveries are unsettled.
+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:
@@ -311,7 +311,7 @@ There is a reliability contract that the router network abides by when deliverin
* 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.
+a| No.
If a producer sends an unsettled delivery, the disposition may be ACCEPTED or RELEASED.
@@ -386,7 +386,7 @@ You can route messages to a queue hosted on a single broker, or route messages t
.Brokered Messaging
image::brokered-messaging.png[Brokered Messaging, align="center"]
-In this diagram, the sender connects to the router and sends messages to my_queue. The router attaches an outgoing link to the broker, and then sends the messages to my_queue. Later, the receiver connects to the router and requests messages from my_queue. The router attaches an incoming link to the broker to receive the messages from my_queue, and then delivers them to the receiver.
+In this diagram, the sender connects to the router and sends messages to my_queue. The router attaches an outgoing link to the broker, and then sends the messages to my_queue. Later, the receiver connects to the router and requests messages from my_queue. The router attaches an incoming link to the broker to receive the messages from my_queue, and then delivers them to the receiver.
You can also route messages to a _sharded queue_, which is a single, logical queue comprised of multiple, underlying physical queues. Using queue sharding, it is possible to distribute a single queue over multiple brokers. Clients can connect to any of the brokers that hold a shard to send and receive messages.
@@ -413,7 +413,7 @@ A waypoint address identifies a queue on a broker to which you want to route mes
.Prerequisites
-An incoming connection (`listener`) to which the clients can connect should be configured. This connection defines how the producers and consumers connect to the router to send and receive messages. For more information, see xref:adding-incoming-connections[Adding Incoming Connections].
+An incoming connection (`listener`) to which the clients can connect should be configured. This connection defines how the producers and consumers connect to the router to send and receive messages. For more information, see xref:listening-client-connections-{context}[].
// Does the broker queue have to exist before you create the waypoint address? If it doesn't exist, will you get an error?
@@ -567,7 +567,7 @@ autoLink { // <6>
<3> The incoming autolink from `queue.first` on the broker to the router.
<4> The outgoing autolink from the router to `queue.first` on the broker.
<5> The incoming autolink from `queue.second` on the broker to the router.
-<6> The outgoing autolink from the router to `queue.second` on the broker.
+<6> The outgoing autolink from the router to `queue.second` on the broker.
==== How the Messages are Routed
@@ -677,7 +677,7 @@ Unlike message routing, with link routing, the sender and receiver handle flow c
[id='creating-link-route']
=== Creating a Link Route
-
+
Link routes establish a link between a sender and a receiver that travels through a router. You can configure inward and outward link routes to enable the router to receive link-attaches from clients and to send them to a particular destination.
With link routing, client traffic is handled on the broker, not the router. Clients have a direct link through the router to a broker's queue. Therefore, each client is a separate producer or consumer.
@@ -728,7 +728,7 @@ linkRoute {
{RouterName} does not support routing transactions to multiple brokers. If you have multiple brokers in your environment, choose a single broker and route all transactions to it.
--
-
+
. If you want clients to send messages on this link route, create an incoming link route:
+
--
@@ -828,13 +828,13 @@ The relevant part of the configuration file for router `Ra` shows the following:
--
[options="nowrap"]
-----
+----
connector { // <1>
name: broker
role: route-container
host: 198.51.100.1
port: 61617
- saslMechanisms: ANONYMOUS
+ saslMechanisms: ANONYMOUS
}
linkRoute { // <2>
@@ -844,7 +844,7 @@ linkRoute { // <2>
}
linkRoute { // <3>
- prefix: b2
+ prefix: b2
direction: out
connection: broker
}
@@ -858,8 +858,8 @@ This configuration enables router `Ra` to advertise itself as a valid destinatio
[NOTE]
====
-While not required, routers `Rp` and `Rb` should also have the same configuration.
-====
+While not required, routers `Rp` and `Rb` should also have the same configuration.
+====
==== How the Client Receives Messages
@@ -873,3 +873,71 @@ To receive messages from the `b2.event-queue` on broker `B2`, client `C1` attach
====
If broker `B2` is unavailable for any reason, router `Ra` will not advertise itself as a destination for `b2` addresses. In this case, routers `Rb` and `Rp` will reject link attaches that should be routed to broker `B2` with an error message indicating that there is no route available to the destination.
====
+
+[id='router-address-pattern-matching']
+=== Pattern Matching for Addresses
+
+In some router configuration scenarios, you might need to use pattern matching to match a range of addresses rather than a single, literal address. Address patterns match any address that corresponds to the pattern.
+
+An address pattern is a sequence of tokens (typically words) that are delimited by either `.` or `/` characters. They also can contain special wildcard characters that represent words:
+
+* `*` represents exactly one word
+* `#` represents zero or more words
+
+.Address Pattern
+====
+This address contains two tokens, separated by the `/` delimiter:
+
+`my/address`
+====
+
+.Address Pattern with Wildcard
+====
+This address contains three tokens. The `*` is a wildcard, representing any single word that might be between `my` and `address`:
+
+`my/*/address`
+====
+
+The following table shows some address patterns and examples of the addresses that would match them:
+
+[options="header"]
+|===
+| This pattern... | Matches... | But not...
+
+a| `news/*`
+a| `news/europe`
+
+`news/usa`
+a| `news`
+
+`news/usa/sports`
+
+a| `news/#`
+a| `news`
+
+`news/europe`
+
+`news/usa/sports`
+a| `europe`
+
+`usa`
+
+a| `news/europe/#`
+a| `news/europe`
+
+`news/europe/sports`
+
+`news/europe/politics/fr`
+a| `news/usa`
+
+`europe`
+
+a| `news/*/sports`
+a| `news/europe/sports`
+
+`news/usa/sports`
+a| `news`
+
+`news/europe/fr/sports`
+
+|===
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org