From ff960fae2cfc503b8d9658b62b778a9f6477ff8f Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Mon, 20 Aug 2018 12:41:32 -0400 Subject: [PATCH 1/9] Change doc dir structure for mod docs --- docs/books/{user-guide => common}/attributes.adoc | 0 .../{user-guide => }/images/01-peer-to-peer.png | Bin .../{user-guide => }/images/balanced-routing.png | Bin .../{user-guide => }/images/brokered-messaging.png | Bin .../{user-guide => }/images/closest-routing.png | Bin docs/books/{user-guide => }/images/console1.png | Bin .../{user-guide => }/images/console_charts.png | Bin .../{user-guide => }/images/console_entity.png | Bin .../books/{user-guide => }/images/console_login.png | Bin .../{user-guide => }/images/console_overview.png | Bin .../{user-guide => }/images/console_schema.png | Bin .../{user-guide => }/images/console_topology.png | Bin docs/books/{user-guide => }/images/link-routing.png | Bin .../{user-guide => }/images/message-routing.png | Bin .../{user-guide => }/images/multicast-routing.png | Bin .../{user-guide => }/images/path-redundancy-01.png | Bin .../{user-guide => }/images/path-redundancy-02.png | Bin .../images/path-redundancy-temp-decoupling-01.png | Bin .../images/path-redundancy-temp-decoupling-02.png | Bin .../{user-guide => }/images/sharded-queue-01.png | Bin .../{user-guide => }/images/sharded-queue-02.png | Bin docs/books/user-guide/book.adoc | 2 +- docs/books/user-guide/images | 1 + 23 files changed, 2 insertions(+), 1 deletion(-) rename docs/books/{user-guide => common}/attributes.adoc (100%) rename docs/books/{user-guide => }/images/01-peer-to-peer.png (100%) rename docs/books/{user-guide => }/images/balanced-routing.png (100%) rename docs/books/{user-guide => }/images/brokered-messaging.png (100%) rename docs/books/{user-guide => }/images/closest-routing.png (100%) rename docs/books/{user-guide => }/images/console1.png (100%) rename docs/books/{user-guide => }/images/console_charts.png (100%) rename docs/books/{user-guide => }/images/console_entity.png (100%) rename docs/books/{user-guide => }/images/console_login.png (100%) rename docs/books/{user-guide => }/images/console_overview.png (100%) rename docs/books/{user-guide => }/images/console_schema.png (100%) rename docs/books/{user-guide => }/images/console_topology.png (100%) rename docs/books/{user-guide => }/images/link-routing.png (100%) rename docs/books/{user-guide => }/images/message-routing.png (100%) rename docs/books/{user-guide => }/images/multicast-routing.png (100%) rename docs/books/{user-guide => }/images/path-redundancy-01.png (100%) rename docs/books/{user-guide => }/images/path-redundancy-02.png (100%) rename docs/books/{user-guide => }/images/path-redundancy-temp-decoupling-01.png (100%) rename docs/books/{user-guide => }/images/path-redundancy-temp-decoupling-02.png (100%) rename docs/books/{user-guide => }/images/sharded-queue-01.png (100%) rename docs/books/{user-guide => }/images/sharded-queue-02.png (100%) create mode 120000 docs/books/user-guide/images diff --git a/docs/books/user-guide/attributes.adoc b/docs/books/common/attributes.adoc similarity index 100% rename from docs/books/user-guide/attributes.adoc rename to docs/books/common/attributes.adoc diff --git a/docs/books/user-guide/images/01-peer-to-peer.png b/docs/books/images/01-peer-to-peer.png similarity index 100% rename from docs/books/user-guide/images/01-peer-to-peer.png rename to docs/books/images/01-peer-to-peer.png diff --git a/docs/books/user-guide/images/balanced-routing.png b/docs/books/images/balanced-routing.png similarity index 100% rename from docs/books/user-guide/images/balanced-routing.png rename to docs/books/images/balanced-routing.png diff --git a/docs/books/user-guide/images/brokered-messaging.png b/docs/books/images/brokered-messaging.png similarity index 100% rename from docs/books/user-guide/images/brokered-messaging.png rename to docs/books/images/brokered-messaging.png diff --git a/docs/books/user-guide/images/closest-routing.png b/docs/books/images/closest-routing.png similarity index 100% rename from docs/books/user-guide/images/closest-routing.png rename to docs/books/images/closest-routing.png diff --git a/docs/books/user-guide/images/console1.png b/docs/books/images/console1.png similarity index 100% rename from docs/books/user-guide/images/console1.png rename to docs/books/images/console1.png diff --git a/docs/books/user-guide/images/console_charts.png b/docs/books/images/console_charts.png similarity index 100% rename from docs/books/user-guide/images/console_charts.png rename to docs/books/images/console_charts.png diff --git a/docs/books/user-guide/images/console_entity.png b/docs/books/images/console_entity.png similarity index 100% rename from docs/books/user-guide/images/console_entity.png rename to docs/books/images/console_entity.png diff --git a/docs/books/user-guide/images/console_login.png b/docs/books/images/console_login.png similarity index 100% rename from docs/books/user-guide/images/console_login.png rename to docs/books/images/console_login.png diff --git a/docs/books/user-guide/images/console_overview.png b/docs/books/images/console_overview.png similarity index 100% rename from docs/books/user-guide/images/console_overview.png rename to docs/books/images/console_overview.png diff --git a/docs/books/user-guide/images/console_schema.png b/docs/books/images/console_schema.png similarity index 100% rename from docs/books/user-guide/images/console_schema.png rename to docs/books/images/console_schema.png diff --git a/docs/books/user-guide/images/console_topology.png b/docs/books/images/console_topology.png similarity index 100% rename from docs/books/user-guide/images/console_topology.png rename to docs/books/images/console_topology.png diff --git a/docs/books/user-guide/images/link-routing.png b/docs/books/images/link-routing.png similarity index 100% rename from docs/books/user-guide/images/link-routing.png rename to docs/books/images/link-routing.png diff --git a/docs/books/user-guide/images/message-routing.png b/docs/books/images/message-routing.png similarity index 100% rename from docs/books/user-guide/images/message-routing.png rename to docs/books/images/message-routing.png diff --git a/docs/books/user-guide/images/multicast-routing.png b/docs/books/images/multicast-routing.png similarity index 100% rename from docs/books/user-guide/images/multicast-routing.png rename to docs/books/images/multicast-routing.png diff --git a/docs/books/user-guide/images/path-redundancy-01.png b/docs/books/images/path-redundancy-01.png similarity index 100% rename from docs/books/user-guide/images/path-redundancy-01.png rename to docs/books/images/path-redundancy-01.png diff --git a/docs/books/user-guide/images/path-redundancy-02.png b/docs/books/images/path-redundancy-02.png similarity index 100% rename from docs/books/user-guide/images/path-redundancy-02.png rename to docs/books/images/path-redundancy-02.png diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png b/docs/books/images/path-redundancy-temp-decoupling-01.png similarity index 100% rename from docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png rename to docs/books/images/path-redundancy-temp-decoupling-01.png diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png b/docs/books/images/path-redundancy-temp-decoupling-02.png similarity index 100% rename from docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png rename to docs/books/images/path-redundancy-temp-decoupling-02.png diff --git a/docs/books/user-guide/images/sharded-queue-01.png b/docs/books/images/sharded-queue-01.png similarity index 100% rename from docs/books/user-guide/images/sharded-queue-01.png rename to docs/books/images/sharded-queue-01.png diff --git a/docs/books/user-guide/images/sharded-queue-02.png b/docs/books/images/sharded-queue-02.png similarity index 100% rename from docs/books/user-guide/images/sharded-queue-02.png rename to docs/books/images/sharded-queue-02.png diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index 4ed6bdf471..c13a914718 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -17,7 +17,7 @@ specific language governing permissions and limitations under the License //// -include::attributes.adoc[] +include::common/attributes.adoc[] = {RouterBook} diff --git a/docs/books/user-guide/images b/docs/books/user-guide/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/docs/books/user-guide/images @@ -0,0 +1 @@ +../images \ No newline at end of file From 4ec39e64c0c459c8ff43a1a81f30195fdab5e7f2 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Mon, 20 Aug 2018 12:54:01 -0400 Subject: [PATCH 2/9] Add underscore to common and images dirs --- docs/books/{common => _common}/attributes.adoc | 4 ++-- .../fragment-router-sasl-para.adoc | 0 .../fragment-starting-router-step.adoc | 0 docs/books/{images => _images}/01-peer-to-peer.png | Bin docs/books/{images => _images}/balanced-routing.png | Bin .../{images => _images}/brokered-messaging.png | Bin docs/books/{images => _images}/closest-routing.png | Bin docs/books/{images => _images}/console1.png | Bin docs/books/{images => _images}/console_charts.png | Bin docs/books/{images => _images}/console_entity.png | Bin docs/books/{images => _images}/console_login.png | Bin docs/books/{images => _images}/console_overview.png | Bin docs/books/{images => _images}/console_schema.png | Bin docs/books/{images => _images}/console_topology.png | Bin docs/books/{images => _images}/link-routing.png | Bin docs/books/{images => _images}/message-routing.png | Bin .../books/{images => _images}/multicast-routing.png | Bin .../{images => _images}/path-redundancy-01.png | Bin .../{images => _images}/path-redundancy-02.png | Bin .../path-redundancy-temp-decoupling-01.png | Bin .../path-redundancy-temp-decoupling-02.png | Bin docs/books/{images => _images}/sharded-queue-01.png | Bin docs/books/{images => _images}/sharded-queue-02.png | Bin docs/books/user-guide/_common | 1 + docs/books/user-guide/_images | 1 + docs/books/user-guide/book.adoc | 2 +- 26 files changed, 5 insertions(+), 3 deletions(-) rename docs/books/{common => _common}/attributes.adoc (98%) rename docs/books/{common => _common}/fragment-router-sasl-para.adoc (100%) rename docs/books/{common => _common}/fragment-starting-router-step.adoc (100%) rename docs/books/{images => _images}/01-peer-to-peer.png (100%) rename docs/books/{images => _images}/balanced-routing.png (100%) rename docs/books/{images => _images}/brokered-messaging.png (100%) rename docs/books/{images => _images}/closest-routing.png (100%) rename docs/books/{images => _images}/console1.png (100%) rename docs/books/{images => _images}/console_charts.png (100%) rename docs/books/{images => _images}/console_entity.png (100%) rename docs/books/{images => _images}/console_login.png (100%) rename docs/books/{images => _images}/console_overview.png (100%) rename docs/books/{images => _images}/console_schema.png (100%) rename docs/books/{images => _images}/console_topology.png (100%) rename docs/books/{images => _images}/link-routing.png (100%) rename docs/books/{images => _images}/message-routing.png (100%) rename docs/books/{images => _images}/multicast-routing.png (100%) rename docs/books/{images => _images}/path-redundancy-01.png (100%) rename docs/books/{images => _images}/path-redundancy-02.png (100%) rename docs/books/{images => _images}/path-redundancy-temp-decoupling-01.png (100%) rename docs/books/{images => _images}/path-redundancy-temp-decoupling-02.png (100%) rename docs/books/{images => _images}/sharded-queue-01.png (100%) rename docs/books/{images => _images}/sharded-queue-02.png (100%) create mode 120000 docs/books/user-guide/_common create mode 120000 docs/books/user-guide/_images diff --git a/docs/books/common/attributes.adoc b/docs/books/_common/attributes.adoc similarity index 98% rename from docs/books/common/attributes.adoc rename to docs/books/_common/attributes.adoc index 01627105c6..d150292dd8 100644 --- a/docs/books/common/attributes.adoc +++ b/docs/books/_common/attributes.adoc @@ -23,7 +23,7 @@ under the License :doctype: article :experimental: :idprefix: -:imagesdir: images +:imagesdir: _images :numbered: :sectanchors!: :sectnums: @@ -39,7 +39,7 @@ under the License :RouterLongName: {ProductName} Dispatch Router :ClientAmqpPythonName: {ProductName} Proton Python :ConsoleName: {RouterLongName} Console -:FragmentDir: common +:FragmentDir: _common :RouterName: Dispatch Router :RouterSchemaDir: ../../build/doc/book :DispatchRouterVersion: 1.0.1 diff --git a/docs/books/common/fragment-router-sasl-para.adoc b/docs/books/_common/fragment-router-sasl-para.adoc similarity index 100% rename from docs/books/common/fragment-router-sasl-para.adoc rename to docs/books/_common/fragment-router-sasl-para.adoc diff --git a/docs/books/common/fragment-starting-router-step.adoc b/docs/books/_common/fragment-starting-router-step.adoc similarity index 100% rename from docs/books/common/fragment-starting-router-step.adoc rename to docs/books/_common/fragment-starting-router-step.adoc diff --git a/docs/books/images/01-peer-to-peer.png b/docs/books/_images/01-peer-to-peer.png similarity index 100% rename from docs/books/images/01-peer-to-peer.png rename to docs/books/_images/01-peer-to-peer.png diff --git a/docs/books/images/balanced-routing.png b/docs/books/_images/balanced-routing.png similarity index 100% rename from docs/books/images/balanced-routing.png rename to docs/books/_images/balanced-routing.png diff --git a/docs/books/images/brokered-messaging.png b/docs/books/_images/brokered-messaging.png similarity index 100% rename from docs/books/images/brokered-messaging.png rename to docs/books/_images/brokered-messaging.png diff --git a/docs/books/images/closest-routing.png b/docs/books/_images/closest-routing.png similarity index 100% rename from docs/books/images/closest-routing.png rename to docs/books/_images/closest-routing.png diff --git a/docs/books/images/console1.png b/docs/books/_images/console1.png similarity index 100% rename from docs/books/images/console1.png rename to docs/books/_images/console1.png diff --git a/docs/books/images/console_charts.png b/docs/books/_images/console_charts.png similarity index 100% rename from docs/books/images/console_charts.png rename to docs/books/_images/console_charts.png diff --git a/docs/books/images/console_entity.png b/docs/books/_images/console_entity.png similarity index 100% rename from docs/books/images/console_entity.png rename to docs/books/_images/console_entity.png diff --git a/docs/books/images/console_login.png b/docs/books/_images/console_login.png similarity index 100% rename from docs/books/images/console_login.png rename to docs/books/_images/console_login.png diff --git a/docs/books/images/console_overview.png b/docs/books/_images/console_overview.png similarity index 100% rename from docs/books/images/console_overview.png rename to docs/books/_images/console_overview.png diff --git a/docs/books/images/console_schema.png b/docs/books/_images/console_schema.png similarity index 100% rename from docs/books/images/console_schema.png rename to docs/books/_images/console_schema.png diff --git a/docs/books/images/console_topology.png b/docs/books/_images/console_topology.png similarity index 100% rename from docs/books/images/console_topology.png rename to docs/books/_images/console_topology.png diff --git a/docs/books/images/link-routing.png b/docs/books/_images/link-routing.png similarity index 100% rename from docs/books/images/link-routing.png rename to docs/books/_images/link-routing.png diff --git a/docs/books/images/message-routing.png b/docs/books/_images/message-routing.png similarity index 100% rename from docs/books/images/message-routing.png rename to docs/books/_images/message-routing.png diff --git a/docs/books/images/multicast-routing.png b/docs/books/_images/multicast-routing.png similarity index 100% rename from docs/books/images/multicast-routing.png rename to docs/books/_images/multicast-routing.png diff --git a/docs/books/images/path-redundancy-01.png b/docs/books/_images/path-redundancy-01.png similarity index 100% rename from docs/books/images/path-redundancy-01.png rename to docs/books/_images/path-redundancy-01.png diff --git a/docs/books/images/path-redundancy-02.png b/docs/books/_images/path-redundancy-02.png similarity index 100% rename from docs/books/images/path-redundancy-02.png rename to docs/books/_images/path-redundancy-02.png diff --git a/docs/books/images/path-redundancy-temp-decoupling-01.png b/docs/books/_images/path-redundancy-temp-decoupling-01.png similarity index 100% rename from docs/books/images/path-redundancy-temp-decoupling-01.png rename to docs/books/_images/path-redundancy-temp-decoupling-01.png diff --git a/docs/books/images/path-redundancy-temp-decoupling-02.png b/docs/books/_images/path-redundancy-temp-decoupling-02.png similarity index 100% rename from docs/books/images/path-redundancy-temp-decoupling-02.png rename to docs/books/_images/path-redundancy-temp-decoupling-02.png diff --git a/docs/books/images/sharded-queue-01.png b/docs/books/_images/sharded-queue-01.png similarity index 100% rename from docs/books/images/sharded-queue-01.png rename to docs/books/_images/sharded-queue-01.png diff --git a/docs/books/images/sharded-queue-02.png b/docs/books/_images/sharded-queue-02.png similarity index 100% rename from docs/books/images/sharded-queue-02.png rename to docs/books/_images/sharded-queue-02.png diff --git a/docs/books/user-guide/_common b/docs/books/user-guide/_common new file mode 120000 index 0000000000..7c77149902 --- /dev/null +++ b/docs/books/user-guide/_common @@ -0,0 +1 @@ +../_common \ No newline at end of file diff --git a/docs/books/user-guide/_images b/docs/books/user-guide/_images new file mode 120000 index 0000000000..6d8b580705 --- /dev/null +++ b/docs/books/user-guide/_images @@ -0,0 +1 @@ +../_images \ No newline at end of file diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index c13a914718..67c5707b31 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -17,7 +17,7 @@ specific language governing permissions and limitations under the License //// -include::common/attributes.adoc[] +include::_common/attributes.adoc[] = {RouterBook} From 7f2b0bb413a48a6f252879a90f4209c325cb6bf9 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Mon, 20 Aug 2018 12:55:40 -0400 Subject: [PATCH 3/9] Remove old symlinks --- docs/books/user-guide/common | 1 - docs/books/user-guide/images | 1 - 2 files changed, 2 deletions(-) delete mode 120000 docs/books/user-guide/common delete mode 120000 docs/books/user-guide/images diff --git a/docs/books/user-guide/common b/docs/books/user-guide/common deleted file mode 120000 index 60d3b0a6a8..0000000000 --- a/docs/books/user-guide/common +++ /dev/null @@ -1 +0,0 @@ -../common \ No newline at end of file diff --git a/docs/books/user-guide/images b/docs/books/user-guide/images deleted file mode 120000 index 5e67573196..0000000000 --- a/docs/books/user-guide/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file From f56845a0a8e022ad8b5e8b108fd09dbcfe7e931b Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Fri, 24 Aug 2018 16:28:10 -0400 Subject: [PATCH 4/9] Create dirs for modules and assemblies, create overview assembly, create modules for overview --- docs/books/_common/document_conventions.adoc | 27 +++++++ docs/books/user-guide/assemblies/common | 1 + .../assemblies/important-terms-concepts.adoc | 48 +++++++++++ docs/books/user-guide/assemblies/modules | 1 + .../books/user-guide/assemblies/overview.adoc | 42 ++++++++++ docs/books/user-guide/assemblies/routing.adoc | 38 +++++++++ docs/books/user-guide/book.adoc | 2 + .../user-guide/modules/key-features.adoc | 32 ++++++++ .../user-guide/modules/link-routing.adoc | 43 ++++++++++ .../user-guide/modules/message-routing.adoc | 80 +++++++++++++++++++ .../user-guide/modules/overview-of-amqp.adoc | 35 ++++++++ .../user-guide/modules/router-addresses.adoc | 52 ++++++++++++ .../user-guide/modules/router-management.adoc | 0 .../modules/router-network-connections.adoc | 52 ++++++++++++ .../user-guide/modules/router-security.adoc | 0 .../supported-standards-protocols.adoc | 39 +++++++++ .../user-guide/modules/what-routers-are.adoc | 47 +++++++++++ 17 files changed, 539 insertions(+) create mode 100644 docs/books/_common/document_conventions.adoc create mode 120000 docs/books/user-guide/assemblies/common create mode 100644 docs/books/user-guide/assemblies/important-terms-concepts.adoc create mode 120000 docs/books/user-guide/assemblies/modules create mode 100644 docs/books/user-guide/assemblies/overview.adoc create mode 100644 docs/books/user-guide/assemblies/routing.adoc create mode 100644 docs/books/user-guide/modules/key-features.adoc create mode 100644 docs/books/user-guide/modules/link-routing.adoc create mode 100644 docs/books/user-guide/modules/message-routing.adoc create mode 100644 docs/books/user-guide/modules/overview-of-amqp.adoc create mode 100644 docs/books/user-guide/modules/router-addresses.adoc create mode 100644 docs/books/user-guide/modules/router-management.adoc create mode 100644 docs/books/user-guide/modules/router-network-connections.adoc create mode 100644 docs/books/user-guide/modules/router-security.adoc create mode 100644 docs/books/user-guide/modules/supported-standards-protocols.adoc create mode 100644 docs/books/user-guide/modules/what-routers-are.adoc diff --git a/docs/books/_common/document_conventions.adoc b/docs/books/_common/document_conventions.adoc new file mode 100644 index 0000000000..7762cb9a10 --- /dev/null +++ b/docs/books/_common/document_conventions.adoc @@ -0,0 +1,27 @@ +//// +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: +// +// overview.adoc + +[id='document-conventions-{context}'] += Document conventions + +In this document, `sudo` is used for any command that requires root privileges. You should always exercise caution when using `sudo`, as any changes can affect the entire system. diff --git a/docs/books/user-guide/assemblies/common b/docs/books/user-guide/assemblies/common new file mode 120000 index 0000000000..739f5166be --- /dev/null +++ b/docs/books/user-guide/assemblies/common @@ -0,0 +1 @@ +../../_common \ No newline at end of file diff --git a/docs/books/user-guide/assemblies/important-terms-concepts.adoc b/docs/books/user-guide/assemblies/important-terms-concepts.adoc new file mode 100644 index 0000000000..22b770702a --- /dev/null +++ b/docs/books/user-guide/assemblies/important-terms-concepts.adoc @@ -0,0 +1,48 @@ +//// +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: +// +// overview.adoc + +ifdef::context[:parent-context: {context}] + +[id='important-terms-concepts-{context}'] += Important terms and concepts +:context: overview-terms-concepts + +Before using {RouterName}, you should be familiar with AMQP and understand some key concepts about {RouterName}. + +include::modules/overview-of-amqp.adoc[leveloffset=+1] + +include::modules/what-routers-are.adoc[leveloffset=+1] + +include::modules/router-network-connections.adoc[leveloffset=+1] + +include::modules/router-addresses.adoc[leveloffset=+1] + +include::modules/router-routing.adoc[leveloffset=+1] + +include::modules/router-security.adoc[leveloffset=+1] + +include::modules/router-management.adoc[leveloffset=+1] + +// Restore the context to what it was before this assembly. +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/assemblies/modules b/docs/books/user-guide/assemblies/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/docs/books/user-guide/assemblies/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/docs/books/user-guide/assemblies/overview.adoc b/docs/books/user-guide/assemblies/overview.adoc new file mode 100644 index 0000000000..0565d3ab9b --- /dev/null +++ b/docs/books/user-guide/assemblies/overview.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 +//// + +// This assembly is included in the following assemblies: +// +// book.adoc + +ifdef::context[:parent-context: {context}] + +[id='overview-{context}'] += Overview +:context: product-overview + +{RouterName} is a lightweight AMQP message router for building scalable, available, and performant messaging networks. + +include::modules/key-features.adoc[leveloffset=+1] + +include::modules/supported-standards-protocols.adoc[leveloffset=+1] + +include::important-terms-concepts.adoc[leveloffset=+1] + +include::_common/document_conventions.adoc[leveloffset=+1] + +// Restore the context to what it was before this assembly. +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/assemblies/routing.adoc b/docs/books/user-guide/assemblies/routing.adoc new file mode 100644 index 0000000000..a3a6965da9 --- /dev/null +++ b/docs/books/user-guide/assemblies/routing.adoc @@ -0,0 +1,38 @@ +//// +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: +// +// important-terms-concepts.adoc + +ifdef::context[:parent-context: {context}] + +[id='router-routing-{context}'] += Routing +:context: terms-concepts-routing + +In a router network, _routing_ is the process by which messages are delivered to their destinations. To accomplish this, {RouterName} offers two different routing mechanisms: _message routing_, which enables you to route messages based on anycast and multicast routing patterns, and _link routing_, which enables you to establish a dedicated, virtual path between a sender and receiver. + +include::modules/message-routing.adoc[leveloffset=+1] + +include::modules/link-routing.adoc[leveloffset=+1] + +// Restore the context to what it was before this assembly. +ifdef::parent-context[:context: {parent-context}] +ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index 67c5707b31..e314150e52 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -21,6 +21,8 @@ include::_common/attributes.adoc[] = {RouterBook} +include::assemblies/overview.adoc[leveloffset=+1] + // Introduction include::introduction.adoc[leveloffset=+1] diff --git a/docs/books/user-guide/modules/key-features.adoc b/docs/books/user-guide/modules/key-features.adoc new file mode 100644 index 0000000000..808e910afa --- /dev/null +++ b/docs/books/user-guide/modules/key-features.adoc @@ -0,0 +1,32 @@ +//// +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: +// +// overview.adoc + +[id='key-features-{context}'] += Key features + +You can use {RouterName} to flexibly route messages between any AMQP-enabled endpoints, including clients, servers, and message brokers. {RouterName} provides the following benefits: + +* Connects clients and message brokers into an internet-scale messaging network with uniform addressing +* Supports high-performance direct messaging +* Uses redundant network paths to route around failures +* Streamlines the management of large deployments diff --git a/docs/books/user-guide/modules/link-routing.adoc b/docs/books/user-guide/modules/link-routing.adoc new file mode 100644 index 0000000000..d7fae9f665 --- /dev/null +++ b/docs/books/user-guide/modules/link-routing.adoc @@ -0,0 +1,43 @@ +//// +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: +// +// routing.adoc + +[id='link-routing-{context}'] += Link routing + +Link routing enables you to establish a dedicated, virtual "path" between a sender and receiver that travels through the router network. Link routes are typically used to connect clients to message brokers in scenarios in which a direct connection is unfeasible. Therefore, link routes enable messaging capabilities that are not possible with message routing, such as: + +* Transactional messaging ++ +Link routing supports local transactions to a single broker. Distributed transactions are not supported. + +* Guaranteed message delivery order ++ +Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance. + +* End-to-end flow control ++ +Flow control is "real" in that credits flow across the link route from the receiver to the sender. + +* Server-side selectors ++ +With a link route, consumers can provide server-side selectors for broker subscriptions. \ No newline at end of file diff --git a/docs/books/user-guide/modules/message-routing.adoc b/docs/books/user-guide/modules/message-routing.adoc new file mode 100644 index 0000000000..4728b989a5 --- /dev/null +++ b/docs/books/user-guide/modules/message-routing.adoc @@ -0,0 +1,80 @@ +//// +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: +// +// routing.adoc + +[id='message-routing-{context}'] += Message routing + +Message routing enables you to distribute messages in anycast and multicast patterns. These patterns can be used for both direct routing, in which the router distributes messages between clients without a message broker, and indirect routing, in which the router enables clients to exchange messages through a message broker. + +With message routing, messages are routed based on their _addresses_, and the _routing pattern_ defined for the address. + +[discrete] +== Addresses + +An _address_ is the name of a message source or destination endpoint in the messaging network. AMQP addresses control the flow of messages across the router network. + +Addresses can designate various types of entities in a messaging network, such as: + +* Endpoint processes that consume data or offer a service +* Topics that match multiple consumers to multiple producers +* Entities within a message broker: +** Queues +** Durable Topics +** Exchanges + +When a router receives a message, it uses the message’s address to determine where to send the message (either its destination or one step closer to its destination). + +[NOTE] +==== +{RouterName} treats addresses as opaque strings. Therefore, when creating addresses, you can use whatever syntax makes the most sense for your environment. +==== + +[discrete] +== Routing patterns + +Routing patterns define the paths that a message with a mobile address can take across a network. These routing patterns can be used for both direct routing, in which the router distributes messages between clients without a broker, and indirect routing, in which the router enables clients to exchange messages through a broker. + +Note that the routing patterns fall into two categories: Anycast (Balanced and Closest) and Multicast. There is no concept of "unicast" in which there is only one consumer for an address. + +Anycast distribution delivers each message to one consumer whereas multicast distribution delivers each message to all consumers. + +Anycast delivery is reliable 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: + +The delivery shall be settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer. + +The delivery shall be settled with RELEASED disposition, meaning that the message was not delivered to any consumer. + +The delivery shall be settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent. + +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 delivery is not reliable. If a producer sends an unsettled delivery, the ingress router shall settle the delivery with ACCEPTED disposition regardless of whether the message was delivered to any consumers. + +Balanced +An anycast method which allows multiple receivers to use the same address. In this case, messages (or links) are routed to exactly one of the receivers and the network attempts to balance the traffic load across the set of receivers using the same address. This routing delivers messages to receivers based on how quickly they settle the deliveries. Faster receivers get more messages. + +Closest +An anycast method in which even if there are more receivers for the same address, every message is sent along the shortest path to reach the destination. This means that only one receiver will get the message. Each message is delivered to the closest receivers in terms of topology cost. If there are multiple receivers with the same lowest cost, deliveries will be spread evenly among those receivers. + +Multicast +Having multiple consumers on the same address at the same time, messages are routed such that each consumer receives one copy of the message. diff --git a/docs/books/user-guide/modules/overview-of-amqp.adoc b/docs/books/user-guide/modules/overview-of-amqp.adoc new file mode 100644 index 0000000000..9e4b0aa4a4 --- /dev/null +++ b/docs/books/user-guide/modules/overview-of-amqp.adoc @@ -0,0 +1,35 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='overview-of-amqp-{context}'] += Overview of AMQP + +{RouterName} implements version 1.0 of the Advanced Message Queueing Protocol (AMQP) specification. Therefore, you should understand several key AMQP terms and concepts before deploying or configuring {RouterName}. + +AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. Containers contain addressable entities (such as queues) called _nodes_. Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages. Links are established over _sessions_, which are contexts for sending and receiving messages. Sessions are established within a _connection_, which is a channel for communication between containers. + +.Additional resources + +* link:http://www.amqp.org/resources/download[OASIS AMQP 1.0 Specification] +* link:https://dzone.com/refcardz/amqp-essentials?chapter=1[AMQP Essentials Refcard] +* link:https://channel9.msdn.com/Blogs/Subscribe[Video series introducing AMQP 1.0] diff --git a/docs/books/user-guide/modules/router-addresses.adoc b/docs/books/user-guide/modules/router-addresses.adoc new file mode 100644 index 0000000000..261525516b --- /dev/null +++ b/docs/books/user-guide/modules/router-addresses.adoc @@ -0,0 +1,52 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='router-addresses-{context}'] += Addresses + +An _address_ is the name of a message source or destination endpoint in the messaging network. AMQP addresses control the flow of messages across the router network. + +Addresses can designate various types of entities in a messaging network, such as: + +* Endpoint processes that consume data or offer a service +* Topics that match multiple consumers to multiple producers +* Entities within a message broker: +** Queues +** Durable Topics +** Exchanges + +{RouterName} treats addresses as opaque strings. Therefore, when creating addresses, you can use whatever syntax makes the most sense for your environment. + +[discrete] +== Mobile addresses +Mobile addresses are rendezvous points between senders and receivers. The router aggregates and serializes messages from senders and distributes messages to receivers. + +Routers consider addresses to be mobile such that any users of an address may be directly connected to any router in a network and may move around the topology. In cases where messages are broadcast to or balanced across multiple consumers, the users of the address may be connected to multiple routers in the network. + +Mobile addresses may be discovered during normal router operation or manually configured. + +[discrete] +== Link route addresses +A link route address is a type of configured address that designates a queue, topic, or service on an external container such as a message broker. For link route addresses, {RouterName} propagates a separate link attachment to the broker resource for each incoming client link. The router does not automatically create any links to the broker resource. + +In addition, with link route addresses, the router network does not participate in aggregated message distribution. The router simply passes message delivery and settlement between the two end points. diff --git a/docs/books/user-guide/modules/router-management.adoc b/docs/books/user-guide/modules/router-management.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/books/user-guide/modules/router-network-connections.adoc b/docs/books/user-guide/modules/router-network-connections.adoc new file mode 100644 index 0000000000..07d7cb9023 --- /dev/null +++ b/docs/books/user-guide/modules/router-network-connections.adoc @@ -0,0 +1,52 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='router-network-connections-{context}'] += Network connections + +{RouterName} connects clients, servers, AMQP services, and other routers through network connections. Routers use _listeners_ to accept incoming connections, and _connectors_ to establish outgoing connections. + +The following table describes how routers connect to clients, other routers, and message brokers: + +[cols="30,70",options="header"] +|=== +| To connect to... | The router uses... + +| Clients +| _Normal_ listeners and connectors. + +Clients can connect to a router using the same methods they would use to connect to a message broker. From the client's perspective, the connection to the router and link establishment are identical to a broker connection and link establishment. + +Routers can also connect to clients for normal message delivery. In this type of connection, the router initiates the connection, but does not create any links. Links are only created by the peer that accepts the connection. + +| Routers +| _Inter-router_ listeners and connectors. + +Inter-router discovery and routing protocols are enabled over these types of connections. + +| Message brokers +| _Route-container_ listeners and connectors. + +A router can accept connections from message brokers or any resource that hosts known AMQP addresses. Routers can also connect to these types of resources. + +|=== diff --git a/docs/books/user-guide/modules/router-security.adoc b/docs/books/user-guide/modules/router-security.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/books/user-guide/modules/supported-standards-protocols.adoc b/docs/books/user-guide/modules/supported-standards-protocols.adoc new file mode 100644 index 0000000000..35ee3c4f41 --- /dev/null +++ b/docs/books/user-guide/modules/supported-standards-protocols.adoc @@ -0,0 +1,39 @@ +//// +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: +// +// overview.adoc + +[id='supported-standards-protocols-{context}'] += Supported standards and protocols + +{RouterName} supports the following industry-recognized standards and network protocols: + +* Version 1.0 of the Advanced Message Queueing Protocol (AMQP) +* Modern TCP with IPv6 + +[NOTE] +==== +The details of distributed transactions (XA) within AMQP are not provided in the 1.0 version of the specification. AMQ Interconnect does not support XA transactions. +==== + +.Additional resources + +* link:http://www.amqp.org/resources/download[OASIS AMQP 1.0 Specification] diff --git a/docs/books/user-guide/modules/what-routers-are.adoc b/docs/books/user-guide/modules/what-routers-are.adoc new file mode 100644 index 0000000000..2e62673707 --- /dev/null +++ b/docs/books/user-guide/modules/what-routers-are.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: +// +// overview.adoc + +[id='what-routers-are-{context}'] += What routers are + +{RouterName} is an application layer program running as a normal user program or as a daemon. A running instance of {RouterName} is called a _router_. Routers transfer messages between producers and consumers, can be combined with other routers to form an interconnected _router network_, and enhance both _direct_ (brokerless) and _indirect_ (brokered) messaging patterns. + +Routers do not take responsibility for messages:: +Routers transfer messages between producers and consumers, but unlike message brokers, they do not take responsibility for messages. Instead, routers propagate message settlement and disposition across a network such that delivery guarantees are met. That is, the router network will deliver the message – possibly through several intermediate routers – and then route the consumer's acknowledgement of that message back across the same path. The responsibility for the message is transfered from the producer to the consumer as if they were directly connected. + +Routers are combined to form router networks:: +Routers are often deployed in topologies of multiple routers called a router network. Routers use link-state routing protocols and algorithms similar to the Open Shortest Path First (OSPF) and Intermediate System to Intermediate System (IS-IS) protocols to calculate the best path from every message source to every message destination, and to recover quickly from failures. A router network relies on redundant network paths to provide continued connectivity in case of system or network failure. + +Routers enhance both direct and indirect messaging patterns:: +A messaging client can make a single AMQP connection into a router network and, over that connection, exchange messages with one or more message brokers connected to any router in the network. At the same time, the client can exchange messages directly with other endpoints without involving a broker at all. ++ +.Enhancing the use of message brokers +==== +Routers can enhance a cluster of message brokers that provide a scalable, distributed work queue. + +The router network makes the broker cluster appear as a single queue, with producers publishing to a single address, and consumers subscribing to a single address. The router network can distribute work to any broker in the cluster, and collect work from any broker for any consumer. + +The routers improve the scalability of the broker cluster, because brokers can be added or removed from the cluster without affecting the clients. + +The routers also solve the common difficulty of "stuck messages". Without the router network, if a consumer is connected to a broker that does not have any messages (but other brokers in the cluster do have messages), you must either transfer the messages or leave them "stuck". The routers solve this issue, however, because all of the consumers are connected to all of the brokers through the router network. A message on any broker can be delivered to any of the consumers. +==== From db01b352e1852a31cad6e56ff73136bcb558da19 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Fri, 24 Aug 2018 16:36:21 -0400 Subject: [PATCH 5/9] Update to message routing module --- .../user-guide/modules/message-routing.adoc | 59 ++++++++++++++++++- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/docs/books/user-guide/modules/message-routing.adoc b/docs/books/user-guide/modules/message-routing.adoc index 4728b989a5..8cff8cbad6 100644 --- a/docs/books/user-guide/modules/message-routing.adoc +++ b/docs/books/user-guide/modules/message-routing.adoc @@ -54,9 +54,64 @@ When a router receives a message, it uses the message’s address to determine w Routing patterns define the paths that a message with a mobile address can take across a network. These routing patterns can be used for both direct routing, in which the router distributes messages between clients without a broker, and indirect routing, in which the router enables clients to exchange messages through a broker. -Note that the routing patterns fall into two categories: Anycast (Balanced and Closest) and Multicast. There is no concept of "unicast" in which there is only one consumer for an address. +{RouterName} supports the following routing patterns: + +Balanced:: An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network. ++ +-- +If multiple consumers are attached to the same address, each router determines which outbound path should receive a message by considering each path's current number of unsettled deliveries. This means that more messages will be delivered along paths where deliveries are settled at higher rates. + +[NOTE] +==== +{RouterName} neither measures nor uses message settlement time to determine which outbound path to use. +==== + +In this scenario, the messages are spread across both receivers regardless of path length: + +.Balanced Message Routing +image::balanced-routing.png[Balanced Message Routing, align="center"] +-- + +Closest:: An anycast method in which every message is sent along the shortest path to reach the destination, even if there are other consumers for the same address. ++ +{RouterName} determines the shortest path based on the topology cost to reach each of the consumers. If there are multiple consumers with the same lowest cost, messages will be spread evenly among those consumers. ++ +In this scenario, all messages sent by `Sender` will be delivered to `Receiver 1`: ++ +.Closest Message Routing +image::closest-routing.png[Closest Message Routing, align="center"] + +Multicast:: Messages are sent to all consumers attached to the address. Each consumer will receive one copy of the message. ++ +In this scenario, all messages are sent to all receivers: ++ +.Multicast Message Routing +image::multicast-routing.png[Multicast Message Routing, align="center"] + +[NOTE] +==== +{RouterName} does not provide a true "unicast" routing pattern in which there is only one consumer for an address. +==== + + + + + + + + + + + + + + + + + + + -Anycast distribution delivers each message to one consumer whereas multicast distribution delivers each message to all consumers. Anycast delivery is reliable 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: From 144906c64819267a189bbfa9d705bdfd8c17caa7 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Mon, 27 Aug 2018 17:01:53 -0400 Subject: [PATCH 6/9] Misc updates, add router security and routing modules --- .../user-guide/assemblies/{common => _common} | 0 .../assemblies/important-terms-concepts.adoc | 6 +- docs/books/user-guide/assemblies/routing.adoc | 38 -------- ...doc => how-routers-connect-endpoints.adoc} | 4 +- .../modules/how-routers-route-messages.adoc | 67 +++++++++++++ .../user-guide/modules/message-routing.adoc | 97 +++++++------------ .../user-guide/modules/overview-of-amqp.adoc | 6 +- .../user-guide/modules/router-addresses.adoc | 52 ---------- .../user-guide/modules/router-security.adoc | 37 +++++++ .../user-guide/modules/what-routers-are.adoc | 2 +- 10 files changed, 151 insertions(+), 158 deletions(-) rename docs/books/user-guide/assemblies/{common => _common} (100%) delete mode 100644 docs/books/user-guide/assemblies/routing.adoc rename docs/books/user-guide/modules/{router-network-connections.adoc => how-routers-connect-endpoints.adoc} (96%) create mode 100644 docs/books/user-guide/modules/how-routers-route-messages.adoc delete mode 100644 docs/books/user-guide/modules/router-addresses.adoc diff --git a/docs/books/user-guide/assemblies/common b/docs/books/user-guide/assemblies/_common similarity index 100% rename from docs/books/user-guide/assemblies/common rename to docs/books/user-guide/assemblies/_common diff --git a/docs/books/user-guide/assemblies/important-terms-concepts.adoc b/docs/books/user-guide/assemblies/important-terms-concepts.adoc index 22b770702a..2ff3b2e0a8 100644 --- a/docs/books/user-guide/assemblies/important-terms-concepts.adoc +++ b/docs/books/user-guide/assemblies/important-terms-concepts.adoc @@ -33,11 +33,9 @@ include::modules/overview-of-amqp.adoc[leveloffset=+1] include::modules/what-routers-are.adoc[leveloffset=+1] -include::modules/router-network-connections.adoc[leveloffset=+1] +// include::modules/how-routers-connect-endpoints.adoc[leveloffset=+1] -include::modules/router-addresses.adoc[leveloffset=+1] - -include::modules/router-routing.adoc[leveloffset=+1] +include::modules/how-routers-route-messages.adoc[leveloffset=+1] include::modules/router-security.adoc[leveloffset=+1] diff --git a/docs/books/user-guide/assemblies/routing.adoc b/docs/books/user-guide/assemblies/routing.adoc deleted file mode 100644 index a3a6965da9..0000000000 --- a/docs/books/user-guide/assemblies/routing.adoc +++ /dev/null @@ -1,38 +0,0 @@ -//// -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: -// -// important-terms-concepts.adoc - -ifdef::context[:parent-context: {context}] - -[id='router-routing-{context}'] -= Routing -:context: terms-concepts-routing - -In a router network, _routing_ is the process by which messages are delivered to their destinations. To accomplish this, {RouterName} offers two different routing mechanisms: _message routing_, which enables you to route messages based on anycast and multicast routing patterns, and _link routing_, which enables you to establish a dedicated, virtual path between a sender and receiver. - -include::modules/message-routing.adoc[leveloffset=+1] - -include::modules/link-routing.adoc[leveloffset=+1] - -// Restore the context to what it was before this assembly. -ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/modules/router-network-connections.adoc b/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc similarity index 96% rename from docs/books/user-guide/modules/router-network-connections.adoc rename to docs/books/user-guide/modules/how-routers-connect-endpoints.adoc index 07d7cb9023..eb7e117519 100644 --- a/docs/books/user-guide/modules/router-network-connections.adoc +++ b/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc @@ -21,8 +21,8 @@ under the License // // important-terms-concepts.adoc -[id='router-network-connections-{context}'] -= Network connections +[id='how-routers-connect-endpoints-{context}'] += How routers connect endpoints {RouterName} connects clients, servers, AMQP services, and other routers through network connections. Routers use _listeners_ to accept incoming connections, and _connectors_ to establish outgoing connections. diff --git a/docs/books/user-guide/modules/how-routers-route-messages.adoc b/docs/books/user-guide/modules/how-routers-route-messages.adoc new file mode 100644 index 0000000000..9936821457 --- /dev/null +++ b/docs/books/user-guide/modules/how-routers-route-messages.adoc @@ -0,0 +1,67 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='how-routers-route-messages-{context}'] += How routers route messages + +In a router network, _routing_ is the process by which messages are delivered to their destinations. To accomplish this, {RouterName} offers two different routing mechanisms: + +Message routing:: +Message routing enables you to distribute messages in anycast and multicast patterns. These patterns can be used for both direct routing, in which the router distributes messages between clients without a message broker, and indirect routing, in which the router enables clients to exchange messages through a message broker. ++ +Message routing is useful for the following types of requirements: ++ +-- +* Default, basic message routing ++ +{RouterName} automatically routes messages by default, so manual configuration is only required if you want routing behavior that is different than the default. + +* Message-based routing patterns ++ +Message routing supports both anycast and multicast routing patterns. You can load-balance individual messages across multiple consumers, and multicast (or fan-out) messages to multiple subscribers. + +* Sharding messages across multiple message brokers when message delivery order is not important ++ +Sharding messages from one producer might cause that producer’s messages to be received in a different order than the order in which they were sent. +-- + +Link routing:: +Link routing enables you to establish a dedicated, virtual "path" between a sender and receiver that travels through the router network. Link routes are typically used to connect clients to message brokers in scenarios in which a direct connection is unfeasible. Therefore, link routes enable messaging capabilities that are not possible with message routing, such as: ++ +-- +* Transactional messaging ++ +Link routing supports local transactions to a single broker. Distributed transactions are not supported. + +* Guaranteed message delivery order ++ +Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance. + +* End-to-end flow control ++ +Flow control is "real" in that credits flow across the link route from the receiver to the sender. + +* Server-side selectors ++ +With a link route, consumers can provide server-side selectors for broker subscriptions. +-- diff --git a/docs/books/user-guide/modules/message-routing.adoc b/docs/books/user-guide/modules/message-routing.adoc index 8cff8cbad6..6aa9df96bd 100644 --- a/docs/books/user-guide/modules/message-routing.adoc +++ b/docs/books/user-guide/modules/message-routing.adoc @@ -49,87 +49,64 @@ When a router receives a message, it uses the message’s address to determine w {RouterName} treats addresses as opaque strings. Therefore, when creating addresses, you can use whatever syntax makes the most sense for your environment. ==== +[discrete] +== What mobile addresses are + +Addresses used in message routing are sometimes called _mobile addresses_, because ... + [discrete] == Routing patterns Routing patterns define the paths that a message with a mobile address can take across a network. These routing patterns can be used for both direct routing, in which the router distributes messages between clients without a broker, and indirect routing, in which the router enables clients to exchange messages through a broker. -{RouterName} supports the following routing patterns: - -Balanced:: An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network. -+ --- -If multiple consumers are attached to the same address, each router determines which outbound path should receive a message by considering each path's current number of unsettled deliveries. This means that more messages will be delivered along paths where deliveries are settled at higher rates. +{RouterName} supports two categories of routing patterns: anycast and multicast. [NOTE] ==== -{RouterName} neither measures nor uses message settlement time to determine which outbound path to use. +{RouterName} does not provide a true "unicast" routing pattern in which there is only one consumer for an address. ==== -In this scenario, the messages are spread across both receivers regardless of path length: +[options="header"] +|=== +| Routing pattern | Description | Reliability -.Balanced Message Routing -image::balanced-routing.png[Balanced Message Routing, align="center"] --- +| Anycast +a| Each message is delivered to one consumer. There are two types of anycast methods: -Closest:: An anycast method in which every message is sent along the shortest path to reach the destination, even if there are other consumers for the same address. -+ -{RouterName} determines the shortest path based on the topology cost to reach each of the consumers. If there are multiple consumers with the same lowest cost, messages will be spread evenly among those consumers. +* Balanced + -In this scenario, all messages sent by `Sender` will be delivered to `Receiver 1`: -+ -.Closest Message Routing -image::closest-routing.png[Closest Message Routing, align="center"] +Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network. This method allows multiple consumers to use the same address. -Multicast:: Messages are sent to all consumers attached to the address. Each consumer will receive one copy of the message. -+ -In this scenario, all messages are sent to all receivers: +* Closest + -.Multicast Message Routing -image::multicast-routing.png[Multicast Message Routing, align="center"] - -[NOTE] -==== -{RouterName} does not provide a true "unicast" routing pattern in which there is only one consumer for an address. -==== - - - - +Each message is sent along the shortest path to reach the destination, even if there are other consumers for the same address. +| Reliable for unsettled message deliveries. +| Multicast +| Each message is delivered to all consumers. Each consumer will receive one copy of the message. +| Unreliable. If a producer sends an unsettled delivery, the router automatically settles the delivery with ACCEPTED disposition regardless of whether the message was delivered to any consumers. +|=== +[discrete] +== Quality of service for message deliveries +{RouterName} can deliver messages with any of the following levels of reliability: +* At most once +* At least once +* Exactly once +The level of reliability is negotiated between the client and router when the client establishes a link to the router. The router achieves this negotiated level of reliability by treating messages as either _pre-settled_ or _unsettled_. +Pre-settled:: +Sometimes called "fire and forget", the router settles the incoming and outgoing deliveries and propagates the settlement to the message’s destination. However, it does not guarantee delivery. - - - - - - - - -Anycast delivery is reliable 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: - -The delivery shall be settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer. - -The delivery shall be settled with RELEASED disposition, meaning that the message was not delivered to any consumer. - -The delivery shall be settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent. - -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 delivery is not reliable. If a producer sends an unsettled delivery, the ingress router shall settle the delivery with ACCEPTED disposition regardless of whether the message was delivered to any consumers. - -Balanced -An anycast method which allows multiple receivers to use the same address. In this case, messages (or links) are routed to exactly one of the receivers and the network attempts to balance the traffic load across the set of receivers using the same address. This routing delivers messages to receivers based on how quickly they settle the deliveries. Faster receivers get more messages. - -Closest -An anycast method in which even if there are more receivers for the same address, every message is sent along the shortest path to reach the destination. This means that only one receiver will get the message. Each message is delivered to the closest receivers in terms of topology cost. If there are multiple receivers with the same lowest cost, deliveries will be spread evenly among those receivers. - -Multicast -Having multiple consumers on the same address at the same time, messages are routed such that each consumer receives one copy of the message. +Unsettled:: +The router propagates the settlement between the producer and consumer, and guarantees one of the following outcomes: ++ +* The delivery is settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer. +* The delivery is settled with RELEASED disposition, meaning that the message was not delivered to any consumer. +* The delivery is settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent. +* The connection to the producer is dropped, signifying that all unsettled deliveries should now be considered in-doubt by the producer and re-sent. diff --git a/docs/books/user-guide/modules/overview-of-amqp.adoc b/docs/books/user-guide/modules/overview-of-amqp.adoc index 9e4b0aa4a4..b69f733ef8 100644 --- a/docs/books/user-guide/modules/overview-of-amqp.adoc +++ b/docs/books/user-guide/modules/overview-of-amqp.adoc @@ -26,7 +26,11 @@ under the License {RouterName} implements version 1.0 of the Advanced Message Queueing Protocol (AMQP) specification. Therefore, you should understand several key AMQP terms and concepts before deploying or configuring {RouterName}. -AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. Containers contain addressable entities (such as queues) called _nodes_. Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages. Links are established over _sessions_, which are contexts for sending and receiving messages. Sessions are established within a _connection_, which is a channel for communication between containers. +* AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. +* Containers contain addressable entities (such as queues) called _nodes_. +* Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages. +* Links are established over _sessions_, which are contexts for sending and receiving messages. +* Sessions are established within a _connection_, which is a channel for communication between containers. .Additional resources diff --git a/docs/books/user-guide/modules/router-addresses.adoc b/docs/books/user-guide/modules/router-addresses.adoc deleted file mode 100644 index 261525516b..0000000000 --- a/docs/books/user-guide/modules/router-addresses.adoc +++ /dev/null @@ -1,52 +0,0 @@ -//// -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: -// -// important-terms-concepts.adoc - -[id='router-addresses-{context}'] -= Addresses - -An _address_ is the name of a message source or destination endpoint in the messaging network. AMQP addresses control the flow of messages across the router network. - -Addresses can designate various types of entities in a messaging network, such as: - -* Endpoint processes that consume data or offer a service -* Topics that match multiple consumers to multiple producers -* Entities within a message broker: -** Queues -** Durable Topics -** Exchanges - -{RouterName} treats addresses as opaque strings. Therefore, when creating addresses, you can use whatever syntax makes the most sense for your environment. - -[discrete] -== Mobile addresses -Mobile addresses are rendezvous points between senders and receivers. The router aggregates and serializes messages from senders and distributes messages to receivers. - -Routers consider addresses to be mobile such that any users of an address may be directly connected to any router in a network and may move around the topology. In cases where messages are broadcast to or balanced across multiple consumers, the users of the address may be connected to multiple routers in the network. - -Mobile addresses may be discovered during normal router operation or manually configured. - -[discrete] -== Link route addresses -A link route address is a type of configured address that designates a queue, topic, or service on an external container such as a message broker. For link route addresses, {RouterName} propagates a separate link attachment to the broker resource for each incoming client link. The router does not automatically create any links to the broker resource. - -In addition, with link route addresses, the router network does not participate in aggregated message distribution. The router simply passes message delivery and settlement between the two end points. diff --git a/docs/books/user-guide/modules/router-security.adoc b/docs/books/user-guide/modules/router-security.adoc index e69de29bb2..f35887d256 100644 --- a/docs/books/user-guide/modules/router-security.adoc +++ b/docs/books/user-guide/modules/router-security.adoc @@ -0,0 +1,37 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='router-security-{context}'] += Router security + +{RouterName} provides authentication and authorization mechanisms so that you can control who can access the router network, and what they can do with the messaging resources. + +Authentication:: +{RouterName} supports both SSL/TLS and SASL for encrypting and authenticating remote peers. Using these mechanisms, you can secure the router network in the following ways: + +* Authenticate incoming connections from remote peers (such as clients and message brokers) +* Provide authentication credentials for outgoing connections to remote peers (such as clients and message brokers) +* Secure the inter-router connections between the routers in the router network + +Authorization:: +{RouterName} provides a `policy` mechanism that you can use to enforce user connection restrictions and AMQP resource access control. diff --git a/docs/books/user-guide/modules/what-routers-are.adoc b/docs/books/user-guide/modules/what-routers-are.adoc index 2e62673707..7c27413531 100644 --- a/docs/books/user-guide/modules/what-routers-are.adoc +++ b/docs/books/user-guide/modules/what-routers-are.adoc @@ -24,7 +24,7 @@ under the License [id='what-routers-are-{context}'] = What routers are -{RouterName} is an application layer program running as a normal user program or as a daemon. A running instance of {RouterName} is called a _router_. Routers transfer messages between producers and consumers, can be combined with other routers to form an interconnected _router network_, and enhance both _direct_ (brokerless) and _indirect_ (brokered) messaging patterns. +{RouterName} is an application layer program running as a normal user program or as a daemon. A running instance of {RouterName} is called a _router_. Routers do not take responsibility for messages:: Routers transfer messages between producers and consumers, but unlike message brokers, they do not take responsibility for messages. Instead, routers propagate message settlement and disposition across a network such that delivery guarantees are met. That is, the router network will deliver the message – possibly through several intermediate routers – and then route the consumer's acknowledgement of that message back across the same path. The responsibility for the message is transfered from the producer to the consumer as if they were directly connected. From dcfa76adf80d91bce75b4929e5e71f698ea19ec8 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Tue, 28 Aug 2018 11:43:44 -0400 Subject: [PATCH 7/9] Add module on router management, update amqp overview module --- .../user-guide/modules/overview-of-amqp.adoc | 19 +++++--- .../user-guide/modules/router-management.adoc | 43 +++++++++++++++++++ 2 files changed, 56 insertions(+), 6 deletions(-) diff --git a/docs/books/user-guide/modules/overview-of-amqp.adoc b/docs/books/user-guide/modules/overview-of-amqp.adoc index b69f733ef8..dcd2a12b61 100644 --- a/docs/books/user-guide/modules/overview-of-amqp.adoc +++ b/docs/books/user-guide/modules/overview-of-amqp.adoc @@ -26,14 +26,21 @@ under the License {RouterName} implements version 1.0 of the Advanced Message Queueing Protocol (AMQP) specification. Therefore, you should understand several key AMQP terms and concepts before deploying or configuring {RouterName}. -* AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. -* Containers contain addressable entities (such as queues) called _nodes_. -* Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages. -* Links are established over _sessions_, which are contexts for sending and receiving messages. -* Sessions are established within a _connection_, which is a channel for communication between containers. +Containers:: +AMQP is a wire-level messaging protocol for transferring messages between applications called _containers_. In AMQP, a container is any application that sends or receives messages, such as a client application or message broker. ++ +Containers connect to each other over _connections_, which are channels for communication. + +Nodes:: +Containers contain addressable entities called _nodes_ that are responsible for storing or delivering messages. For example, a queue on a message broker is a node. + +Links:: +Messages are transferred between connected containers over _links_. A link is a unidirectional route between nodes. Essentially, a link is a channel for sending or receiving messages. ++ +Links are established over _sesssions_, which are contexts for sending and receiving messages. Sessions are established over connections. .Additional resources * link:http://www.amqp.org/resources/download[OASIS AMQP 1.0 Specification] * link:https://dzone.com/refcardz/amqp-essentials?chapter=1[AMQP Essentials Refcard] -* link:https://channel9.msdn.com/Blogs/Subscribe[Video series introducing AMQP 1.0] +* link:https://channel9.msdn.com/Blogs/Subscribe/The-AMQP-10-Protocol-16-Overview[Video series introducing AMQP 1.0] diff --git a/docs/books/user-guide/modules/router-management.adoc b/docs/books/user-guide/modules/router-management.adoc index e69de29bb2..bd500efbe5 100644 --- a/docs/books/user-guide/modules/router-management.adoc +++ b/docs/books/user-guide/modules/router-management.adoc @@ -0,0 +1,43 @@ +//// +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: +// +// important-terms-concepts.adoc + +[id='router-management-{context}'] += Router management + +{RouterName} provides both graphical and CLI tools for monitoring and managing a router network. + +{RouterLongName} Console:: +A web console for monitoring the layout and health of the router network. + +qdstat:: +A command-line tool for monitoring the status of a router in the router network. Using this tool, you can view the following information about a router: + +* Incoming and outgoing connections +* Incoming and outgoing links +* Router network topology from the perspective of this router +* Addresses known to this router +* Link routes and autolinks +* Memory consumption information + +qdmanage:: +A command-line tool for viewing and updating the configuration of a router at runtime. From 252e172e1a27a69cfa6bb8b5edc012684b8b82b0 Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Mon, 8 Oct 2018 15:27:24 -0400 Subject: [PATCH 8/9] Add add'l resources and move theory of operation content to each applicable section --- docs/books/user-guide/book.adoc | 4 +- .../user-guide/configuration-connections.adoc | 34 ++++- .../user-guide/configuration-security.adoc | 2 + .../modules/how-routers-route-messages.adoc | 6 + .../user-guide/modules/router-management.adoc | 6 + .../user-guide/modules/router-security.adoc | 6 + docs/books/user-guide/routing.adoc | 140 +++++++++++++++++- 7 files changed, 191 insertions(+), 7 deletions(-) diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index e314150e52..971ad30f84 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -24,10 +24,10 @@ include::_common/attributes.adoc[] include::assemblies/overview.adoc[leveloffset=+1] // Introduction -include::introduction.adoc[leveloffset=+1] +// include::introduction.adoc[leveloffset=+1] // Theory of Operation -include::theory_of_operation.adoc[leveloffset=+1] +// include::theory_of_operation.adoc[leveloffset=+1] // Getting Started include::getting-started.adoc[leveloffset=+1] diff --git a/docs/books/user-guide/configuration-connections.adoc b/docs/books/user-guide/configuration-connections.adoc index 26e10a207d..5c244225bb 100644 --- a/docs/books/user-guide/configuration-connections.adoc +++ b/docs/books/user-guide/configuration-connections.adoc @@ -25,7 +25,21 @@ Connections define how the router communicates with clients, other routers, and [id='adding-incoming-connections'] == Listening for Incoming Connections -Listening for incoming connections involves setting the host and port on which the router should listen for traffic. +{RouterName} provides _listeners_ that accept client connections. +A client connecting to a router listener uses the +same methods that it would use to connect to a broker. From the +client's perspective, the router connection and link establishment are +identical to broker connection and link establishment. + +Several types of listeners are defined by their role. + +[options="header",cols="20,80"] +|=== +| Role | Description +| normal | The connection is used for AMQP clients using normal message delivery. +| inter-router | The connection is assumed to be to another router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections. +| route-container | The connection is a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the remote resource has created a connection. +|=== .Procedure @@ -56,7 +70,23 @@ If you have set up SSL/TLS or SASL in your environment, you can configure the ro [id='adding-outgoing-connections'] == Adding Outgoing Connections -Configuring outgoing connections involves setting the host and port on which the router connects to other routers and brokers. +You can configure {RouterName} to create outbound connections to +messaging brokers or other AMQP entities using _connectors_. A +connector is defined with the network address of the broker and the +name or names of the resources that are available in that broker. When +a router connects to a broker through a connector, it uses the same +methods a normal messaging client would use when connecting to the +broker. + +Several types of connectors are defined by their role. + +[options="header",cols="20,80"] +|=== +| Role | Description +| normal | The connection is used for AMQP clients using normal message delivery. On this connector the router will initiate the connection but it will never create any links. Links are to be created by the peer that accepts the connection. +| inter-router | The connection is assumed to be to another router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections. +| route-container | The connection is to a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the router has created a connection to the remote resource. +|=== // Adding this here for now; in the future it might be better to have separate procedures for creating inter-router and route-container connections. When a router connects to a broker, the broker might provide backup connection data that the router can use if the primary connection fails. If the primary connection fails, the router attempts to reconnect by using a combination of the primary and -- if provided -- backup connections in round-robin fashion until the connection is successful. For more information about viewing the backup connection data provided by the broker, see xref:managing-connectors[]. diff --git a/docs/books/user-guide/configuration-security.adoc b/docs/books/user-guide/configuration-security.adoc index 8c632a66bb..a21c5d6a18 100644 --- a/docs/books/user-guide/configuration-security.adoc +++ b/docs/books/user-guide/configuration-security.adoc @@ -22,6 +22,7 @@ under the License 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: @@ -440,6 +441,7 @@ 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. diff --git a/docs/books/user-guide/modules/how-routers-route-messages.adoc b/docs/books/user-guide/modules/how-routers-route-messages.adoc index 9936821457..34c596b395 100644 --- a/docs/books/user-guide/modules/how-routers-route-messages.adoc +++ b/docs/books/user-guide/modules/how-routers-route-messages.adoc @@ -65,3 +65,9 @@ Flow control is "real" in that credits flow across the link route from the recei + With a link route, consumers can provide server-side selectors for broker subscriptions. -- + +.Additional resources + +* xref:configuring-message-routing[] + +* xref:configuring-link-routing[] diff --git a/docs/books/user-guide/modules/router-management.adoc b/docs/books/user-guide/modules/router-management.adoc index bd500efbe5..91e0ca5478 100644 --- a/docs/books/user-guide/modules/router-management.adoc +++ b/docs/books/user-guide/modules/router-management.adoc @@ -41,3 +41,9 @@ A command-line tool for monitoring the status of a router in the router network. qdmanage:: A command-line tool for viewing and updating the configuration of a router at runtime. + +.Additional resources + +* xref:console-overview[] +* xref:monitoring-using-qdstat[] +* xref:managing-router[] diff --git a/docs/books/user-guide/modules/router-security.adoc b/docs/books/user-guide/modules/router-security.adoc index f35887d256..b11f928f77 100644 --- a/docs/books/user-guide/modules/router-security.adoc +++ b/docs/books/user-guide/modules/router-security.adoc @@ -35,3 +35,9 @@ Authentication:: Authorization:: {RouterName} provides a `policy` mechanism that you can use to enforce user connection restrictions and AMQP resource access control. + +.Additional resources + +* xref:authenticating-remote-peers[] + +* xref:authorizing-access-to-messaging-resources[] \ No newline at end of file diff --git a/docs/books/user-guide/routing.adoc b/docs/books/user-guide/routing.adoc index 417012e264..508153f036 100644 --- a/docs/books/user-guide/routing.adoc +++ b/docs/books/user-guide/routing.adoc @@ -102,6 +102,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 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_. @@ -128,13 +129,109 @@ Addresses determine how messages flow through your router network. An address de When a router receives a message, it uses the message's address to determine where to send the message (either its destination or one step closer to its destination). -// Do we need to specify that these are AMQP addresses? Should they be distinguished from generic message addresses? +==== Mobile Addresses + +Routers consider addresses to be mobile such that any users of an +address may be directly connected to any router in a network and may +move around the topology. In cases where messages are broadcast to or +balanced across multiple consumers, the address users may be connected +to multiple routers in the network. + +Mobile addresses are rendezvous points for senders and receivers. +Messages arrive at the mobile address and are dispatched to their +destinations according to the routing defined for the mobile address. +The details of these routing patterns are discussed later. + +Mobile addresses may be discovered during normal router operation or +configured through management settings. + +===== Discovered Mobile Addresses + +Mobile addresses are created when a client creates a link to a source +or destination address that is unknown to the router network. + +Suppose a service provider wants to offer _my-service_ that clients +may use. The service provider must open a receiver link with source +address _my-service_. The router creates a mobile address +_my-service_ and propagates the address so that it is known to every +router in the network. + +Later a client wants to use the service and creates a sending link +with target address _my-service_. The router matches the service +provider's receiver having source address _my-service_ to the client's +sender having target address _my-service_ and routes messages between +the two. + +Any number of other clients can create links to the service as +well. The clients do not have to know where in the router network the +service provider is physically located nor are the clients required to +connect to a specific router to use the service. Regardless of how +many clients are using the service the service provider needs only a +single connection and link into the router network. + +Another view of this same scenario is when a client tries to use the +service before service provider has connected to the network. In this +case the router network creates the mobile address _my-service_ as +before. However, since the mobile address has only client sender links +and no receiver links the router stalls the clients and prevents them +from sending any messages. Later, after the service provider connects +and creates the receiver link, the router will issue credits to the +clients and the messages will begin to flow between the clients and +the service. + +The service provider can connect, disconnect, and reconnect from a +different location without having to change any of the clients or +their connections. Imagine having the service running on a +laptop. One day the connection is from corporate headquarters and the +next day the connection is from some remote location. In this case the +service provider's computer will typically have different host IP +addresses for each connection. Using the router network the service +provider connects to the router network and offers the named service +and the clients connect to the router network and consume from the +named service. The router network routes messages between the mobile +addresses effectively masking host IP addresses of the service +provider and the client systems. + +===== Configured Mobile Addresses + +Mobile addresses may be configured using the router _autoLink_ +object. An address created via an _autoLink_ represents a queue, +topic, or other service in an external broker. Logically the +_autoLink_ addresses are treated by the router network as if the +broker had connected to the router and offered the services itself. + +For each configured mobile address the router will create a single +link to the external resource. Messages flow between sender links and +receiver links the same regardless if the mobile address was +discovered or configured. + +Multiple _autoLink_ objects may define the same address on multiple +brokers. In this case the router network creates a sharded resource +split between the brokers. Any client can seamlessly send and receive +messages from either broker. + +Note that the brokers do not need to be clustered or federated to +receive this treatment. The brokers may even be from different vendors +or be different versions of the same broker yet still work together to +provide a larger service platform. -// Need to add something here about the difference between discovered vs. configured mobile addresses so that it's clear that with message routing, the router can either be proactive or reactive in the way it routes messages. [id='routing-patterns-overview'] === Routing Patterns +Routing patterns define the paths that a message with a mobile address +can take across a network. These routing patterns can be used for both +direct routing, in which the router distributes messages between +clients without a broker, and indirect routing, in which the router +enables clients to exchange messages through a broker. + +Routing patterns fall into two categories: Anycast +(Balanced and Closest) and Multicast. There is no concept of +"unicast" in which there is only one consumer for an address. + +Anycast distribution delivers each message to one consumer whereas +multicast distribution delivers each message to all consumers. + Each address has one of the following routing patterns, which define the path that a message with the address can take across the messaging network: Balanced:: An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and {RouterName} attempts to balance the traffic load across the router network. @@ -192,6 +289,38 @@ This means that the message did not reach its destination. This means that the message might or might not have reached its destination. The delivery is considered to be "in-doubt" and should be re-sent if "at least once" delivery is required. * The link, session, or connection to {RouterName} was dropped, and all deliveries are "in-doubt". +=== Routing Pattern Reliability + +The following table describes the levels of reliability provided by each routing pattern: + +[options="header",cols="30,70"] +|=== +| Routing pattern | Reliable? + +| Anycast (Balanced or Closest) +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: + +* The delivery shall be settled with ACCEPTED or REJECTED disposition where the disposition is supplied by the consumer. + +* The delivery shall be settled with RELEASED disposition, meaning that the message was not delivered to any consumer. + +* The delivery shall be settled with MODIFIED disposition, meaning that the message may have been delivered to a consumer but should be considered in-doubt and re-sent. + +* 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. + +If a producer sends an unsettled delivery, the disposition may be ACCEPTED or RELEASED. + +* If ACCEPTED, there is no guarantee that the message was delivered to any consumer. + +* If RELEASED, the message was definitely not delivered to any consumer. + +|=== + [id='routing-messages-between-clients'] === Routing Messages Between Clients @@ -521,6 +650,7 @@ The command output shows that Phase 1 of the address was used to deliver all thr Even in a multi-router network, and with multiple producers and consumers for `queue.first`, all deliveries are routed through the queue on the connected broker. ==== +[id='configuring-link-routing'] == Configuring Link Routing Link routing provides an alternative strategy for brokered messaging. A link route represents a private messaging path between a sender and a receiver in which the router passes the messages between end points. You can think of a link route as a "virtual connection" or "tunnel" that travels from a sender, through the router network, to a receiver. @@ -529,7 +659,11 @@ With link routing, routing is performed on link-attach frames, which are chained === Link Route Addresses -A link route address represents a broker queue, topic, or other service. When a client attaches a link route address to a router, the router propagates a link attachment to the broker resource identified by the address. +A link route address represents a broker queue, topic, or other service. When a client attaches a link route address to a router, the router propagates a link attachment to the broker resource identified by the address. + +Using link route addresses, the router network does not participate in +aggregated message distribution. The router simply passes message +delivery and settlement between the two end points. === Link Route Routing Patterns From 29b3a7c90dd4f07858debcb2251c590fda7ce6cf Mon Sep 17 00:00:00 2001 From: Ben Hardesty Date: Wed, 10 Oct 2018 17:18:49 -0400 Subject: [PATCH 9/9] Update getting started --- docs/books/_common/attributes.adoc | 9 ++ .../fragment-router-install-intro.adoc | 25 +++++ .../fragment-router-install-steps.adoc | 27 +++++ .../fragment-starting-router-step.adoc | 2 +- .../assemblies/getting-started.adoc | 42 ++++++++ .../assemblies/important-terms-concepts.adoc | 7 -- .../books/user-guide/assemblies/overview.adoc | 7 -- docs/books/user-guide/book.adoc | 7 +- docs/books/user-guide/modules/_common | 1 + docs/books/user-guide/modules/_images | 1 + .../user-guide/modules/installing-router.adoc | 31 ++++++ docs/books/user-guide/modules/next-steps.adoc | 42 ++++++++ .../modules/sending-test-messages.adoc | 97 ++++++++++++++++++ .../user-guide/modules/starting-router.adoc | 65 ++++++++++++ ...ing-default-router-configuration-file.adoc | 98 +++++++++++++++++++ 15 files changed, 444 insertions(+), 17 deletions(-) create mode 100644 docs/books/_common/fragment-router-install-intro.adoc create mode 100644 docs/books/_common/fragment-router-install-steps.adoc create mode 100644 docs/books/user-guide/assemblies/getting-started.adoc create mode 120000 docs/books/user-guide/modules/_common create mode 120000 docs/books/user-guide/modules/_images create mode 100644 docs/books/user-guide/modules/installing-router.adoc create mode 100644 docs/books/user-guide/modules/next-steps.adoc create mode 100644 docs/books/user-guide/modules/sending-test-messages.adoc create mode 100644 docs/books/user-guide/modules/starting-router.adoc create mode 100644 docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc diff --git a/docs/books/_common/attributes.adoc b/docs/books/_common/attributes.adoc index d150292dd8..01e6f3f153 100644 --- a/docs/books/_common/attributes.adoc +++ b/docs/books/_common/attributes.adoc @@ -52,6 +52,12 @@ under the License :DispatchRouterUrlBase: https://qpid.apache.org/releases/qpid-dispatch-{DispatchRouterVersion} +:DispatchRouterDownloadUrl: https://qpid.apache.org/download.html +:DispatchRouterDownloadLink: link:{DispatchRouterDownloadUrl}[Download page^] + +:DispatchRouterPackagesUrl: https://qpid.apache.org/packages.html +:DispatchRouterPackagesLink: link:{DispatchRouterPackagesUrl}[Packages page^] + :ManagementEntitiesUrl: {DispatchRouterUrlBase}/man/managementschema.html :ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^] @@ -70,6 +76,9 @@ under the License :qdstatManPageUrl: {DispatchRouterUrlBase}/man/qdstat.html :qdstatManPageLink: link:{qdstatManPageUrl}[qdstat man page^] +:QpidDispatchReadmeUrl: https://git-wip-us.apache.org/repos/asf?p=qpid-dispatch.git;a=blob_plain;f=README;hb={DispatchRouterVersion} +:QpidDispatchReadmeLink: link:{QpidDispatchReadmeUrl}[Qpid Dispatch README^] + :ClientAmqpPythonUrl: https://qpid.apache.org/proton/ // Other links diff --git a/docs/books/_common/fragment-router-install-intro.adoc b/docs/books/_common/fragment-router-install-intro.adoc new file mode 100644 index 0000000000..aa1d1fb091 --- /dev/null +++ b/docs/books/_common/fragment-router-install-intro.adoc @@ -0,0 +1,25 @@ +//// +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 +//// + +{RouterName} is distributed as a set of RPM packages, which are available for `yum`/`dnf`-based Linux distributions. Alternatively, you can build the {RouterName} from source. + +[NOTE] +==== +{RouterName} will not build on Windows. +==== diff --git a/docs/books/_common/fragment-router-install-steps.adoc b/docs/books/_common/fragment-router-install-steps.adoc new file mode 100644 index 0000000000..21ccc81ca5 --- /dev/null +++ b/docs/books/_common/fragment-router-install-steps.adoc @@ -0,0 +1,27 @@ +//// +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 +//// + +* Do one of the following: + +** Download and build the {RouterName} source. ++ +To download the source, see {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/_common/fragment-starting-router-step.adoc b/docs/books/_common/fragment-starting-router-step.adoc index 4e9117b895..22142ac36c 100644 --- a/docs/books/_common/fragment-starting-router-step.adoc +++ b/docs/books/_common/fragment-starting-router-step.adoc @@ -22,7 +22,7 @@ under the License -- This example uses the default configuration to start the router as a daemon: -[options="nowrap"] +[source,bash,options="nowrap"] ---- $ qdrouterd -d ---- diff --git a/docs/books/user-guide/assemblies/getting-started.adoc b/docs/books/user-guide/assemblies/getting-started.adoc new file mode 100644 index 0000000000..019c05f73a --- /dev/null +++ b/docs/books/user-guide/assemblies/getting-started.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 +//// + +// This assembly is included in the following assemblies: +// +// book.adoc + +[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. + +// Installing Dispatch Router +include::modules/installing-router.adoc[leveloffset=+1] + +// Viewing the default router configuration file +include::modules/viewing-default-router-configuration-file.adoc[leveloffset=+1] + +// Starting the router +include::modules/starting-router.adoc[leveloffset=+1] + +// Sending some test messages +include::modules/sending-test-messages.adoc[leveloffset=+1] + +// Next steps +include::modules/next-steps.adoc[leveloffset=+1] diff --git a/docs/books/user-guide/assemblies/important-terms-concepts.adoc b/docs/books/user-guide/assemblies/important-terms-concepts.adoc index 2ff3b2e0a8..83a42ffafc 100644 --- a/docs/books/user-guide/assemblies/important-terms-concepts.adoc +++ b/docs/books/user-guide/assemblies/important-terms-concepts.adoc @@ -21,11 +21,8 @@ under the License // // overview.adoc -ifdef::context[:parent-context: {context}] - [id='important-terms-concepts-{context}'] = Important terms and concepts -:context: overview-terms-concepts Before using {RouterName}, you should be familiar with AMQP and understand some key concepts about {RouterName}. @@ -40,7 +37,3 @@ include::modules/how-routers-route-messages.adoc[leveloffset=+1] include::modules/router-security.adoc[leveloffset=+1] include::modules/router-management.adoc[leveloffset=+1] - -// Restore the context to what it was before this assembly. -ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/assemblies/overview.adoc b/docs/books/user-guide/assemblies/overview.adoc index 0565d3ab9b..3474443505 100644 --- a/docs/books/user-guide/assemblies/overview.adoc +++ b/docs/books/user-guide/assemblies/overview.adoc @@ -21,11 +21,8 @@ under the License // // book.adoc -ifdef::context[:parent-context: {context}] - [id='overview-{context}'] = Overview -:context: product-overview {RouterName} is a lightweight AMQP message router for building scalable, available, and performant messaging networks. @@ -36,7 +33,3 @@ include::modules/supported-standards-protocols.adoc[leveloffset=+1] include::important-terms-concepts.adoc[leveloffset=+1] include::_common/document_conventions.adoc[leveloffset=+1] - -// Restore the context to what it was before this assembly. -ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index 971ad30f84..ca0f2c69bc 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -19,8 +19,11 @@ under the License include::_common/attributes.adoc[] +:context: router + = {RouterBook} +// Overview include::assemblies/overview.adoc[leveloffset=+1] // Introduction @@ -29,8 +32,8 @@ include::assemblies/overview.adoc[leveloffset=+1] // Theory of Operation // include::theory_of_operation.adoc[leveloffset=+1] -// Getting Started -include::getting-started.adoc[leveloffset=+1] +// Getting started +include::assemblies/getting-started.adoc[leveloffset=+1] // Configuration include::understand-router-configuration.adoc[leveloffset=+1] diff --git a/docs/books/user-guide/modules/_common b/docs/books/user-guide/modules/_common new file mode 120000 index 0000000000..739f5166be --- /dev/null +++ b/docs/books/user-guide/modules/_common @@ -0,0 +1 @@ +../../_common \ No newline at end of file diff --git a/docs/books/user-guide/modules/_images b/docs/books/user-guide/modules/_images new file mode 120000 index 0000000000..fe463e8894 --- /dev/null +++ b/docs/books/user-guide/modules/_images @@ -0,0 +1 @@ +../../_images \ No newline at end of file diff --git a/docs/books/user-guide/modules/installing-router.adoc b/docs/books/user-guide/modules/installing-router.adoc new file mode 100644 index 0000000000..f870357d6c --- /dev/null +++ b/docs/books/user-guide/modules/installing-router.adoc @@ -0,0 +1,31 @@ +//// +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: +// +// getting-started.adoc + +[id='installing-router-{context}'] += Installing {RouterName} + +include::{FragmentDir}/fragment-router-install-intro.adoc[] + +.Procedure + +include::{FragmentDir}/fragment-router-install-steps.adoc[] diff --git a/docs/books/user-guide/modules/next-steps.adoc b/docs/books/user-guide/modules/next-steps.adoc new file mode 100644 index 0000000000..83a1369441 --- /dev/null +++ b/docs/books/user-guide/modules/next-steps.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 +//// + +// This assembly 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. + +Configure the router:: +You can configure the router to meet the requirements of your production environment. ++ +-- +* 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. diff --git a/docs/books/user-guide/modules/sending-test-messages.adoc b/docs/books/user-guide/modules/sending-test-messages.adoc new file mode 100644 index 0000000000..85b9f44676 --- /dev/null +++ b/docs/books/user-guide/modules/sending-test-messages.adoc @@ -0,0 +1,97 @@ +//// +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: +// +// getting-started.adoc + +[id='sending-test-messages-{context}'] += Sending test messages + +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. + +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. + +.Prerequisites + +{ClientAmqpPythonName} must be installed. For more information, see {ClientAmqpPythonUrl}. + +.Procedure + +. Navigate to the {ClientAmqpPythonName} Python examples directory. ++ +-- +[source,bash,options="nowrap",subs="+quotes"] +---- +$ cd ____/examples/python/ +---- + +:: The directory where you installed {ClientAmqpPythonName}. +-- + +. Start the `simple_recv.py` receiver client. ++ +-- +[source,bash,options="nowrap"] +---- +$ python simple_recv.py -a 127.0.0.1:5672/examples -m 5 +---- + +This command starts the receiver and listens on the `examples` address (`127.0.0.1:5672/examples`). The receiver is also set to receive a maximum of five messages. + +[NOTE] +==== +In practice, the order in which you start senders and receivers does not matter. In both cases, messages will be sent as soon as the receiver comes online. +==== +-- + +. In a new terminal window, navigate to the Python examples directory and run the `simple_send.py` example: ++ +-- +[source,bash,options="nowrap",subs="+quotes"] +---- +$ cd ____/examples/python/ +$ python simple_send.py -a 127.0.0.1:5672/examples -m 5 +---- + +This command sends five auto-generated messages to the `examples` address (`127.0.0.1:5672/examples`) and then confirms that they were delivered and acknowledged by the receiver: + +[source,bash,options="nowrap"] +---- +all messages confirmed +---- +-- + +. Verify that the receiver client received the messages. ++ +-- +The receiver client should display the contents of the five messages: + +[source,bash,options="nowrap"] +---- +{u'sequence': 1L} +{u'sequence': 2L} +{u'sequence': 3L} +{u'sequence': 4L} +{u'sequence': 5L} +---- +-- diff --git a/docs/books/user-guide/modules/starting-router.adoc b/docs/books/user-guide/modules/starting-router.adoc new file mode 100644 index 0000000000..14e8bdfd2a --- /dev/null +++ b/docs/books/user-guide/modules/starting-router.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 +//// + +// This assembly is included in the following assemblies: +// +// getting-started.adoc + +[id='starting-router-{context}'] += Starting the router + +After installing {RouterName}, you start the router by using the `qdrouterd` command. + +.Procedure + +// 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`. + +. View the log to verify the router status: ++ +[source,bash,options="nowrap"] +---- +$ qdstat --log +---- ++ +This example shows that the router was correctly installed, is running, and is ready to route traffic between clients: ++ +[options="nowrap"] +---- +$ qdstat --log +Fri May 20 09:38:03 2017 SERVER (info) Container Name: Router.A +Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone mode +Fri May 20 09:38:03 2017 ROUTER_CORE (info) Router Core thread running. 0/Router.A +Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription M/$management +Fri May 20 09:38:03 2017 AGENT (info) Activating management agent on $_management_internal +Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$management +Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$_management_internal +Fri May 20 09:38:03 2017 DISPLAYNAME (info) Activating DisplayNameService on $displayname +Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$displayname +Fri May 20 09:38:03 2017 CONN_MGR (info) Configured Listener: 0.0.0.0:amqp proto=any role=normal +Fri May 20 09:38:03 2017 POLICY (info) Policy configured maximumConnections: 0, policyFolder: '', access rules enabled: 'false' +Fri May 20 09:38:03 2017 POLICY (info) Policy fallback defaultApplication is disabled +Fri May 20 09:38:03 2017 SERVER (info) Operational, 4 Threads Running +---- + +.Additional resources + +* The {qdrouterdManPageLink}. diff --git a/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc b/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc new file mode 100644 index 0000000000..80300fac1b --- /dev/null +++ b/docs/books/user-guide/modules/viewing-default-router-configuration-file.adoc @@ -0,0 +1,98 @@ +//// +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: +// +// getting-started.adoc + +[id='viewing-default-router-configuration-file-{context}'] += Viewing the default router configuration file + +The router's configuration file (`qdrouterd.conf`) controls the way in which the router functions. The default configuration file contains the minimum number of settings required for the router to run. As you become more familiar with the router, you can add to or change these settings, or create your own configuration files. + +By default, the router configuration file defines the following settings for the router: + +* Operating mode +* How it listens for incoming connections +* Routing patterns for the message routing mechanism + +.Procedure + +. Open the following file: `/etc/qpid-dispatch/qdrouterd.conf`. ++ +-- +When {RouterName} is installed, `qdrouterd.conf` is installed in this directory. When the router is started, it runs with the settings defined in this file. +-- + +. Review the default settings in `qdrouterd.conf`. ++ +-- +.Default Configuration File +[options="nowrap"] +---- +router { + mode: standalone // <1> + id: Router.A // <2> +} + +listener { // <3> + host: 0.0.0.0 + port: amqp + authenticatePeer: no +} + +address { // <4> + prefix: closest + distribution: closest +} + +address { + prefix: multicast + distribution: multicast +} + +address { + prefix: unicast + distribution: closest +} + +address { + prefix: exclusive + distribution: closest +} + +address { + prefix: broadcast + distribution: multicast +} +---- +<1> By default, the router operates in _standalone_ mode. This means that it can only communicate with endpoints that are directly connected to it. It cannot connect to other routers, or participate in a router network. +<2> The unique identifier of the router. This ID is used as the `container-id` (container name) at the AMQP protocol level. It is required, and the router will not start if this attribute is not defined. +<3> The `listener` entity handles incoming connections from client endpoints. By default, the router listens on all network interfaces on the default AMQP port (5672). +<4> By default, the router is configured to use the message routing mechanism. Each `address` entity defines how messages that are received with a particular address `prefix` should be distributed. For example, all messages with addresses that start with `closest` will be distributed using the `closest` distribution pattern. + +[NOTE] +==== +If a client requests a message with an address that is not defined in the router's configuration file, the `balanced` distribution pattern will be used automatically. +==== +-- + +.Additional resources + +* For more information about the router configuration file (including available entities and attributes), see the {qdrouterdManPageLink}.