On 27 September 2017 at 16:07, Ganesh Murthy <[email protected]> wrote: > 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 >
Yep. The slight difference here is that although both the branches in question are actually publicly visible, by being in different repositories its effectively the same situation as a private branch when viewed from the main repo perspective. The commit reference will actually work when viewed in the GitHub UI however (along with the PR reference). >> >> 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] >> >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
