On Wed, Sep 27, 2017 at 10:56 AM, Robbie Gemmell <[email protected]> wrote:
> This seems like it would have been good to have a JIRA for. > > Also, using cherry-pick -x when handling a PR isn't great for the repo > history. The updated log message and/or rebase here mean the commit > sha changed when going from the mirrors PR ref to the main repo. Since > the original commit was never in the main repo, browsing its web view > for this commit will show a link that 404's. > Thanks for pointing this out Robbie. I have also sometimes used the -x option which I will now stop if I am cherry picking from my private branch. The git documentation is pretty clear on this - "Do not use this option if you are cherry-picking from your private branch because the information is useless to the recipient. If on the other hand you are cherry-picking between two publicly visible branches (e.g. backporting a fix to a maintenance branch for an older release from a development branch), adding this information can be useful." https://git-scm.com/docs/git-cherry-pick#git-cherry-pick--x > > On 26 September 2017 at 13:39, <[email protected]> wrote: > > NO-JIRA - Add new book dir for dispatch router book; contribute doc > improvements > > This closes #200 > > > > (cherry picked from commit 0a89a302f79d9ded74508863f5c8ce31ca0a13a2) > > > > > > Project: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/repo > > Commit: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/ > commit/2f192d0a > > Tree: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/tree/2f192d0a > > Diff: http://git-wip-us.apache.org/repos/asf/qpid-dispatch/diff/2f192d0a > > > > Branch: refs/heads/master > > Commit: 2f192d0a3c6ff3e579a2cfa063947b09a373642a > > Parents: 1bc362f > > Author: Ben Hardesty <[email protected]> > > Authored: Fri Sep 1 14:46:31 2017 -0400 > > Committer: Ted Ross <[email protected]> > > Committed: Tue Sep 26 08:34:11 2017 -0400 > > > > ---------------------------------------------------------------------- > > doc/common/fragment-starting-router-step.adoc | 29 + > > doc/new-book/attributes.adoc | 75 ++ > > doc/new-book/book.adoc | 67 ++ > > doc/new-book/common | 1 + > > doc/new-book/configuration-connections.adoc | 87 +++ > > doc/new-book/configuration-reference.adoc | 224 ++++++ > > doc/new-book/configuration-security.adoc | 336 +++++++++ > > doc/new-book/cyrus-sasl.adoc | 90 +++ > > doc/new-book/getting-started.adoc | 156 +++++ > > doc/new-book/images/01-peer-to-peer.png | Bin 0 -> 20101 bytes > > doc/new-book/images/balanced-routing.png | Bin 0 -> 43261 bytes > > doc/new-book/images/brokered-messaging.png | Bin 0 -> 50206 bytes > > doc/new-book/images/closest-routing.png | Bin 0 -> 39803 bytes > > doc/new-book/images/console1.png | Bin 0 -> 40412 bytes > > doc/new-book/images/console_charts.png | Bin 0 -> 70070 bytes > > doc/new-book/images/console_entity.png | Bin 0 -> 69319 bytes > > doc/new-book/images/console_login.png | Bin 0 -> 39915 bytes > > doc/new-book/images/console_overview.png | Bin 0 -> 87960 bytes > > doc/new-book/images/console_schema.png | Bin 0 -> 68025 bytes > > doc/new-book/images/console_topology.png | Bin 0 -> 67338 bytes > > doc/new-book/images/link-routing.png | Bin 0 -> 46968 bytes > > doc/new-book/images/message-routing.png | Bin 0 -> 35861 bytes > > doc/new-book/images/multicast-routing.png | Bin 0 -> 44923 bytes > > doc/new-book/images/path-redundancy-01.png | Bin 0 -> 47995 bytes > > doc/new-book/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 > > doc/new-book/images/sharded-queue-01.png | Bin 0 -> 28383 bytes > > doc/new-book/images/sharded-queue-02.png | Bin 0 -> 62233 bytes > > doc/new-book/introduction.adoc | 124 ++++ > > doc/new-book/logging.adoc | 346 +++++++++ > > doc/new-book/management-entities.adoc | 24 + > > doc/new-book/management.adoc | 38 + > > doc/new-book/managing-using-qdmanage.adoc | 671 > ++++++++++++++++++ > > doc/new-book/monitoring-using-qdstat.adoc | 392 +++++++++++ > > doc/new-book/policy.adoc | 366 ++++++++++ > > doc/new-book/reliability.adoc | 701 > +++++++++++++++++++ > > doc/new-book/revision-info.adoc | 20 + > > doc/new-book/routing.adoc | 693 ++++++++++++++++++ > > .../technical-details-specifications.adoc | 190 +++++ > > doc/new-book/theory_of_operation.adoc | 344 +++++++++ > > .../understand-router-configuration.adoc | 206 ++++++ > > doc/new-book/using-console.adoc | 126 ++++ > > 43 files changed, 5306 insertions(+) > > ---------------------------------------------------------------------- > > > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/common/fragment-starting-router-step.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/common/fragment-starting-router-step.adoc > b/doc/common/fragment-starting-router-step.adoc > > new file mode 100644 > > index 0000000..4e9117b > > --- /dev/null > > +++ b/doc/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: > > + > > +[options="nowrap"] > > +---- > > +$ qdrouterd -d > > +---- > > +-- > > \ No newline at end of file > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/attributes.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/attributes.adoc b/doc/new-book/attributes.adoc > > new file mode 100644 > > index 0000000..6492bff > > --- /dev/null > > +++ b/doc/new-book/attributes.adoc > > @@ -0,0 +1,75 @@ > > +//// > > +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 > > +:RouterVersion: 0.8 > > + > > +// Book names > > + > > +:RouterBook: Using {RouterLongName} > > + > > +// Doc links > > + > > +:BookUrlBase: https://qpid.apache.org/releases/qpid-dispatch-0.8.0 > > + > > +:ManagementEntitiesUrl: {BookUrlBase}/man/managementschema.html > > +:ManagementEntitiesLink: link:{ManagementEntitiesUrl}[{RouterName} > Management Schema] > > + > > +:RouterBookUrl: {BookUrlBase}/book/book.html > > +:RouterBookLink: link:{RouterBookUrl}[{RouterBook}] > > + > > +:qdmanageManPageUrl: {BookUrlBase}/man/qdmanage.html > > +:qdmanageManPageLink: link:{qdmanageManPageUrl}[qdmanage man page] > > + > > +:qdrouterdManPageUrl: {BookUrlBase}/man/qdrouterd.html > > +:qdrouterdManPageLink: link:{qdrouterdManPageUrl}[qdrouterd man page] > > + > > +:qdstatManPageUrl: {BookUrlBase}/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/ > 2f192d0a/doc/new-book/book.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/book.adoc b/doc/new-book/book.adoc > > new file mode 100644 > > index 0000000..f84a1c2 > > --- /dev/null > > +++ b/doc/new-book/book.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 > > +//// > > + > > +include::attributes.adoc[] > > + > > += {RouterBook} > > + > > +// Introduction > > +include::introduction.adoc[leveloffset=+1] > > + > > +// Theory of Operation > > +include::theory_of_operation.adoc[leveloffset=+1] > > + > > +// Getting Started > > +include::getting-started.adoc[leveloffset=+1] > > + > > +// Configuration > > +include::understand-router-configuration.adoc[leveloffset=+1] > > + > > +// Network Connections > > +include::configuration-connections.adoc[leveloffset=+1] > > + > > +// Security > > +include::configuration-security.adoc[leveloffset=+1] > > + > > +// Routing > > +include::routing.adoc[leveloffset=+1] > > + > > +// Logging > > +include::logging.adoc[leveloffset=+1] > > + > > +// Policies > > +include::policy.adoc[leveloffset=+1] > > + > > +// Management > > +include::management.adoc[leveloffset=+1] > > + > > +// Reliability > > +include::reliability.adoc[leveloffset=+1] > > + > > +// Technical Details and Specifications > > +include::technical-details-specifications.adoc[leveloffset=+1] > > + > > +[appendix] > > +include::cyrus-sasl.adoc[leveloffset=+1] > > + > > +[appendix] > > +include::configuration-reference.adoc[leveloffset=+1] > > + > > +// Revision information > > +include::revision-info.adoc[] > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/common > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/common b/doc/new-book/common > > new file mode 120000 > > index 0000000..8332399 > > --- /dev/null > > +++ b/doc/new-book/common > > @@ -0,0 +1 @@ > > +../common/ > > \ No newline at end of file > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/configuration-connections.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/configuration-connections.adoc > b/doc/new-book/configuration-connections.adoc > > new file mode 100644 > > index 0000000..eaed602 > > --- /dev/null > > +++ b/doc/new-book/configuration-connections.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 > > +//// > > + > > +[[router_network_connections]] > > += Network Connections > > + > > +Connections define how the router communicates with clients, other > routers, and brokers. You can configure _incoming connections_ to define > how the router listens for data from clients and other routers, and you can > configure _outgoing connections_ to define how the router sends data to > other routers and brokers. > > + > > +[[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. > > + > > +.Procedure > > + > > +. In the router's configuration file, add a `listener`: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +listener { > > + host: _HOST_NAME/ADDRESS_ > > + port: _PORT_NUMBER/NAME_ > > + ... > > +} > > +---- > > + > > +`host`:: Either an IP address (IPv4 or IPv6) or hostname on which the > router should listen for incoming connections. > > +`port`:: The port number or symbolic service name on which the router > should listen for incoming connections. > > + > > +For information about additional attributes, see > xref:router_configuration_file_listener[Listener] in the _Configuration > Reference_. > > +-- > > + > > +. If necessary, xref:securing_incoming_connections[secure the > connection]. > > ++ > > +If you have set up SSL/TLS or SASL in your environment, you can > configure the router to only accept encrypted or authenticated > communication on this connection. > > + > > +. If you want the router to listen for incoming connections on > additional hosts or ports, configure an additional `listener` entity for > each host and port. > > + > > +[[adding_outgoing_connections]] > > +== Adding Outgoing Connections > > + > > +Configuring outgoing connections involves setting the host and port on > which the router should connect to other routers and brokers. > > + > > +.Procedure > > + > > +. In the router's configuration file, add a `connector`: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +connector { > > + name: _NAME_ > > + host: _HOST_NAME/ADDRESS_ > > + port: _PORT_NUMBER/NAME_ > > + ... > > +} > > +---- > > + > > +`name`:: The name of the `connector`. You should specify a name that > describes the entity to which the connector connects. This name is used by > configured addresses (for example, a `linkRoute` entity) in order to > specify which connection should be used for them. > > +`host`:: Either an IP address (IPv4 or IPv6) or hostname on which the > router should connect. > > +`port`:: The port number or symbolic service name on which the router > should connect. > > + > > +For information about additional attributes, see > xref:router_configuration_file_connector[Connector] in the _Configuration > Reference_. > > +-- > > + > > +. If necessary, xref:securing_outgoing_connections[secure the > connection]. > > ++ > > +If you have set up SSL/TLS or SASL in your environment, you can > configure the router to only send encrypted or authenticated communication > on this connection. > > + > > +. For each remaining router or broker to which this router should > connect, configure an additional `connector` entity. > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/configuration-reference.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/configuration-reference.adoc > b/doc/new-book/configuration-reference.adoc > > new file mode 100644 > > index 0000000..6ccbd16 > > --- /dev/null > > +++ b/doc/new-book/configuration-reference.adoc > > @@ -0,0 +1,224 @@ > > +//// > > +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 > > +//// > > + > > +[[router_configuration_reference]] > > + > > +// This config reference could stand to be cleaned up. Also, some of > the introductory content is no longer necessary since it's covered in the > introductory chapter about configuration. We should just link to it instead > of repeating it here. > > + > > += Configuration Reference > > + > > +The {RouterName} component behavior is totally configurable using a > configuration file which can be passed as parameter (with the `--conf` > option) on the command line when running it. After installation, a default > configuration file is placed at the following path : > > + > > +[options="nowrap"] > > +---- > > +[install-prefix]/etc/qpid-dispatch/qdrouterd.conf > > +---- > > + > > +This file is used when the router is started without specify > configuration file path on the command line and when it is started as a > service. In case of starting router on the command line the configuration > file can be placed anywhere on the file system. > > + > > +== Configuration File > > + > > +The configuration file is made up of sections with following syntax : > > + > > +[options="nowrap"] > > +---- > > +sectionName { > > + attributeName: attributeValue > > + attributeName: attributeValue > > + ... > > +} > > +---- > > + > > +A section could be referenced by another section using its `name` > attribute. An example is the _sslProfile_ section which describes > attributes for setting SSL/TLS configuration and can be applied to one or > more _listener_ and _connector_ sections. > > + > > +[options="nowrap"] > > +---- > > +sslProfile { > > + name: ssl-profile-one > > + certDb: ca-certificate-1.pem > > + certFile: server-certificate-1.pem > > + keyFile: server-private-key.pem > > +} > > + > > +listener { > > + sslProfile: ssl-profile-one > > + host: 0.0.0.0 > > + port: amqp > > + saslMechanisms: ANONYMOUS > > +} > > +---- > > + > > +In the above example, the _sslProfile_ section named _ssl-profile-one_ > is used to define the _sslProfile_ attribute for the _listener_ section. > > + > > +=== Configuration Sections > > + > > +[[router_configuration_file_sslprofile]] > > +==== sslProfile > > + > > +Attributes for setting SSL/TLS configuration for connections. > > + > > +* *_certDb_* (path) : The absolute path to the database that contains > the public certificates of trusted certificate authorities (CA). > > +* *_certFile_* (path) : The absolute path to the file containing the > PEM-formatted public certificate to be used on the local end of any > connections using this profile. > > +* *_keyFile_* (path) : The absolute path to the file containing the > PEM-formatted private key for the above certificate. > > +* *_passwordFile_* (path) : If the above private key is password > protected, this is the absolute path to a file containing the password that > unlocks the certificate key. > > +* *_password_* (string) : An alternative to storing the password in a > file referenced by passwordFile is to supply the password right here in the > configuration file. This option can be used by supplying the password in > the ‘password’ option. Don’t use both password and passwordFile in the same > profile. > > +* *_uidFormat_* (string) : A list of x509 client certificate fields > that will be used to build a string that will uniquely identify the client > certificate owner. For example, a value of ‘cou’ indicates that the uid > will consist of c - common name concatenated with o - organization-company > name concatenated with u - organization unit; or a value of ‘oF’ indicates > that the uid will consist of o (organization name) concatenated with F (the > sha256 fingerprint of the entire certificate) . Allowed values can be any > combination of comma separated ‘c’( ISO3166 two character country code), > ‘s’(state or province), ‘l’(Locality; generally - city), ‘o’(Organization - > Company Name), ‘u’(Organization Unit - typically certificate type or > brand), ‘n’(CommonName - typically a username for client certificates) and > ‘1’(sha1 certificate fingerprint, as displayed in the fingerprints section > when looking at a certificate with say a web browser is the hash of the > entire > > certificate) and 2 (sha256 certificate fingerprint) and 5 (sha512 > certificate fingerprint). > > +* *_displayNameFile_* (string) : The absolute path to the file > containing the unique id to display name mapping. > > +* *_name_* (string) : The name of the profile used for referencing it > from _listener_ and _connector_ sections. > > + > > +*Used by* : _listener_, _connector_. > > + > > +[[router_configuration_file_router]] > > +==== router > > + > > +Describe main information about the router related to identity, > internal processes and inter routers communication. > > + > > + > > +* *_id_* (string) : Router’s unique identity. It is required and the > router will fail to start without it. > > +* *_mode_* (One of [`standalone`, `interior`], default=`standalone`) : > In standalone mode, the router operates as a single component. It does not > participate in the routing protocol and therefore will not cooperate with > other routers. In interior mode, the router operates in cooperation with > other interior routers in an interconnected network. > > +* *_helloInterval_* (integer, default=`1`) : Interval in seconds > between HELLO messages sent to neighbor routers in order to announce its > presence (as a keep alive). > > +* *_helloMaxAge_* (integer, default=`3`) : Time in seconds after which > a neighbor router is declared lost if no HELLO is received. > > +* *_raInterval_* (integer, default=`30`) : Interval in seconds between > Router-Advertisements sent to all routers in a stable network. > > +* *_raIntervalFlux_* (integer, default=`4`) : Interval in seconds > between Router-Advertisements sent to all routers during topology > fluctuations. > > +* *_remoteLsMaxAge_* (integer, default=`60`) : Time in seconds after > which link state is declared stale if no RA is received. > > +* *_workerThreads_* (integer, default=`4`) : The number of threads that > will be created to process message traffic and other application work > (timers, non-amqp file descriptors, and so on). > > +* *_debugDump_* (path) : The absolute path for a file to dump debugging > information that can’t be logged normally. > > +* *_saslConfigPath_* (path) : The absolute path to the SASL > configuration file. > > +* *_saslConfigName_* (string, default=`qdrouterd`) : Name of the SASL > configuration. This string + ‘.conf’ is the name of the configuration file. > > + > > +[[router_configuration_file_listener]] > > +==== listener > > + > > +Listens for incoming connections to the router. > > + > > +* *_host_* (string, default=`127.0.0.1`) : IP address: ipv4 or ipv6 > literal or a hostname. > > +* *_port_* (string, default=`amqp`) : Port number or symbolic service > name. > > +* *_protocolFamily_* (One of [`IPv4`, `IPv6`]) : IPv4: Internet > Protocol version 4; IPv6: Internet Protocol version 6. If not specified, > the protocol family will be automatically determined from the address. > > +* *_role_* (One of [`normal`, `inter-router`, `route-container`], > default=`normal`) : The role of an established connection. In the normal > role, the connection is assumed to be used for AMQP clients that are doing > normal message delivery over the connection. In the inter-router role, 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. The route-container role can be used for router-container > connections, for example, a router-broker connection. > > +* *_cost_* (integer, default=`1`) : For the `inter-route` role only. > This value assigns a cost metric to the inter-router connection. The > default (and minimum) value is one. Higher values represent higher costs. > The cost is used to influence the routing algorithm as it attempts to use > the path with the lowest total cost from ingress to egress. > > +* *_saslMechanisms_* (string) : Space separated list of accepted SASL > authentication mechanisms. > > +* *_authenticatePeer_* (boolean) : yes: Require the peer’s identity to > be authenticated; no: Do not require any authentication. > > +* *_requireEncryption_* (boolean) : yes: Require the connection to the > peer to be encrypted; no: Permit non-encrypted communication with the peer. > It is related to SASL mechanisms which support encryption. > > +* *_requireSsl_* (boolean) : yes: Require the use of SSL/TLS on the > connection; no: Allow clients to connect without SSL/TLS. > > +* *_trustedCerts_* (path) : This optional setting can be used to reduce > the set of available CAs for client authentication. If used, this setting > must provide an absolute path to a PEM file that contains the trusted > certificates. > > +* *_maxFrameSize_* (integer, default=`16384`) : Defaults to 16384. If > specified, it is the maximum frame size in octets that will be used in the > connection-open negotiation with a connected peer. The frame size is the > largest contiguous set of uninterrupted data that can be sent for a message > delivery over the connection. Interleaving of messages on different links > is done at frame granularity. > > +* *_idleTimeoutSeconds_* : (integer, default=`16`) : The idle timeout, > in seconds, for connections through this listener. If no frames are > received on the connection for this time interval, the connection shall be > closed. > > +* *_stripAnnotations_* (One of [`in`, `out`, `both`, `no`], > default=`both`) : in: Strip the dispatch router specific annotations only > on ingress; out: Strip the dispatch router specific annotations only on > egress; both: Strip the dispatch router specific annotations on both > ingress and egress; no - do not strip dispatch router specific annotations. > > +* *_linkCapacity_* (integer) : The capacity of links within this > connection, in terms of message deliveries. The capacity is the number of > messages that can be in-flight concurrently for each link. > > +* *_sslProfile_* (string) : The name of the _sslProfile_ entity to use > in order to have SSL/TLS configuration. > > +* *_http_* (boolean): If set to `yes`, the listener will accept HTTP > connections using AMQP over WebSockets. > > + > > +[[router_configuration_file_connector]] > > +==== connector > > + > > +Establishes an outgoing connection from the router. > > + > > +* *_name_* (string) : Name using to reference the connector in the > configuration file for example for a link routing to queue on a broker. > > +* *_host_* (string, default=`127.0.0.1`) : IP address: ipv4 or ipv6 > literal or a hostname. > > +* *_port_* (string, default=`amqp`) : Port number or symbolic service > name. > > +* *_protocolFamily_* (One of [`IPv4`, `IPv6`]) : IPv4: Internet > Protocol version 4; IPv6: Internet Protocol version 6. If not specified, > the protocol family will be automatically determined from the address. > > +* *_role_* (One of [`normal`, `inter-router`, `route-container`], > default=`normal`) : The role of an established connection. In the normal > role, the connection is assumed to be used for AMQP clients that are doing > normal message delivery over the connection. In the inter-router role, 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 role can be used for router-container > connections, for example, a router-broker connection. > > +* *_cost_* (integer, default=`1`) : For the ‘inter-router’ role only. > This value assigns a cost metric to the inter-router connection. The > default (and minimum) value is one. Higher values represent higher costs. > The cost is used to influence the routing algorithm as it attempts to use > the path with the lowest total cost from ingress to egress. > > +* *_saslMechanisms_* (string) : Space separated list of accepted SASL > authentication mechanisms. > > +* *_allowRedirect_* (boolean, default=True) : Allow the peer to > redirect this connection to another address. > > +* *_maxFrameSize_* (integer, default=`65536`) : Maximum frame size in > octets that will be used in the connection-open negotiation with a > connected peer. The frame size is the largest contiguous set of > uninterrupted data that can be sent for a message delivery over the > connection. Interleaving of messages on different links is done at frame > granularity. > > +* *_idleTimeoutSeconds_* (integer, default=`16`) : The idle timeout, in > seconds, for connections through this connector. If no frames are received > on the connection for this time interval, the connection shall be closed. > > +* *_stripAnnotations_* (One of [`in`, `out`, `both`, `no`], > default=`both`) : in: Strip the dispatch router specific annotations only > on ingress; out: Strip the dispatch router specific annotations only on > egress; both: Strip the dispatch router specific annotations on both > ingress and egress; no - do not strip dispatch router specific annotations. > > +* *_linkCapacity_* (integer) : The capacity of links within this > connection, in terms of message deliveries. The capacity is the number of > messages that can be in-flight concurrently for each link. > > +* *_verifyHostName_* (boolean, default=True) : yes: Ensures that when > initiating a connection (as a client) the hostname in the URL to which this > connector connects to matches the hostname in the digital certificate that > the peer sends back as part of the SSL/TLS connection; no: Does not perform > hostname verification > > +* *_saslUsername_* (string) : The username that the connector is using > to connect to a peer. > > +* *_saslPassword_* (string) : The password that the connector is using > to connect to a peer. > > +* *_sslProfile_* (string) : The name of the _sslProfile_ entity to use > in order to have SSL/TLS configuration. > > + > > +[[router_configuration_file_log]] > > +==== log > > + > > +Configure logging for a particular module which is part of the router. > You can use the UPDATE operation to change log settings while the router is > running. > > + > > +* *_module_* (One of [`ROUTER`, `ROUTER_CORE`, `ROUTER_HELLO`, > `ROUTER_LS`, `ROUTER_MA`, `MESSAGE`, `SERVER`, `AGENT`, `CONTAINER`, > `ERROR`, `POLICY`, `DEFAULT`], required) : Module to configure. The special > module `DEFAULT` specifies defaults for all modules. > > +* *_enable_* (string, default=`default`, required) Levels are: `trace`, > `debug`, `info`, `notice`, `warning`, `error`, `critical`. The enable > string is a comma-separated list of levels. A level may have a trailing `+` > to enable that level and above. For example `trace,debug,warning+` means > enable trace, debug, warning, error and critical. The value ‘none’ means > disable logging for the module. The value `default` means use the value > from the `DEFAULT` module. > > +* *_timestamp_* (boolean) : Include timestamp in log messages. > > +* *_source_* (boolean) : Include source file and line number in log > messages. > > +* *_output_* (string) : Where to send log messages. Can be `stderr`, > `syslog` or a file name. > > + > > +[[router_configuration_file_address]] > > +==== address > > + > > +Entity type for address configuration. This is used to configure the > treatment of message-routed deliveries within a particular address-space. > The configuration controls distribution and address phasing. > > + > > +* *_prefix_* (string, required) : The address prefix for the configured > settings. > > +* *_distribution_* (One of [`multicast`, `closest`, `balanced`], > default=`balanced`) : Treatment of traffic associated with the address. > > +* *_waypoint_* (boolean) : Designates this address space as being used > for waypoints. This will cause the proper address-phasing to be used. > > +* *_ingressPhase_* (integer) : Advanced - Override the ingress phase > for this address. > > +* *_egressPhase_* (integer) : Advanced - Override the egress phase for > this address. > > + > > +[[router_configuration_file_linkroute]] > > +==== linkRoute > > + > > +Entity type for link-route configuration. This is used to identify > remote containers that shall be destinations for routed link-attaches. The > link-routing configuration applies to an addressing space defined by a > prefix. > > + > > +* *_prefix_* (string, required) : The address prefix for the configured > settings. > > +* *_containerId_* (string) : it specifies that the link route will be > activated if a remote container will provide a container-id matching with > this value. > > +* *_connection_* (string) : The name from a connector or listener. > > +* *_distribution_* (One of [`linkBalanced`], default=`linkBalanced`) : > Treatment of traffic associated with the address. > > +* *_dir_* (One of [`in`, `out`], required) : The permitted direction of > links. It is defined from a router point of view so ‘in’ means client > senders (router ingress) and ‘out’ means client receivers (router egress). > > + > > +[[router_configuration_file_autolink]] > > +==== autoLink > > + > > +Entity type for configuring auto-links. Auto-links are links whose > lifecycle is managed by the router. These are typically used to attach to > waypoints on remote containers (brokers, and so on.). > > + > > +* *_addr_* (string, required) : The address of the provisioned object. > > +* *_dir_* (One of [`in`, `out`], required) : The direction of the link > to be created. In means into the router, out means out of the router. > > +* *_phase_* (integer) : The address phase for this link. Defaults to > `0` for `out` links and `1` for `in` links. > > +* *_containerId_* (string) : ContainerID for the target container. > > +* *_connection_* (string) : The name from a connector or listener. > > + > > +==== console > > + > > +Start a websocket/tcp proxy and http file server to serve the web > console. > > + > > +* *_listener_* (string) : The name of the listener to send the proxied > tcp traffic to. > > +* *_wsport_* (integer, default=`5673`) : The port on which to listen > for websocket traffic. > > +* *_proxy_* (string) : The full path to the proxy program to run. > > +* *_home_* (string) : The full path to the html/css/js files for the > console. > > +* *_args_* (string) : Optional args to pass to the proxy program for > logging, authentication, and so on. > > + > > +==== policy > > + > > +Defines global connection limit > > + > > +* *_maximumConnections_* (integer) : Global maximum number of > concurrent client connections allowed. Zero implies no limit. This limit is > always enforced even if no other policy settings have been defined. > > +* *_enableAccessRules_* (boolean) : Enable user rule set processing and > connection denial. > > +* *_policyFolder_* (path) : The absolute path to a folder that holds > policyRuleset definition .json files. For a small system the rulesets may > all be defined in this file. At a larger scale it is better to have the > policy files in their own folder and to have none of the rulesets defined > here. All rulesets in all .json files in this folder are processed. > > +* *_defaultApplication_* (string) : Application policyRuleset to use > for connections with no open.hostname or a hostname that does not match any > existing policy. For users that don’t wish to use open.hostname or any > multi-tennancy feature, this default policy can be the only policy in > effect for the network. > > +* *_defaultApplicationEnabled_* (boolean) : Enable defaultApplication > policy fallback logic. > > + > > +==== policyRuleset > > + > > +Per application definition of the locations from which users may > connect and the groups to which users belong. > > + > > +* *_maxConnections_* (integer) : Maximum number of concurrent client > connections allowed. Zero implies no limit. > > +* *_maxConnPerUser_* (integer) : Maximum number of concurrent client > connections allowed for any single user. Zero implies no limit. > > +* *_maxConnPerHost_* (integer) : Maximum number of concurrent client > connections allowed for any remote host. Zero implies no limit. > > +* *_userGroups_* (map) : A map where each key is a user group name and > the corresponding value is a CSV string naming the users in that group. > Users who are assigned to one or more groups are deemed ‘restricted’. > Restricted users are subject to connection ingress policy and are assigned > policy settings based on the assigned user groups. Unrestricted users may > be allowed or denied. If unrestricted users are allowed to connect then > they are assigned to user group default. > > +* *_ingressHostGroups_* (map) : A map where each key is an ingress host > group name and the corresponding value is a CSV string naming the IP > addresses or address ranges in that group. IP addresses may be FQDN strings > or numeric IPv4 or IPv6 host addresses. A host range is two host addresses > of the same address family separated with a hyphen. The wildcard host > address ‘*’ represents any host address. > > +* *_ingressPolicies_* (map) : A map where each key is a user group name > and the corresponding value is a CSV string naming the ingress host group > names that restrict the ingress host for the user group. Users who are > members of the user group are allowed to connect only from a host in one of > the named ingress host groups. > > +* *_connectionAllowDefault_* (boolean) : Unrestricted users, those who > are not members of a defined user group, are allowed to connect to this > application. Unrestricted users are assigned to the ‘default’ user group > and receive ‘default’ settings. > > +* *_settings_* (map) : A map where each key is a user group name and > the value is a map of the corresponding settings for that group. > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/configuration-security.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/configuration-security.adoc > b/doc/new-book/configuration-security.adoc > > new file mode 100644 > > index 0000000..c59a35f > > --- /dev/null > > +++ b/doc/new-book/configuration-security.adoc > > @@ -0,0 +1,336 @@ > > +//// > > +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 > > +//// > > + > > +[[security_config]] > > += Security > > + > > +You can configure {RouterName} to communicate with clients, routers, > and brokers in a secure way by authenticating and encrypting the router's > connections. {RouterName} supports the following security protocols: > > + > > +* _SSL/TLS_ for certificate-based encryption and mutual authentication > > +* _SASL_ for authentication and payload encryption > > + > > +[[setting_up_ssl_for_encryption_and_authentication]] > > +== Setting Up SSL/TLS for Encryption and Authentication > > + > > +Before you can secure incoming and outgoing connections using SSL/TLS > encryption and authentication, you must first set up the SSL/TLS profile in > the router's configuration file. > > + > > +// This section assumes that you only need to set up a single SSL > profile. Are there scenarios in which customers might need multiple SSL > profiles? Would you typically use a single SSL profile for all incoming and > outgoing connections, or would you use separate profiles? > > + > > +.Prerequisites > > + > > +You must have the following files in PEM format: > > + > > +* An X.509 CA certificate (used for signing the router certificate for > the SSL/TLS server authentication feature). > > +* A private key (with or without password protection) for the router. > > +* An X.509 router certificate signed by the X.509 CA certificate. > > + > > +.Procedure > > + > > +* In the router's configuration file, add an `sslProfile` section: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +sslProfile { > > + name: _NAME_ > > + certDb: _PATH_.pem > > + certFile: _PATH_.pem > > + keyFile: _PATH_.pem > > + password: _PASSWORD/PATH_TO_PASSWORD_FILE_ > > + ... > > +} > > +---- > > + > > +`name`:: A name for the SSL/TLS profile. You can use this name to refer > to the profile from the incoming and outgoing connections. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +name: router-ssl-profile > > +---- > > + > > +`certDb`:: The absolute path to the database that contains the public > certificates of trusted certificate authorities (CA). > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +certDb: /qdrouterd/ssl_certs/ca-cert.pem > > +---- > > + > > +`certFile`:: The absolute path to the file containing the PEM-formatted > public certificate to be used on the local end of any connections using > this profile. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +certFile: /qdrouterd/ssl_certs/router-cert-pwd.pem > > +---- > > + > > +`keyFile`:: The absolute path to the file containing the PEM-formatted > private key for the above certificate. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +keyFile: /qdrouterd/ssl_certs/router-key-pwd.pem > > +---- > > + > > +`passwordFile` or `password`:: If the private key is > password-protected, you must provide the password by either specifying the > absolute path to a file containing the password that unlocks the > certificate key, or entering the password directly in the configuration > file. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +password: routerKeyPassword > > +---- > > + > > +For information about additional `sslProfile` attributes, see > xref:router_configuration_file_sslprofile[_sslProfile_] in the > _Configuration Reference_. > > +-- > > + > > +[[setting_up_sasl_for_authentication_and_payload_encryption]] > > +== Setting Up SASL for Authentication and Payload Encryption > > + > > +If you plan to use SASL to authenticate connections, you must first add > the SASL attributes to the `router` entity in the router's configuration > file. These attributes define a set of SASL parameters that can be used by > the router's incoming and outgoing connections. > > + > > +// Do we need to say something here about only supporting Cyrus SASL? > > + > > +.Prerequisites > > + > > +Before you can set up SASL, you must have the following: > > + > > +* xref:generating_sasl_database[The SASL database is generated.] > > +* xref:configuring_sasl_database[The SASL configuration file is > configured.] > > + > > +.Procedure > > + > > +* In the router's configuration file, add the following attributes to > the `router` section: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +router { > > + ... > > + saslConfigPath: _PATH_ > > + saslConfigName: _FILE_NAME_ > > +} > > +---- > > + > > +`saslConfigPath`:: The absolute path to the SASL configuration file. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +saslConfigPath: /qdrouterd/security > > +---- > > + > > +`saslConfigName`:: The name of the SASL configuration file. This name > should _not_ include the `.conf` file extension. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +saslConfigName: qdrouterd_sasl > > +---- > > +-- > > + > > +[[securing_incoming_connections]] > > +== Securing Incoming Connections > > + > > +You can secure incoming connections by configuring each connection's > `listener` entity for encryption, authentication, or both. > > + > > +.Prerequisites > > + > > +Before securing incoming connections, the security protocols you plan > to use should be set up. > > + > > +.Choices > > + > > +* xref:adding_ssl_encryption_to_incoming_connection[Add SSL/TLS > encryption] > > +* xref:adding_sasl_authentication_to_incoming_connection[Add SASL > authentication] > > +* xref:adding_ssl_client_authentication_to_incoming_connection[Add > SSL/TLS client authentication] > > +* xref:adding_sasl_payload_encryption_to_incoming_connection[Add SASL > payload encryption] > > + > > +[[adding_ssl_encryption_to_incoming_connection]] > > +=== Adding SSL/TLS Encryption to an Incoming Connection > > + > > +You can configure an incoming connection to accept encrypted > connections only. By adding SSL/TLS encryption, to connect to this router, > a remote peer must first start an SSL/TLS handshake with the router and be > able to validate the server certificate received by the router during the > handshake. > > + > > +.Procedure > > + > > +* In the router's configuration file, add the following attributes to > the connection's `listener` entity: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +listener { > > + ... > > + sslProfile: _SSL_PROFILE_NAME_ > > + requireSsl: yes > > +} > > +---- > > + > > +`sslProfile`:: The name of the SSL/TLS profile you set up. > > + > > +`requireSsl`:: Enter `yes` to require all clients connecting to the > router on this connection to use encryption. > > +-- > > + > > +[[adding_sasl_authentication_to_incoming_connection]] > > +=== Adding SASL Authentication to an Incoming Connection > > + > > +You can configure an incoming connection to authenticate the client > using SASL. You can use SASL authentication with or without SSL/TLS > encryption. > > + > > +.Procedure > > + > > +* In the router's configuration file, add the following attributes to > the connection's `listener` section: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +listener { > > + ... > > + authenticatePeer: yes > > + saslMechanisms: _MECHANISMS_ > > +} > > +---- > > + > > +`authenticatePeer`:: Set this attribute to `yes` to require the router > to authenticate the identity of a remote peer before it can use this > incoming connection. > > + > > +`saslMechanisms`:: The SASL authentication mechanism (or mechanisms) to > use for peer authentication. You can choose any of the Cyrus SASL > authentication mechanisms _except_ for `ANONYMOUS`. To specify multiple > authentication mechanisms, separate each mechanism with a space. > > ++ > > +For a full list of supported Cyrus SASL authentication mechanisms, see > link:https://www.cyrusimap.org/sasl/sasl/authentication_ > mechanisms.html[Authentication Mechanisms^]. > > +-- > > + > > +[[adding_ssl_client_authentication_to_incoming_connection]] > > +=== Adding SSL/TLS Client Authentication to an Incoming Connection > > + > > +You can configure an incoming connection to authenticate the client > using SSL/TLS. > > + > > +The base SSL/TLS configuration provides content encryption and server > authentication, which means that remote peers can verify the router's > identity, but the router cannot verify a peer's identity. > > + > > +However, you can require an incoming connection to use SSL/TLS client > authentication, which means that remote peers must provide an additional > certificate to the router during the SSL/TLS handshake. By using this > certificate, the router can verify the client's identity without using a > username and password. > > + > > +You can use SSL/TLS client authentication with or without SASL > authentication. > > + > > +.Procedure > > + > > +* In the router's configuration, file, add the following attribute to > the connection's `listener` entity: > > ++ > > +-- > > +[options="nowrap"] > > +---- > > +listener { > > + ... > > + authenticatePeer: yes > > +} > > +---- > > + > > +`authenticatePeer`:: Set this attribute to `yes` to require the router > to authenticate the identity of a remote peer before it can use this > incoming connection. > > +-- > > + > > +[[adding_sasl_payload_encryption_to_incoming_connection]] > > +=== Adding SASL Payload Encryption to an Incoming Connection > > + > > +If you do not use SSL/TLS, you can still encrypt the incoming > connection by using SASL payload encryption. > > + > > +.Procedure > > + > > +* In the router's configuration file, add the following attributes to > the connection's `listener` section: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +listener { > > + ... > > + requireEncryption: yes > > + saslMechanisms: _MECHANISMS_ > > +} > > +---- > > + > > +`requireEncryption`:: Set this attribute to `yes` to require the router > to use SASL payload encryption for the connection. > > + > > +`saslMechanisms`:: The SASL mechanism to use. You can choose any of the > Cyrus SASL authentication mechanisms. To specify multiple authentication > mechanisms, separate each mechanism with a space. > > ++ > > +For a full list of supported Cyrus SASL authentication mechanisms, see > link:https://www.cyrusimap.org/sasl/sasl/authentication_ > mechanisms.html[Authentication Mechanisms^]. > > +-- > > + > > +[[securing_outgoing_connections]] > > +== Securing Outgoing Connections > > + > > +You can secure outgoing connections by configuring each connection's > `connector` entity for encryption, authentication, or both. > > + > > +.Prerequisites > > + > > +Before securing outgoing connections, the security protocols you plan > to use should be set up. > > + > > +.Choices > > + > > +* xref:adding_ssl_authentication_to_outgoing_connection[Add SSL/TLS > authentication] > > +* xref:adding_sasl_authentication_to_outgoing_connection[Add SASL > authentication] > > + > > +[[adding_ssl_authentication_to_outgoing_connection]] > > +=== Adding SSL/TLS Client Authentication to an Outgoing Connection > > + > > +If an outgoing connection connects to an external client configured > with mutual authentication, you should ensure that the outgoing connection > is configured to provide the external client with a valid security > certificate during the SSL/TLS handshake. > > + > > +You can use SSL/TLS client authentication with or without SASL > authentication. > > + > > +.Procedure > > + > > +* In the router's configuration file, add the `sslProfile` attribute to > the connection's `connector` entity: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +connector { > > + ... > > + sslProfile: _SSL_PROFILE_NAME_ > > +} > > +---- > > + > > +`sslProfile`:: The name of the SSL/TLS profile you set up. > > +-- > > + > > +[[adding_sasl_authentication_to_outgoing_connection]] > > +=== Adding SASL Authentication to an Outgoing Connection > > + > > +You can configure an outgoing connection to provide authentication > credentials to the external container. You can use SASL authentication with > or without SSL/TLS encryption. > > + > > +.Procedure > > + > > +* In the router's configuration file, add the `saslMechanisms` > attribute to the connection's `connector` entity: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +connector { > > + ... > > + saslMechanisms: _MECHANISMS_ > > + saslUsername: _USERNAME_ > > + saslPassword: _PASSWORD_ > > +} > > +---- > > + > > +`saslMechanisms`:: One or more SASL mechanisms to use to authenticate > the router to the external container. You can choose any of the Cyrus SASL > authentication mechanisms. To specify multiple authentication mechanisms, > separate each mechanism with a space. > > ++ > > +For a full list of supported Cyrus SASL authentication mechanisms, see > link:https://www.cyrusimap.org/sasl/sasl/authentication_ > mechanisms.html[Authentication Mechanisms^]. > > +`saslUsername`:: If any of the SASL mechanisms uses username/password > authentication, then provide the username to connect to the external > container. > > +`saslPassword`:: If any of the SASL mechanisms uses username/password > authentication, then provide the password to connect to the external > container. > > +-- > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/cyrus-sasl.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/cyrus-sasl.adoc b/doc/new-book/cyrus-sasl.adoc > > new file mode 100644 > > index 0000000..6d510d6 > > --- /dev/null > > +++ b/doc/new-book/cyrus-sasl.adoc > > @@ -0,0 +1,90 @@ > > +//// > > +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 > > +//// > > + > > +[[cyrus_sasl]] > > += Using Cyrus SASL to Provide Authentication > > + > > +// Just doing some basic editing for now; for future releases, this > content will need some more work. Also need to determine if it should be > moved from an appendix to the section that deals with setting up SASL. > > + > > +{RouterName} uses the Cyrus SASL library for SASL authentication. > Therefore, if you want to use SASL, you must set up the Cyrus SASL database > and configure it. > > + > > +[[generating_sasl_database]] > > +== Generating a SASL Database > > + > > +To generate a SASL database to store credentials, enter the following > command: > > + > > +[options="nowrap",subs="+quotes"] > > +---- > > +# saslpasswd2 -c -f _SASL_DATABASE_NAME_.sasldb -u _DOMAIN_NAME_ > _USER_NAME_ > > +---- > > + > > +This command creates or updates the specified SASL database, and adds > the specified user name to it. The command also prompts you for the user > name's password. > > + > > +// What is the goal here - to add user credentials to the database? If > so, do you need to run this command for every user that you want to add? > When it says that the command prompts for the password, does that mean you > use the prompt to set the user's password? > > + > > +The full user name is the user name you entered plus the domain name > (`__USER_NAME__`@`__DOMAIN_NAME__`). Providing a domain name is not > required when you add a user to the database, but if you do not provide > one, a default domain will be added automatically (the hostname of the > machine on which the tool is running). For example, in the command above, > the full user name would be `[email protected]`. > > + > > +== Viewing Users in a SASL Database > > + > > +To view the user names stored in the SASL database: > > + > > +[options="nowrap",subs="+quotes"] > > +---- > > +# sasldblistusers2 -f qdrouterd.sasldb > > [email protected]: __PASSWORD__ > > [email protected]: __PASSWORD__ > > +---- > > + > > +[[configuring_sasl_database]] > > +== Configuring a SASL Database > > + > > +To use the SASL database to provide authentication in {RouterName}: > > + > > +. Open the `/etc/sasl2/qdrouterd.conf` configuration file. > > + > > +. Set the following attributes: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +pwcheck_method: auxprop > > +auxprop_plugin: sasldb > > +sasldb_path: __SASL_DATABASE_NAME__ > > +mech_list: __MECHANISM1 ...__ > > +---- > > + > > +`sasldb_path`:: The name of the SASL database to use. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +sasldb_path: qdrouterd.sasldb > > +---- > > + > > +`mech_list`:: The SASL mechanisms to enable for authentication. To add > multiple mechanisms, separate each entry with a space. > > ++ > > +For example: > > ++ > > +[options="nowrap"] > > +---- > > +mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN > > +---- > > +// Where can users find a list of supported mechanisms? > > +-- > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/getting-started.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/getting-started.adoc b/doc/new-book/getting- > started.adoc > > new file mode 100644 > > index 0000000..6c899d2 > > --- /dev/null > > +++ b/doc/new-book/getting-started.adoc > > @@ -0,0 +1,156 @@ > > +//// > > +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 > > +//// > > + > > +[[getting_started]] > > += Getting Started > > + > > +Before configuring {RouterName}, you should understand how to start the > router, how it is configured by default, and how to use it in a simple > peer-to-peer configuration. > > + > > +[[starting_the_router]] > > +== Starting the Router > > + > > +.Procedure > > + > > +// Step 1 for starting the router. > > +include::{FragmentDir}/fragment-starting-router-step.adoc[] > > ++ > > +[NOTE] > > +==== > > +You can specify a different configuration file with which to start the > router. For more information, see > xref:methods_for_changing_router_configuration[_Changing > a Router's Configuration_]. > > +==== > > ++ > > +The router starts, using the default configuration file stored at > `/etc/qpid-dispatch/qdrouterd.conf`. > > + > > +. View the log to verify the router status: > > ++ > > +[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 // <1> > > +Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone > mode // <2> > > +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 // <3> > > +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 // <4> > > +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 > // <5> > > +---- > > +<1> The name of this router instance. > > +<2> By default, the router starts in _standalone_ mode, which means > that it cannot connect to other routers or be used in a router network. > > +<3> The management agent. It provides the `$management` address, > through which management tools such as `qdmanage` and `qdstat` can perform > create, read, update, and delete (CRUD) operations on the router. As an > AMQP endpoint, the management agent supports all operations defined by the > link:https://www.oasis-open.org/committees/download.php/ > 54441/AMQP%20Management%20v1.0%20WD09[AMQP management specification > (Draft 9)]. > > +<4> A listener is started on all available network interfaces and > listens for connections on the standard AMQP port (5672, which is not > encrypted). > > +<5> Threads for handling message traffic and all other internal > operations. > > + > > +== Routing Messages in a Peer-to-Peer Configuration > > + > > +// XXX Calling this peer-to-peer poses some problems. It's also > > +// technically client-server in this instance, and most people think > > +// those two things are exclusive. > > + > > +This example demonstrates how the router can connect clients by > receiving and sending messages between them. It uses the router's default > configuration file and does not require a broker. > > + > > +.Peer-to-peer Communication > > +image::01-peer-to-peer.png[Peer-to-peer Communication, align="center"] > > + > > +As the diagram indicates, the configuration consists of an {RouterName} > component 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 example, so there is no _"store and > forward"_ mechanism in the middle. Instead, the messages flow from sender > to receiver only if the receiver is online, and the sender can confirm that > the messages have arrived at their destination. > > + > > +This example uses a {ClientAmqpPythonName} client to start a receiver > client, and then send five messages from the sender client. > > + > > +.Prerequisites > > + > > +{ClientAmqpPythonName} must be installed before you can complete the > peer-to-peer routing example. For more information, see > {ClientAmqpPythonUrl}. > > + > > +.Procedure > > + > > +. xref:starting_the_receiver_client[Start the receiver client]. > > +. xref:sending_messages[Send messages]. > > + > > +[[starting_the_receiver_client]] > > +=== Starting the Receiver Client > > + > > +In this example, the receiver client is started first. This means that > the messages will be sent as soon as the sender client is started. > > + > > +[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. > > +==== > > + > > +.Procedure > > + > > +* To start the receiver by using the Python receiver client, navigate > to the Python examples directory and run the `simple_recv.py` example: > > ++ > > +-- > > +[options="nowrap",subs="+quotes"] > > +---- > > +$ cd __INSTALL_DIR__/examples/python/ > > +$ python simple_recv.py -a 127.0.0.1:5672/examples -m 5 > > +---- > > + > > +This command starts the receiver and listens on the default address (` > 127.0.0.1:5672/examples` <http://127.0.0.1:5672/examples%60>). The > receiver is also set to receive a maximum of five messages. > > +-- > > + > > +[[sending_messages]] > > +=== Sending Messages > > + > > +After starting the receiver client, you can send messages from the > sender. These messages will travel through the router to the receiver. > > + > > +.Procedure > > + > > +* In a new terminal window, navigate to the Python examples directory > and run the `simple_send.py` example: > > ++ > > +-- > > +[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 default address > (`127.0.0.1:5672/examples` <http://127.0.0.1:5672/examples%60>) and then > confirms that they were delivered and acknowledged by the receiver: > > + > > +[options="nowrap"] > > +---- > > +all messages confirmed > > +---- > > + > > +The receiver client receives the messages and displays their content: > > + > > +[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/ > 2f192d0a/doc/new-book/images/01-peer-to-peer.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/01-peer-to-peer.png > b/doc/new-book/images/01-peer-to-peer.png > > new file mode 100644 > > index 0000000..5c834aa > > Binary files /dev/null and b/doc/new-book/images/01-peer-to-peer.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/balanced-routing.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/balanced-routing.png > b/doc/new-book/images/balanced-routing.png > > new file mode 100644 > > index 0000000..fedcdbf > > Binary files /dev/null and b/doc/new-book/images/balanced-routing.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/brokered-messaging.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/brokered-messaging.png > b/doc/new-book/images/brokered-messaging.png > > new file mode 100644 > > index 0000000..ae129d4 > > Binary files /dev/null and b/doc/new-book/images/brokered-messaging.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/closest-routing.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/closest-routing.png > b/doc/new-book/images/closest-routing.png > > new file mode 100644 > > index 0000000..ba3f0a5 > > Binary files /dev/null and b/doc/new-book/images/closest-routing.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console1.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console1.png b/doc/new-book/images/ > console1.png > > new file mode 100644 > > index 0000000..f131884 > > Binary files /dev/null and b/doc/new-book/images/console1.png differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_charts.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_charts.png > b/doc/new-book/images/console_charts.png > > new file mode 100644 > > index 0000000..169c2ca > > Binary files /dev/null and b/doc/new-book/images/console_charts.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_entity.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_entity.png > b/doc/new-book/images/console_entity.png > > new file mode 100644 > > index 0000000..130c7e7 > > Binary files /dev/null and b/doc/new-book/images/console_entity.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_login.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_login.png > b/doc/new-book/images/console_login.png > > new file mode 100644 > > index 0000000..63e22c6 > > Binary files /dev/null and b/doc/new-book/images/console_login.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_overview.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_overview.png > b/doc/new-book/images/console_overview.png > > new file mode 100644 > > index 0000000..af25f36 > > Binary files /dev/null and b/doc/new-book/images/console_overview.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_schema.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_schema.png > b/doc/new-book/images/console_schema.png > > new file mode 100644 > > index 0000000..ba56c7b > > Binary files /dev/null and b/doc/new-book/images/console_schema.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/console_topology.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/console_topology.png > b/doc/new-book/images/console_topology.png > > new file mode 100644 > > index 0000000..ae4b22a > > Binary files /dev/null and b/doc/new-book/images/console_topology.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/link-routing.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/link-routing.png > b/doc/new-book/images/link-routing.png > > new file mode 100644 > > index 0000000..0c1b9e4 > > Binary files /dev/null and b/doc/new-book/images/link-routing.png differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/message-routing.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/message-routing.png > b/doc/new-book/images/message-routing.png > > new file mode 100644 > > index 0000000..42f4638 > > Binary files /dev/null and b/doc/new-book/images/message-routing.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/multicast-routing.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/multicast-routing.png > b/doc/new-book/images/multicast-routing.png > > new file mode 100644 > > index 0000000..d4548a6 > > Binary files /dev/null and b/doc/new-book/images/multicast-routing.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/path-redundancy-01.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/path-redundancy-01.png > b/doc/new-book/images/path-redundancy-01.png > > new file mode 100644 > > index 0000000..ba8f10d > > Binary files /dev/null and b/doc/new-book/images/path-redundancy-01.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/path-redundancy-02.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/path-redundancy-02.png > b/doc/new-book/images/path-redundancy-02.png > > new file mode 100644 > > index 0000000..6d4a1f5 > > Binary files /dev/null and b/doc/new-book/images/path-redundancy-02.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/path-redundancy-temp-decoupling-01.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/path-redundancy-temp-decoupling-01.png > b/doc/new-book/images/path-redundancy-temp-decoupling-01.png > > new file mode 100644 > > index 0000000..c3c6631 > > Binary files /dev/null and b/doc/new-book/images/path- > redundancy-temp-decoupling-01.png differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/path-redundancy-temp-decoupling-02.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/path-redundancy-temp-decoupling-02.png > b/doc/new-book/images/path-redundancy-temp-decoupling-02.png > > new file mode 100644 > > index 0000000..ecab8b1 > > Binary files /dev/null and b/doc/new-book/images/path- > redundancy-temp-decoupling-02.png differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/sharded-queue-01.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/sharded-queue-01.png > b/doc/new-book/images/sharded-queue-01.png > > new file mode 100644 > > index 0000000..ab25be0 > > Binary files /dev/null and b/doc/new-book/images/sharded-queue-01.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/images/sharded-queue-02.png > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/images/sharded-queue-02.png > b/doc/new-book/images/sharded-queue-02.png > > new file mode 100644 > > index 0000000..7e73e6d > > Binary files /dev/null and b/doc/new-book/images/sharded-queue-02.png > differ > > > > http://git-wip-us.apache.org/repos/asf/qpid-dispatch/blob/ > 2f192d0a/doc/new-book/introduction.adoc > > ---------------------------------------------------------------------- > > diff --git a/doc/new-book/introduction.adoc b/doc/new-book/introduction. > adoc > > new file mode 100644 > > index 0000000..2f2655b > > --- /dev/null > > +++ b/doc/new-book/introduction.adoc > > @@ -0,0 +1,124 @@ > > +//// > > +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 > > +//// > > + > > +[[introduction]] > > += Introduction > > + > > +[[overview]] > > +== Overview > > + > > +The {RouterName} is an AMQP message router that provides > > +advanced interconnect capabilities. It allows flexible routing of > > +messages between any AMQP-enabled endpoints, whether they be clients, > > +servers, brokers or any other entity that can send or receive standard > > +AMQP messages. > > + > > +A messaging client can make a single AMQP connection into a messaging > > +bus built of {RouterName} routers and, over that connection, exchange > > +messages with one or more message brokers, and at the same time exchange > > +messages directly with other endpoints without involving a broker at > > +all. > > + > > +The router is an intermediary for messages but it is _not_ a broker. It > > +does not _take responsibility for_ messages. It will, however, propagate > > +settlement and disposition across a network such that delivery > > +guarantees are met. In other words: the router network will deliver the > > +message, possibly via several intermediate routers, _and_ it will route > > +the acknowledgement of that message by the ultimate receiver back across > > +the same path. This means that _responsibility_ for the message is > > +transfered from the original sender to the ultimate receiver __as if > > +they were directly connected__. However this is done via a flexible > > +network that allows highly configurable routing of the message > > +transparent to both sender and receiver. > > + > > +There are some patterns where this enables "brokerless messaging" > > +approaches that are preferable to brokered approaches. In other cases a > > +broker is essential (in particular where you need the separation of > > +responsibility and/or the buffering provided by store-and-forward) but a > > +dispatch network can still be useful to tie brokers and clients together > > +into patterns that are difficult with a single broker. > > + > > +For a "brokerless" example, consider the common brokered implementation > > +of the request-response pattern, a client puts a request on a queue and > > +then waits for a reply on another queue. In this case the broker can be > > +a hindrance - the client may want to know immediately if there is nobody > > +to serve the request, but typically it can only wait for a timeout to > > +discover this. With a {RouterName} network, the client can be informed > > +immediately if its message cannot be delivered because nobody is > > +listening. When the client receives acknowledgement of the request it > > +knows not just that it is sitting on a queue, but that it has actually > > +been received by the server. > > + > > +For an exampe of using {RouterName} to enhance the use of brokers, > consider > > +using an array of brokers to implement a scalable distributed work > > +queue. A dispatch network can make this appear as a single queue, with > > +senders publishing to a single address and receivers subscribing to a > > +single address. The dispatch network can distribute work to any broker > > +in the array and collect work from any broker for any receiver. Brokers > > +can be shut down or added without affecting clients. This elegantly > > +solves the common difficulty of "stuck messages" when implementing this > > +pattern with brokers alone. If a receiver is connected to a broker that > > +has no messages, but there are messages on another broker, you have to > > +somehow transfer them or leave them "stuck". With a {RouterName} > network, > > +_all_ the receivers are connected to _all_ the brokers. If there is a > > +message anywhere it can be delivered to any receiver. > > + > > +{RouterName} is meant to be deployed in topologies of multiple routers, > > +preferably with redundant paths. It uses link-state routing protocols > > +and algorithms (similar to OSPF or IS-IS from the networking world) to > > +calculate the best path from every point to every other point and to > > +recover quickly from failures. It does not need to use clustering for > > +high availability; rather, it relies on redundant paths to provide > > +continued connectivity in the face of system or network failure. Because > > +it never takes responsibility for messages it is effectively stateless. > > +Messages not delivered to their final destination will not be > > +acknowledged to the sender and therefore the sender can re-send such > > +messages if it is disconnected from the network. > > + > > +[[benefits]] > > +== Benefits > > + > > +Simplifies connectivity > > + > > +* An endpoint can do all of its messaging through a single transport > > +connection > > +* Avoid opening holes in firewalls for incoming connections > > + > > +Provides messaging connectivity where there is no TCP/IP connectivity > > + > > +* A server or broker can be in a private IP network (behind a NAT > > +firewall) and be accessible by messaging endpoints in other networks > > +(learn more). > > + > > +Simplifies reliability > > + > > +* Reliability and availability are provided using redundant topology, > > +not server clustering > > +* Reliable end-to-end messaging without persistent stores > > +* Use a message broker only when you need store-and-forward semantics > > + > > +[[features]] > > +== Features > > + > > +* Can be deployed stand-alone or in a network of routers > > +** Supports arbitrary network topology - no restrictions on redundancy > > ++ > > +- Automatic route computation - adjusts quickly to changes in topology > > +* Provides remote access to brokers or other AMQP servers > > +* Security > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
