My comment wasnt around whether you rebase a PR or not (I also prefer that they are), just that we shouldnt use the -x option if doing a cherry-pick, since the additional info using -x adds doesnt make sense for the main repo if the original commit isn't in there too (which for PRs it isnt, as they only exist on the mirror).
If a PR doesnt align to the current head then you can do a bunch of things such as ask the author to rebase it, rebase it yourself and merge it with a 'this closes #' note (with or without using a seperate merge commit), skip an actual rebase and just cherry-pick the commits directly and ensure a ''this closes #' note in a commit , or merge it as-is with a 'this closes #' note in the merge commit and accept the non-linear history. Robbie On 28 September 2017 at 13:09, Ted Ross <[email protected]> wrote: > 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 <[email protected]> > wrote: > >> 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] >> >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
