qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ted Ross <tr...@redhat.com>
Subject Re: [4/4] qpid-dispatch git commit: NO-JIRA - Add new book dir for dispatch router book; contribute doc improvements This closes #200
Date Thu, 28 Sep 2017 12:09:40 GMT
Is there any other way to rebase a pull request then, other than requesting
that the author rebase it for you?  If we don't do this, the history of
master becomes a jumble of splits and merges.

-Ted

On Wed, Sep 27, 2017 at 12:52 PM, Robbie Gemmell <robbie.gemmell@gmail.com>
wrote:

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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message