DISPATCH-1144: Improve overview and getting started doc This closes #391
Project: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/commit/40de3931 Tree: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/tree/40de3931 Diff: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/diff/40de3931 Branch: refs/heads/master Commit: 40de3931637e6986563524776dacfdd15b8b6aad Parents: ba71448 Author: Ben Hardesty <bhard...@redhat.com> Authored: Mon Aug 20 12:41:32 2018 -0400 Committer: Ted Ross <tr...@redhat.com> Committed: Thu Oct 18 14:22:01 2018 -0400 ---------------------------------------------------------------------- docs/books/_common/attributes.adoc | 87 ++++++++++++ docs/books/_common/document_conventions.adoc | 27 ++++ .../_common/fragment-router-install-intro.adoc | 25 ++++ .../_common/fragment-router-install-steps.adoc | 27 ++++ .../_common/fragment-router-sasl-para.adoc | 20 +++ .../_common/fragment-starting-router-step.adoc | 29 ++++ docs/books/_images/01-peer-to-peer.png | Bin 0 -> 20101 bytes docs/books/_images/balanced-routing.png | Bin 0 -> 43261 bytes docs/books/_images/brokered-messaging.png | Bin 0 -> 50206 bytes docs/books/_images/closest-routing.png | Bin 0 -> 39803 bytes docs/books/_images/console1.png | Bin 0 -> 40412 bytes docs/books/_images/console_charts.png | Bin 0 -> 70070 bytes docs/books/_images/console_entity.png | Bin 0 -> 69319 bytes docs/books/_images/console_login.png | Bin 0 -> 39915 bytes docs/books/_images/console_overview.png | Bin 0 -> 87960 bytes docs/books/_images/console_schema.png | Bin 0 -> 68025 bytes docs/books/_images/console_topology.png | Bin 0 -> 67338 bytes docs/books/_images/link-routing.png | Bin 0 -> 46968 bytes docs/books/_images/message-routing.png | Bin 0 -> 35861 bytes docs/books/_images/multicast-routing.png | Bin 0 -> 44923 bytes docs/books/_images/path-redundancy-01.png | Bin 0 -> 47995 bytes docs/books/_images/path-redundancy-02.png | Bin 0 -> 42131 bytes .../path-redundancy-temp-decoupling-01.png | Bin 0 -> 47766 bytes .../path-redundancy-temp-decoupling-02.png | Bin 0 -> 49105 bytes docs/books/_images/sharded-queue-01.png | Bin 0 -> 28383 bytes docs/books/_images/sharded-queue-02.png | Bin 0 -> 62233 bytes .../books/common/fragment-router-sasl-para.adoc | 20 --- .../common/fragment-starting-router-step.adoc | 29 ---- docs/books/user-guide/_common | 1 + docs/books/user-guide/_images | 1 + docs/books/user-guide/assemblies/_common | 1 + .../user-guide/assemblies/getting-started.adoc | 42 ++++++ .../assemblies/important-terms-concepts.adoc | 39 ++++++ docs/books/user-guide/assemblies/modules | 1 + docs/books/user-guide/assemblies/overview.adoc | 35 +++++ docs/books/user-guide/attributes.adoc | 78 ----------- docs/books/user-guide/book.adoc | 15 +- docs/books/user-guide/common | 1 - .../user-guide/configuration-connections.adoc | 34 ++++- .../user-guide/configuration-security.adoc | 2 + .../books/user-guide/images/01-peer-to-peer.png | Bin 20101 -> 0 bytes .../user-guide/images/balanced-routing.png | Bin 43261 -> 0 bytes .../user-guide/images/brokered-messaging.png | Bin 50206 -> 0 bytes .../books/user-guide/images/closest-routing.png | Bin 39803 -> 0 bytes docs/books/user-guide/images/console1.png | Bin 40412 -> 0 bytes docs/books/user-guide/images/console_charts.png | Bin 70070 -> 0 bytes docs/books/user-guide/images/console_entity.png | Bin 69319 -> 0 bytes docs/books/user-guide/images/console_login.png | Bin 39915 -> 0 bytes .../user-guide/images/console_overview.png | Bin 87960 -> 0 bytes docs/books/user-guide/images/console_schema.png | Bin 68025 -> 0 bytes .../user-guide/images/console_topology.png | Bin 67338 -> 0 bytes docs/books/user-guide/images/link-routing.png | Bin 46968 -> 0 bytes .../books/user-guide/images/message-routing.png | Bin 35861 -> 0 bytes .../user-guide/images/multicast-routing.png | Bin 44923 -> 0 bytes .../user-guide/images/path-redundancy-01.png | Bin 47995 -> 0 bytes .../user-guide/images/path-redundancy-02.png | Bin 42131 -> 0 bytes .../path-redundancy-temp-decoupling-01.png | Bin 47766 -> 0 bytes .../path-redundancy-temp-decoupling-02.png | Bin 49105 -> 0 bytes .../user-guide/images/sharded-queue-01.png | Bin 28383 -> 0 bytes .../user-guide/images/sharded-queue-02.png | Bin 62233 -> 0 bytes docs/books/user-guide/modules/_common | 1 + docs/books/user-guide/modules/_images | 1 + .../modules/how-routers-connect-endpoints.adoc | 52 +++++++ .../modules/how-routers-route-messages.adoc | 73 ++++++++++ .../user-guide/modules/installing-router.adoc | 31 ++++ docs/books/user-guide/modules/key-features.adoc | 32 +++++ docs/books/user-guide/modules/link-routing.adoc | 43 ++++++ .../user-guide/modules/message-routing.adoc | 112 +++++++++++++++ docs/books/user-guide/modules/next-steps.adoc | 42 ++++++ .../user-guide/modules/overview-of-amqp.adoc | 46 ++++++ .../user-guide/modules/router-management.adoc | 49 +++++++ .../user-guide/modules/router-security.adoc | 43 ++++++ .../modules/sending-test-messages.adoc | 97 +++++++++++++ .../user-guide/modules/starting-router.adoc | 65 +++++++++ .../modules/supported-standards-protocols.adoc | 39 ++++++ ...ewing-default-router-configuration-file.adoc | 98 +++++++++++++ .../user-guide/modules/what-routers-are.adoc | 47 +++++++ docs/books/user-guide/routing.adoc | 140 ++++++++++++++++++- 78 files changed, 1387 insertions(+), 138 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/attributes.adoc ---------------------------------------------------------------------- diff --git a/docs/books/_common/attributes.adoc b/docs/books/_common/attributes.adoc new file mode 100644 index 0000000..01e6f3f --- /dev/null +++ b/docs/books/_common/attributes.adoc @@ -0,0 +1,87 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License +//// + +// Standard document attributes + +:data-uri!: +:doctype: article +:experimental: +:idprefix: +:imagesdir: _images +:numbered: +:sectanchors!: +:sectnums: +:source-highlighter: highlightjs +:highlightjs-theme: solarized_dark +:toc: left +:linkattrs: +:toclevels: 3 + +// Component attributes + +:ProductName: Apache Qpid +:RouterLongName: {ProductName} Dispatch Router +:ClientAmqpPythonName: {ProductName} Proton Python +:ConsoleName: {RouterLongName} Console +:FragmentDir: _common +:RouterName: Dispatch Router +:RouterSchemaDir: ../../build/doc/book +:DispatchRouterVersion: 1.0.1 + +// Book names + +:RouterBook: Using {RouterLongName} + +// Doc links + +: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^] + +:RouterBookUrl: {DispatchRouterUrlBase}/book/book.html +:RouterBookLink: link:{RouterBookUrl}[{RouterBook}] + +:qdmanageManPageUrl: {DispatchRouterUrlBase}/man/qdmanage.html +:qdmanageManPageLink: link:{qdmanageManPageUrl}[qdmanage man page^] + +:qdrouterdManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.html +:qdrouterdManPageLink: link:{qdrouterdManPageUrl}[qdrouterd man page^] + +:qdrouterdConfManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.conf.html +:qdrouterdConfManPageLink: link:{qdrouterdConfManPageUrl}[qdrouterd.conf man page^] + +: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 + +:AmqpSpecUrl: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html +:AmqpSpecLink: link:{AmqpSpecUrl}[AMQP 1.0 specification^] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/document_conventions.adoc ---------------------------------------------------------------------- diff --git a/docs/books/_common/document_conventions.adoc b/docs/books/_common/document_conventions.adoc new file mode 100644 index 0000000..7762cb9 --- /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. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-install-intro.adoc ---------------------------------------------------------------------- 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 0000000..aa1d1fb --- /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. +==== http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-install-steps.adoc ---------------------------------------------------------------------- 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 0000000..21ccc81 --- /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}. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-router-sasl-para.adoc ---------------------------------------------------------------------- diff --git a/docs/books/_common/fragment-router-sasl-para.adoc b/docs/books/_common/fragment-router-sasl-para.adoc new file mode 100644 index 0000000..c6264e4 --- /dev/null +++ b/docs/books/_common/fragment-router-sasl-para.adoc @@ -0,0 +1,20 @@ +//// +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 +//// + +To see a list of Cyrus SASL plugins in a `dnf`-based Linux system, use the `dnf search cyrus-sasl` command. To install a Cyrus SASL plugin, use the `dnf install _PLUGIN_` command. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_common/fragment-starting-router-step.adoc ---------------------------------------------------------------------- diff --git a/docs/books/_common/fragment-starting-router-step.adoc b/docs/books/_common/fragment-starting-router-step.adoc new file mode 100644 index 0000000..22142ac --- /dev/null +++ b/docs/books/_common/fragment-starting-router-step.adoc @@ -0,0 +1,29 @@ +//// +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 +//// + +. To start the router, use the *`qdrouterd`* command. ++ +-- +This example uses the default configuration to start the router as a daemon: + +[source,bash,options="nowrap"] +---- +$ qdrouterd -d +---- +-- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/01-peer-to-peer.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/01-peer-to-peer.png b/docs/books/_images/01-peer-to-peer.png new file mode 100644 index 0000000..5c834aa Binary files /dev/null and b/docs/books/_images/01-peer-to-peer.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/balanced-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/balanced-routing.png b/docs/books/_images/balanced-routing.png new file mode 100644 index 0000000..fedcdbf Binary files /dev/null and b/docs/books/_images/balanced-routing.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/brokered-messaging.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/brokered-messaging.png b/docs/books/_images/brokered-messaging.png new file mode 100644 index 0000000..ae129d4 Binary files /dev/null and b/docs/books/_images/brokered-messaging.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/closest-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/closest-routing.png b/docs/books/_images/closest-routing.png new file mode 100644 index 0000000..ba3f0a5 Binary files /dev/null and b/docs/books/_images/closest-routing.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console1.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console1.png b/docs/books/_images/console1.png new file mode 100644 index 0000000..f131884 Binary files /dev/null and b/docs/books/_images/console1.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_charts.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_charts.png b/docs/books/_images/console_charts.png new file mode 100644 index 0000000..169c2ca Binary files /dev/null and b/docs/books/_images/console_charts.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_entity.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_entity.png b/docs/books/_images/console_entity.png new file mode 100644 index 0000000..130c7e7 Binary files /dev/null and b/docs/books/_images/console_entity.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_login.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_login.png b/docs/books/_images/console_login.png new file mode 100644 index 0000000..63e22c6 Binary files /dev/null and b/docs/books/_images/console_login.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_overview.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_overview.png b/docs/books/_images/console_overview.png new file mode 100644 index 0000000..af25f36 Binary files /dev/null and b/docs/books/_images/console_overview.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_schema.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_schema.png b/docs/books/_images/console_schema.png new file mode 100644 index 0000000..ba56c7b Binary files /dev/null and b/docs/books/_images/console_schema.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/console_topology.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/console_topology.png b/docs/books/_images/console_topology.png new file mode 100644 index 0000000..ae4b22a Binary files /dev/null and b/docs/books/_images/console_topology.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/link-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/link-routing.png b/docs/books/_images/link-routing.png new file mode 100644 index 0000000..0c1b9e4 Binary files /dev/null and b/docs/books/_images/link-routing.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/message-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/message-routing.png b/docs/books/_images/message-routing.png new file mode 100644 index 0000000..42f4638 Binary files /dev/null and b/docs/books/_images/message-routing.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/multicast-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/multicast-routing.png b/docs/books/_images/multicast-routing.png new file mode 100644 index 0000000..d4548a6 Binary files /dev/null and b/docs/books/_images/multicast-routing.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-01.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/path-redundancy-01.png b/docs/books/_images/path-redundancy-01.png new file mode 100644 index 0000000..ba8f10d Binary files /dev/null and b/docs/books/_images/path-redundancy-01.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-02.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/path-redundancy-02.png b/docs/books/_images/path-redundancy-02.png new file mode 100644 index 0000000..6d4a1f5 Binary files /dev/null and b/docs/books/_images/path-redundancy-02.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-temp-decoupling-01.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/path-redundancy-temp-decoupling-01.png b/docs/books/_images/path-redundancy-temp-decoupling-01.png new file mode 100644 index 0000000..c3c6631 Binary files /dev/null and b/docs/books/_images/path-redundancy-temp-decoupling-01.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/path-redundancy-temp-decoupling-02.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/path-redundancy-temp-decoupling-02.png b/docs/books/_images/path-redundancy-temp-decoupling-02.png new file mode 100644 index 0000000..ecab8b1 Binary files /dev/null and b/docs/books/_images/path-redundancy-temp-decoupling-02.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/sharded-queue-01.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/sharded-queue-01.png b/docs/books/_images/sharded-queue-01.png new file mode 100644 index 0000000..ab25be0 Binary files /dev/null and b/docs/books/_images/sharded-queue-01.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/_images/sharded-queue-02.png ---------------------------------------------------------------------- diff --git a/docs/books/_images/sharded-queue-02.png b/docs/books/_images/sharded-queue-02.png new file mode 100644 index 0000000..7e73e6d Binary files /dev/null and b/docs/books/_images/sharded-queue-02.png differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/common/fragment-router-sasl-para.adoc ---------------------------------------------------------------------- diff --git a/docs/books/common/fragment-router-sasl-para.adoc b/docs/books/common/fragment-router-sasl-para.adoc deleted file mode 100644 index c6264e4..0000000 --- a/docs/books/common/fragment-router-sasl-para.adoc +++ /dev/null @@ -1,20 +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 -//// - -To see a list of Cyrus SASL plugins in a `dnf`-based Linux system, use the `dnf search cyrus-sasl` command. To install a Cyrus SASL plugin, use the `dnf install _PLUGIN_` command. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/common/fragment-starting-router-step.adoc ---------------------------------------------------------------------- diff --git a/docs/books/common/fragment-starting-router-step.adoc b/docs/books/common/fragment-starting-router-step.adoc deleted file mode 100644 index 4e9117b..0000000 --- a/docs/books/common/fragment-starting-router-step.adoc +++ /dev/null @@ -1,29 +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 -//// - -. To start the router, use the *`qdrouterd`* command. -+ --- -This example uses the default configuration to start the router as a daemon: - -[options="nowrap"] ----- -$ qdrouterd -d ----- --- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/_common ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/_common b/docs/books/user-guide/_common new file mode 120000 index 0000000..7c77149 --- /dev/null +++ b/docs/books/user-guide/_common @@ -0,0 +1 @@ +../_common \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/_images ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/_images b/docs/books/user-guide/_images new file mode 120000 index 0000000..6d8b580 --- /dev/null +++ b/docs/books/user-guide/_images @@ -0,0 +1 @@ +../_images \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/_common ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/assemblies/_common b/docs/books/user-guide/assemblies/_common new file mode 120000 index 0000000..739f516 --- /dev/null +++ b/docs/books/user-guide/assemblies/_common @@ -0,0 +1 @@ +../../_common \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/getting-started.adoc ---------------------------------------------------------------------- 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 0000000..019c05f --- /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] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/important-terms-concepts.adoc ---------------------------------------------------------------------- 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 0000000..83a42ff --- /dev/null +++ b/docs/books/user-guide/assemblies/important-terms-concepts.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 +//// + +// This assembly is included in the following assemblies: +// +// overview.adoc + +[id='important-terms-concepts-{context}'] += Important terms and 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/how-routers-connect-endpoints.adoc[leveloffset=+1] + +include::modules/how-routers-route-messages.adoc[leveloffset=+1] + +include::modules/router-security.adoc[leveloffset=+1] + +include::modules/router-management.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/modules ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/assemblies/modules b/docs/books/user-guide/assemblies/modules new file mode 120000 index 0000000..464b823 --- /dev/null +++ b/docs/books/user-guide/assemblies/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/assemblies/overview.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/assemblies/overview.adoc b/docs/books/user-guide/assemblies/overview.adoc new file mode 100644 index 0000000..3474443 --- /dev/null +++ b/docs/books/user-guide/assemblies/overview.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 +//// + +// This assembly is included in the following assemblies: +// +// book.adoc + +[id='overview-{context}'] += 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] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/attributes.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/attributes.adoc b/docs/books/user-guide/attributes.adoc deleted file mode 100644 index 0162710..0000000 --- a/docs/books/user-guide/attributes.adoc +++ /dev/null @@ -1,78 +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 -//// - -// Standard document attributes - -:data-uri!: -:doctype: article -:experimental: -:idprefix: -:imagesdir: images -:numbered: -:sectanchors!: -:sectnums: -:source-highlighter: highlightjs -:highlightjs-theme: solarized_dark -:toc: left -:linkattrs: -:toclevels: 3 - -// Component attributes - -:ProductName: Apache Qpid -:RouterLongName: {ProductName} Dispatch Router -:ClientAmqpPythonName: {ProductName} Proton Python -:ConsoleName: {RouterLongName} Console -:FragmentDir: common -:RouterName: Dispatch Router -:RouterSchemaDir: ../../build/doc/book -:DispatchRouterVersion: 1.0.1 - -// Book names - -:RouterBook: Using {RouterLongName} - -// Doc links - -:DispatchRouterUrlBase: https://qpid.apache.org/releases/qpid-dispatch-{DispatchRouterVersion} - -:ManagementEntitiesUrl: {DispatchRouterUrlBase}/man/managementschema.html -:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} Management Schema^] - -:RouterBookUrl: {DispatchRouterUrlBase}/book/book.html -:RouterBookLink: link:{RouterBookUrl}[{RouterBook}] - -:qdmanageManPageUrl: {DispatchRouterUrlBase}/man/qdmanage.html -:qdmanageManPageLink: link:{qdmanageManPageUrl}[qdmanage man page^] - -:qdrouterdManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.html -:qdrouterdManPageLink: link:{qdrouterdManPageUrl}[qdrouterd man page^] - -:qdrouterdConfManPageUrl: {DispatchRouterUrlBase}/man/qdrouterd.conf.html -:qdrouterdConfManPageLink: link:{qdrouterdConfManPageUrl}[qdrouterd.conf man page^] - -:qdstatManPageUrl: {DispatchRouterUrlBase}/man/qdstat.html -:qdstatManPageLink: link:{qdstatManPageUrl}[qdstat man page^] - -:ClientAmqpPythonUrl: https://qpid.apache.org/proton/ - -// Other links - -:AmqpSpecUrl: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html -:AmqpSpecLink: link:{AmqpSpecUrl}[AMQP 1.0 specification^] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/book.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/book.adoc b/docs/books/user-guide/book.adoc index 4ed6bdf..ca0f2c6 100644 --- a/docs/books/user-guide/book.adoc +++ b/docs/books/user-guide/book.adoc @@ -17,18 +17,23 @@ specific language governing permissions and limitations under the License //// -include::attributes.adoc[] +include::_common/attributes.adoc[] + +:context: router = {RouterBook} +// Overview +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] +// Getting started +include::assemblies/getting-started.adoc[leveloffset=+1] // Configuration include::understand-router-configuration.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/common ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/common b/docs/books/user-guide/common deleted file mode 120000 index 60d3b0a..0000000 --- a/docs/books/user-guide/common +++ /dev/null @@ -1 +0,0 @@ -../common \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/configuration-connections.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/configuration-connections.adoc b/docs/books/user-guide/configuration-connections.adoc index 26e10a2..5c24422 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[]. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/configuration-security.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/configuration-security.adoc b/docs/books/user-guide/configuration-security.adoc index 8c632a6..a21c5d6 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. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/01-peer-to-peer.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/01-peer-to-peer.png b/docs/books/user-guide/images/01-peer-to-peer.png deleted file mode 100644 index 5c834aa..0000000 Binary files a/docs/books/user-guide/images/01-peer-to-peer.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/balanced-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/balanced-routing.png b/docs/books/user-guide/images/balanced-routing.png deleted file mode 100644 index fedcdbf..0000000 Binary files a/docs/books/user-guide/images/balanced-routing.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/brokered-messaging.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/brokered-messaging.png b/docs/books/user-guide/images/brokered-messaging.png deleted file mode 100644 index ae129d4..0000000 Binary files a/docs/books/user-guide/images/brokered-messaging.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/closest-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/closest-routing.png b/docs/books/user-guide/images/closest-routing.png deleted file mode 100644 index ba3f0a5..0000000 Binary files a/docs/books/user-guide/images/closest-routing.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console1.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console1.png b/docs/books/user-guide/images/console1.png deleted file mode 100644 index f131884..0000000 Binary files a/docs/books/user-guide/images/console1.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_charts.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_charts.png b/docs/books/user-guide/images/console_charts.png deleted file mode 100644 index 169c2ca..0000000 Binary files a/docs/books/user-guide/images/console_charts.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_entity.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_entity.png b/docs/books/user-guide/images/console_entity.png deleted file mode 100644 index 130c7e7..0000000 Binary files a/docs/books/user-guide/images/console_entity.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_login.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_login.png b/docs/books/user-guide/images/console_login.png deleted file mode 100644 index 63e22c6..0000000 Binary files a/docs/books/user-guide/images/console_login.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_overview.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_overview.png b/docs/books/user-guide/images/console_overview.png deleted file mode 100644 index af25f36..0000000 Binary files a/docs/books/user-guide/images/console_overview.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_schema.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_schema.png b/docs/books/user-guide/images/console_schema.png deleted file mode 100644 index ba56c7b..0000000 Binary files a/docs/books/user-guide/images/console_schema.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/console_topology.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/console_topology.png b/docs/books/user-guide/images/console_topology.png deleted file mode 100644 index ae4b22a..0000000 Binary files a/docs/books/user-guide/images/console_topology.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/link-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/link-routing.png b/docs/books/user-guide/images/link-routing.png deleted file mode 100644 index 0c1b9e4..0000000 Binary files a/docs/books/user-guide/images/link-routing.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/message-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/message-routing.png b/docs/books/user-guide/images/message-routing.png deleted file mode 100644 index 42f4638..0000000 Binary files a/docs/books/user-guide/images/message-routing.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/multicast-routing.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/multicast-routing.png b/docs/books/user-guide/images/multicast-routing.png deleted file mode 100644 index d4548a6..0000000 Binary files a/docs/books/user-guide/images/multicast-routing.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-01.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/path-redundancy-01.png b/docs/books/user-guide/images/path-redundancy-01.png deleted file mode 100644 index ba8f10d..0000000 Binary files a/docs/books/user-guide/images/path-redundancy-01.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-02.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/path-redundancy-02.png b/docs/books/user-guide/images/path-redundancy-02.png deleted file mode 100644 index 6d4a1f5..0000000 Binary files a/docs/books/user-guide/images/path-redundancy-02.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png b/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png deleted file mode 100644 index c3c6631..0000000 Binary files a/docs/books/user-guide/images/path-redundancy-temp-decoupling-01.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png b/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png deleted file mode 100644 index ecab8b1..0000000 Binary files a/docs/books/user-guide/images/path-redundancy-temp-decoupling-02.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/sharded-queue-01.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/sharded-queue-01.png b/docs/books/user-guide/images/sharded-queue-01.png deleted file mode 100644 index ab25be0..0000000 Binary files a/docs/books/user-guide/images/sharded-queue-01.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/images/sharded-queue-02.png ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/images/sharded-queue-02.png b/docs/books/user-guide/images/sharded-queue-02.png deleted file mode 100644 index 7e73e6d..0000000 Binary files a/docs/books/user-guide/images/sharded-queue-02.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/_common ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/modules/_common b/docs/books/user-guide/modules/_common new file mode 120000 index 0000000..739f516 --- /dev/null +++ b/docs/books/user-guide/modules/_common @@ -0,0 +1 @@ +../../_common \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/_images ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/modules/_images b/docs/books/user-guide/modules/_images new file mode 120000 index 0000000..fe463e8 --- /dev/null +++ b/docs/books/user-guide/modules/_images @@ -0,0 +1 @@ +../../_images \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc ---------------------------------------------------------------------- diff --git a/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc b/docs/books/user-guide/modules/how-routers-connect-endpoints.adoc new file mode 100644 index 0000000..eb7e117 --- /dev/null +++ b/docs/books/user-guide/modules/how-routers-connect-endpoints.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='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. + +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. + +|=== http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/how-routers-route-messages.adoc ---------------------------------------------------------------------- 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 0000000..34c596b --- /dev/null +++ b/docs/books/user-guide/modules/how-routers-route-messages.adoc @@ -0,0 +1,73 @@ +//// +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. +-- + +.Additional resources + +* xref:configuring-message-routing[] + +* xref:configuring-link-routing[] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/installing-router.adoc ---------------------------------------------------------------------- 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 0000000..f870357 --- /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[] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/key-features.adoc ---------------------------------------------------------------------- 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 0000000..808e910 --- /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 http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/link-routing.adoc ---------------------------------------------------------------------- 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 0000000..d7fae9f --- /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 http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/message-routing.adoc ---------------------------------------------------------------------- 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 0000000..6aa9df9 --- /dev/null +++ b/docs/books/user-guide/modules/message-routing.adoc @@ -0,0 +1,112 @@ +//// +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] +== 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 two categories of routing patterns: anycast and multicast. + +[NOTE] +==== +{RouterName} does not provide a true "unicast" routing pattern in which there is only one consumer for an address. +==== + +[options="header"] +|=== +| Routing pattern | Description | Reliability + +| Anycast +a| Each message is delivered to one consumer. There are two types of anycast methods: + +* Balanced ++ +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. + +* Closest ++ +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. + +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. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/next-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 0000000..83a1369 --- /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. http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/overview-of-amqp.adoc ---------------------------------------------------------------------- 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 0000000..dcd2a12 --- /dev/null +++ b/docs/books/user-guide/modules/overview-of-amqp.adoc @@ -0,0 +1,46 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License +//// + +// 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}. + +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/The-AMQP-10-Protocol-16-Overview[Video series introducing AMQP 1.0] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/router-management.adoc ---------------------------------------------------------------------- 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 0000000..91e0ca5 --- /dev/null +++ b/docs/books/user-guide/modules/router-management.adoc @@ -0,0 +1,49 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License +//// + +// 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. + +.Additional resources + +* xref:console-overview[] +* xref:monitoring-using-qdstat[] +* xref:managing-router[] http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/router-security.adoc ---------------------------------------------------------------------- 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 0000000..b11f928 --- /dev/null +++ b/docs/books/user-guide/modules/router-security.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-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. + +.Additional resources + +* xref:authenticating-remote-peers[] + +* xref:authorizing-access-to-messaging-resources[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/sending-test-messages.adoc ---------------------------------------------------------------------- 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 0000000..85b9f44 --- /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 __<install-dir>__/examples/python/ +---- + +<install-dir>:: 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 __<install-dir>__/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} +---- +-- http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/40de3931/docs/books/user-guide/modules/starting-router.adoc ---------------------------------------------------------------------- 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 0000000..14e8bdf --- /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}. --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
