This is an automated email from the ASF dual-hosted git repository.
bhardesty 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 ce8a89c Minor edits and improvements to doc overview content. This
closes #637.
ce8a89c is described below
commit ce8a89cbadc830ae6fc12009a7fe84bd11faeeef
Author: Ben Hardesty <[email protected]>
AuthorDate: Wed Nov 6 16:35:35 2019 -0500
Minor edits and improvements to doc overview content. This closes #637.
---
.../configuring-network-connections.adoc | 12 +++++------
.../assemblies/user-guide/configuring-router.adoc | 14 ++++++------
.../creating-router-network-topology.adoc | 18 ++++++----------
.../assemblies/user-guide/getting-started.adoc | 9 +++++---
...work.adoc => router-deployment-guidelines.adoc} | 14 ++++++------
.../securing-incoming-client-connections.adoc | 8 +++----
.../user-guide/securing-network-connections.adoc | 8 +++----
.../user-guide/securing-outgoing-connections.adoc | 10 ++++-----
.../common/fragment-router-install-steps.adoc | 2 +-
...onnecting-routers-external-amqp-containers.adoc | 6 ++++++
.../modules/user-guide/connecting-routers.adoc | 6 ++++++
.../user-guide/listening-client-connections.adoc | 8 ++++++-
docs/books/modules/user-guide/next-steps.adoc | 25 +++++++++-------------
...ions.adoc => router-connection-guidelines.adoc} | 6 +++---
...etwork.adoc => router-deployment-workflow.adoc} | 12 +++++------
...onsiderations.adoc => security-guidelines.adoc} | 8 +++----
...adoc => understanding-connection-failover.adoc} | 4 ++--
docs/books/user-guide/book.adoc | 3 +++
18 files changed, 92 insertions(+), 81 deletions(-)
diff --git
a/docs/books/assemblies/user-guide/configuring-network-connections.adoc
b/docs/books/assemblies/user-guide/configuring-network-connections.adoc
index ef00c70..39d8e62 100644
--- a/docs/books/assemblies/user-guide/configuring-network-connections.adoc
+++ b/docs/books/assemblies/user-guide/configuring-network-connections.adoc
@@ -26,12 +26,12 @@ under the License
{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:
+You can do the following:
-`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.
+* xref:connecting-routers-{context}[Connect a router to another router]
+* xref:listening-client-connections-{context}[Listen for client connections]
+* xref:connecting-to-external-amqp-containers-{context}[Connect a router to an
external AMQP container]
+* xref:understanding-connection-failover-{context}[Understand connection
failover]
// Connecting routers
include::../../modules/user-guide/connecting-routers.adoc[leveloffset=+1]
@@ -43,4 +43,4 @@
include::../../modules/user-guide/listening-client-connections.adoc[leveloffset=
include::../../modules/user-guide/connecting-routers-external-amqp-containers.adoc[leveloffset=+1]
// Connection failover
-include::../../modules/user-guide/connection-failover.adoc[leveloffset=+1]
+include::../../modules/user-guide/understanding-connection-failover.adoc[leveloffset=+1]
diff --git a/docs/books/assemblies/user-guide/configuring-router.adoc
b/docs/books/assemblies/user-guide/configuring-router.adoc
index 0f01526..e9b7121 100644
--- a/docs/books/assemblies/user-guide/configuring-router.adoc
+++ b/docs/books/assemblies/user-guide/configuring-router.adoc
@@ -22,17 +22,17 @@ under the License
// book.adoc
[id='configuring-router-{context}']
-= Configuring a router
+= Configuring {RouterName}
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:
+You can do the following:
-* Essential router properties
-* Network connections
-* Security settings (authentication and authorization)
-* Routing (message routing and link routing)
-* Logging
+* xref:configuring-router-properties-{context}[Configure essential router
properties]
+* xref:configuring-network-connections-{context}[Configure network connections]
+* xref:securing-network-connections-{context}[Secure network connections]
+* xref:authorizing-access-to-messaging-resources[Authorize access to messaging
resources]
+* xref:logging[Configure logging]
// Configuring router properties
include::../../modules/user-guide/configuring-router-properties.adoc[leveloffset=+1]
diff --git
a/docs/books/assemblies/user-guide/creating-router-network-topology.adoc
b/docs/books/assemblies/user-guide/creating-router-network-topology.adoc
index 6064f9b..c4ad944 100644
--- a/docs/books/assemblies/user-guide/creating-router-network-topology.adoc
+++ b/docs/books/assemblies/user-guide/creating-router-network-topology.adoc
@@ -30,20 +30,14 @@ With {RouterName}, the router network topology is
independent from the message r
To create the router network topology, complete the following:
-. xref:planning-router-network-{context}[Plan the router network].
+. xref:router-deployment-guidelines-{context}[Understand the router network
deployment guidelines].
+
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-{context}[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)
+. xref:router-deployment-workflow-{context}[Build the router network by
deploying routers one at a time].
-// Planning a router network
-include::planning-router-network.adoc[leveloffset=+1]
+// Router deployment guidelines
+include::router-deployment-guidelines.adoc[leveloffset=+1]
-// Adding routers to the router network
-include::../../modules/user-guide/adding-routers-router-network.adoc[leveloffset=+1]
+// Router deployment workflow
+include::../../modules/user-guide/router-deployment-workflow.adoc[leveloffset=+1]
diff --git a/docs/books/assemblies/user-guide/getting-started.adoc
b/docs/books/assemblies/user-guide/getting-started.adoc
index a5b987b..cfb8a92 100644
--- a/docs/books/assemblies/user-guide/getting-started.adoc
+++ b/docs/books/assemblies/user-guide/getting-started.adoc
@@ -24,10 +24,13 @@ under the License
[id='getting-started-{context}']
= Getting started
-This section shows you how to install {RouterName} on a single host, start the
router with the default configuration settings, and distribute messages between
two clients.
+This section shows you how to start the {RouterName} with the default
configuration settings, and distribute messages between two clients.
-// Installing Dispatch Router
-include::../../modules/user-guide/installing-router.adoc[leveloffset=+1]
+.Prerequisites
+
+* {RouterName} must be installed.
++
+For more information, see xref:installing-router-{context}[].
// Viewing the default router configuration file
include::../../modules/user-guide/viewing-default-router-configuration-file.adoc[leveloffset=+1]
diff --git a/docs/books/assemblies/user-guide/planning-router-network.adoc
b/docs/books/assemblies/user-guide/router-deployment-guidelines.adoc
similarity index 77%
rename from docs/books/assemblies/user-guide/planning-router-network.adoc
rename to docs/books/assemblies/user-guide/router-deployment-guidelines.adoc
index 2cd0ec3..43286c4 100644
--- a/docs/books/assemblies/user-guide/planning-router-network.adoc
+++ b/docs/books/assemblies/user-guide/router-deployment-guidelines.adoc
@@ -19,18 +19,18 @@ under the License
// This assembly is included in the following assemblies:
//
-// creating-router-networks.adoc
+// creating-router-network-topology.adoc
-[id='planning-router-network-{context}']
-= Planning a router network
+[id='router-deployment-guidelines-{context}']
+= {RouterName} deployment guidelines
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.
// Router operating modes
include::../../modules/user-guide/router-operating-modes.adoc[leveloffset=+1]
-// Security considerations
-include::../../modules/user-guide/router-network-security-considerations.adoc[leveloffset=+1]
+// Security guidelines
+include::../../modules/user-guide/security-guidelines.adoc[leveloffset=+1]
-// Example router network topologies
-// include::modules/example-router-network-topologies.adoc[leveloffset=+1]
+// Router connection guidelines
+include::../../modules/user-guide/router-connection-guidelines.adoc[leveloffset=+1]
diff --git
a/docs/books/assemblies/user-guide/securing-incoming-client-connections.adoc
b/docs/books/assemblies/user-guide/securing-incoming-client-connections.adoc
index f95ca6c..0650fc5 100644
--- a/docs/books/assemblies/user-guide/securing-incoming-client-connections.adoc
+++ b/docs/books/assemblies/user-guide/securing-incoming-client-connections.adoc
@@ -26,10 +26,10 @@ under the License
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-{context}[Enabling SSL/TLS encryption]
-* xref:enabling-ssl-tls-client-authentication-{context}[Enabling SSL/TLS
client authentication]
-* xref:enabling-username-password-authentication-{context}[Enabling user name
and password authentication]
-* xref:integrating-with-kerberos-{context}[Integrating with Kerberos]
+* xref:enabling-ssl-tls-encryption-{context}[Enable SSL/TLS encryption]
+* xref:enabling-ssl-tls-client-authentication-{context}[Enable SSL/TLS client
authentication]
+* xref:enabling-username-password-authentication-{context}[Enable user name
and password authentication]
+* xref:integrating-with-kerberos-{context}[Integrate with Kerberos]
// Enabling SSL/TLS encryption
include::../../modules/user-guide/enabling-ssl-tls-encryption.adoc[leveloffset=+1]
diff --git a/docs/books/assemblies/user-guide/securing-network-connections.adoc
b/docs/books/assemblies/user-guide/securing-network-connections.adoc
index d194714..8f4c141 100644
--- a/docs/books/assemblies/user-guide/securing-network-connections.adoc
+++ b/docs/books/assemblies/user-guide/securing-network-connections.adoc
@@ -29,11 +29,11 @@ You can configure {RouterName} to communicate with clients,
routers, and brokers
* 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:
+You configure SSL/TLS, SASL (or a combination of both) to secure any of the
following:
-* xref:securing-connections-between-routers-{context}[Connections between
routers]
-* xref:securing-incoming-client-connections-{context}[Incoming client
connections]
-* xref:securing-outgoing-connections-{context}[Outgoing connections]
+* xref:securing-connections-between-routers-{context}[Secure connections
between routers]
+* xref:securing-incoming-client-connections-{context}[Secure incoming client
connections]
+* xref:securing-outgoing-connections-{context}[Secure outgoing connections]
// Securing connections between routers
include::../../modules/user-guide/securing-connections-between-routers.adoc[leveloffset=+1]
diff --git
a/docs/books/assemblies/user-guide/securing-outgoing-connections.adoc
b/docs/books/assemblies/user-guide/securing-outgoing-connections.adoc
index 5856c48..3be68e4 100644
--- a/docs/books/assemblies/user-guide/securing-outgoing-connections.adoc
+++ b/docs/books/assemblies/user-guide/securing-outgoing-connections.adoc
@@ -24,13 +24,11 @@ under the License
[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.
+If a router is configured to create connections to external AMQP containers
(such as message brokers), you can use the following methods to secure the
connection:
-You can configure a router to create outgoing connections using:
-
-* xref:connecting-using-one-way-ssl-tls-authentication-{context}[SSL/TLS
encryption (one-way authentication)]
-* xref:connecting-using-mutual-ssl-tls-authentication-{context}[SSL/TLS mutual
authentication]
-* xref:connecting-using-username-password-authentication-{context}[User name
and password authentication (with or without SSL/TLS encryption)]
+* xref:connecting-using-one-way-ssl-tls-authentication-{context}[Connect using
SSL/TLS encryption (one-way authentication)]
+* xref:connecting-using-mutual-ssl-tls-authentication-{context}[Connect using
SSL/TLS mutual authentication]
+* xref:connecting-using-username-password-authentication-{context}[Connect
using user name and password authentication (with or without SSL/TLS
encryption)]
// Connecting using SSL/TLS encryption
include::../../modules/user-guide/connecting-using-one-way-ssl-tls-authentication.adoc[leveloffset=+1]
diff --git a/docs/books/common/fragment-router-install-steps.adoc
b/docs/books/common/fragment-router-install-steps.adoc
index 21ccc81..1a7260d 100644
--- a/docs/books/common/fragment-router-install-steps.adoc
+++ b/docs/books/common/fragment-router-install-steps.adoc
@@ -21,7 +21,7 @@ under the License
** Download and build the {RouterName} source.
+
-To download the source, see {DispatchRouterDownloadLink}. For instructions on
building the source, see the {QpidDispatchReadmeLink}.
+To download the source, see the {DispatchRouterDownloadLink}. For instructions
on building the source, see the {QpidDispatchReadmeLink}.
** Install the {RouterName} packages.
+
Packages are available for `yum`/`dnf`-based Linux distributions. For more
information, see the {DispatchRouterPackagesLink}.
diff --git
a/docs/books/modules/user-guide/connecting-routers-external-amqp-containers.adoc
b/docs/books/modules/user-guide/connecting-routers-external-amqp-containers.adoc
index 0fb7516..4ef8b49 100644
---
a/docs/books/modules/user-guide/connecting-routers-external-amqp-containers.adoc
+++
b/docs/books/modules/user-guide/connecting-routers-external-amqp-containers.adoc
@@ -55,3 +55,9 @@ connector {
`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.
--
+
+.Additional resources
+
+* After enabling a router to connect to an external AMQP container, configure
any necessary security credentials.
++
+For more information, see xref:securing-outgoing-connections-{context}[].
diff --git a/docs/books/modules/user-guide/connecting-routers.adoc
b/docs/books/modules/user-guide/connecting-routers.adoc
index daab148..79e55c9 100644
--- a/docs/books/modules/user-guide/connecting-routers.adoc
+++ b/docs/books/modules/user-guide/connecting-routers.adoc
@@ -87,3 +87,9 @@ listener {
. 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.
+
+.Additional resources
+
+* After connecting a router to another router, secure the connection.
++
+For more information, see
xref:securing-connections-between-routers-{context}[].
diff --git a/docs/books/modules/user-guide/listening-client-connections.adoc
b/docs/books/modules/user-guide/listening-client-connections.adoc
index a35bff6..85facdb 100644
--- a/docs/books/modules/user-guide/listening-client-connections.adoc
+++ b/docs/books/modules/user-guide/listening-client-connections.adoc
@@ -57,5 +57,11 @@ listener {
+
`[(amqp|amqps|ws|wss)://](__HOST__|__IP ADDRESS__)[:port]`
+
-For more information, see xref:connection-failover-{context}[].
+For more information, see xref:understanding-connection-failover-{context}[].
--
+
+.Additional resources
+
+* After enabling a router to listen for client connections, secure the
connection.
++
+For more information, see
xref:securing-incoming-client-connections-{context}[].
diff --git a/docs/books/modules/user-guide/next-steps.adoc
b/docs/books/modules/user-guide/next-steps.adoc
index 4b340e1..da96103 100644
--- a/docs/books/modules/user-guide/next-steps.adoc
+++ b/docs/books/modules/user-guide/next-steps.adoc
@@ -24,18 +24,13 @@ under the License
[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 a router network topology and
route messages.
-
-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.
-+
---
-* 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.
---
-+
-For more information, see xref:routing[].
+After using {RouterName} to distribute messages between two clients, you can
use the following sections to learn more about {RouterName} configuration,
deployment, and management.
+
+xref:configuring-router-{context}[Configure non-default settings for the
router]::
+{RouterName} ships with default settings that are suitable for many basic use
cases. You can configure the router's essential properties, network
connections, security settings, logging, and routing mechanisms.
+
+xref:creating-router-network-topology-{context}[Plan a {RouterName}
deployment]::
+{RouterName} is typically deployed in router networks. You can design a router
network of any arbitrary topology to interconnect the endpoints in your
messaging network.
+
+xref:monitoring-managing-router-network[Monitor and manage {RouterName}]::
+You can use the web console and command-line management tools to monitor the
status and performance of the routers in your router network.
diff --git
a/docs/books/modules/user-guide/router-connection-considerations.adoc
b/docs/books/modules/user-guide/router-connection-guidelines.adoc
similarity index 96%
rename from docs/books/modules/user-guide/router-connection-considerations.adoc
rename to docs/books/modules/user-guide/router-connection-guidelines.adoc
index 9902951..00af0e2 100644
--- a/docs/books/modules/user-guide/router-connection-considerations.adoc
+++ b/docs/books/modules/user-guide/router-connection-guidelines.adoc
@@ -19,10 +19,10 @@ under the License
// Module included in the following assemblies:
//
-// planning-router-network.adoc
+// router-deployment-guidelines.adoc
-[id='router-connection-considerations-{context}']
-= Router connection considerations
+[id='router-connection-guidelines-{context}']
+= Router connection guidelines
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.
diff --git a/docs/books/modules/user-guide/adding-routers-router-network.adoc
b/docs/books/modules/user-guide/router-deployment-workflow.adoc
similarity index 87%
rename from docs/books/modules/user-guide/adding-routers-router-network.adoc
rename to docs/books/modules/user-guide/router-deployment-workflow.adoc
index bd6c2c9..e639510 100644
--- a/docs/books/modules/user-guide/adding-routers-router-network.adoc
+++ b/docs/books/modules/user-guide/router-deployment-workflow.adoc
@@ -21,12 +21,10 @@ under the License
//
// creating-router-network-topology.adoc
-[id='adding-routers-router-network-{context}']
-= Adding routers to the router network
+[id='router-deployment-workflow-{context}']
+= {RouterName} deployment workflow
-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.
+This workflow describes the basic workflow for deploying a {RouterName}
router. To create a router network, complete this workflow for each router in
the network.
.Prerequisites
@@ -66,4 +64,6 @@ If necessary, configure policies to control which messaging
resources clients ar
+
You can set the default logging configuration to ensure that events are logged
at the correct level for your environment.
-. Start the router.
+. xref:starting-router-{context}[Start the router].
+
+. Repeat this workflow for each additional router that you want to add to the
router network.
diff --git
a/docs/books/modules/user-guide/router-network-security-considerations.adoc
b/docs/books/modules/user-guide/security-guidelines.adoc
similarity index 92%
rename from
docs/books/modules/user-guide/router-network-security-considerations.adoc
rename to docs/books/modules/user-guide/security-guidelines.adoc
index 5ec9ba2..673e704 100644
--- a/docs/books/modules/user-guide/router-network-security-considerations.adoc
+++ b/docs/books/modules/user-guide/security-guidelines.adoc
@@ -17,12 +17,12 @@ specific language governing permissions and limitations
under the License
////
-// Module included in the following assemblies:
+// This module is included in the following assemblies:
//
-// planning-router-network.adoc
+// router-deployment-guidelines.adoc
-[id='router-network-security-considerations-{context}']
-= Router network security considerations
+[id='security-guidelines-{context}']
+= Security guidelines
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.
diff --git a/docs/books/modules/user-guide/connection-failover.adoc
b/docs/books/modules/user-guide/understanding-connection-failover.adoc
similarity index 96%
rename from docs/books/modules/user-guide/connection-failover.adoc
rename to docs/books/modules/user-guide/understanding-connection-failover.adoc
index 249359d..c3b08e3 100644
--- a/docs/books/modules/user-guide/connection-failover.adoc
+++ b/docs/books/modules/user-guide/understanding-connection-failover.adoc
@@ -20,8 +20,8 @@ under the License
// Module included in the following assemblies:
// configuring-network-connections.adoc
-[id='connection-failover-{context}']
-= Connection failover
+[id='understanding-connection-failover-{context}']
+= Understanding connection failover
If a connection between a router and a remote host fails, connection failover
enables the connection to be reestablished automatically on an alternate URL.
diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc
index 981d191..0a4d6c2 100644
--- a/docs/books/user-guide/book.adoc
+++ b/docs/books/user-guide/book.adoc
@@ -26,6 +26,9 @@ include::common/attributes.adoc[]
// Overview
include::assemblies/user-guide/overview.adoc[leveloffset=+1]
+// Installing
+include::modules/user-guide/installing-router.adoc[leveloffset=+1]
+
// Getting started
include::assemblies/user-guide/getting-started.adoc[leveloffset=+1]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
