You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by bh...@apache.org on 2019/12/09 19:07:25 UTC
[qpid-dispatch] branch master updated: Minor edits and improvements
to doc overview content. This closes #637.
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 <bh...@redhat.com>
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org