Is there any other way to rebase a pull request then, other than requesting that the author rebase it for you? If we don't do this, the history of master becomes a jumble of splits and merges.
-Ted On Wed, Sep 27, 2017 at 12:52 PM, Robbie Gemmell <robbie.gemm...@gmail.com> wrote: > On 27 September 2017 at 16:07, Ganesh Murthy <gmur...@redhat.com> wrote: > > On Wed, Sep 27, 2017 at 10:56 AM, Robbie Gemmell < > robbie.gemm...@gmail.com> > > 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, <tr...@apache.org> 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 <bhard...@redhat.com> > >> > Authored: Fri Sep 1 14:46:31 2017 -0400 > >> > Committer: Ted Ross <tr...@redhat.com> > >> > 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 `us...@domain.com`. > >> > + > >> > +== Viewing Users in a SASL Database > >> > + > >> > +To view the user names stored in the SASL database: > >> > + > >> > +[options="nowrap",subs="+quotes"] > >> > +---- > >> > +# sasldblistusers2 -f qdrouterd.sasldb > >> > +us...@domain.com: __PASSWORD__ > >> > +us...@domain.com: __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: commits-unsubscr...@qpid.apache.org > >> > For additional commands, e-mail: commits-h...@qpid.apache.org > >> > > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org > >> For additional commands, e-mail: dev-h...@qpid.apache.org > >> > >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org > For additional commands, e-mail: dev-h...@qpid.apache.org > >
