You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jr...@apache.org on 2018/04/28 14:19:40 UTC
[4/8] qpid-site git commit: QPID-8154: Add missing images to the
Dispatch user guide; regen the master doc snapshot
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/b64809eb/input/releases/qpid-dispatch-master/user-guide/index.html.in
----------------------------------------------------------------------
diff --git a/input/releases/qpid-dispatch-master/user-guide/index.html.in b/input/releases/qpid-dispatch-master/user-guide/index.html.in
index 1f1e40a..0d7b048 100644
--- a/input/releases/qpid-dispatch-master/user-guide/index.html.in
+++ b/input/releases/qpid-dispatch-master/user-guide/index.html.in
@@ -34,53 +34,56 @@
<li><a href="#security">2.5. Security</a></li>
</ul>
</li>
-<li><a href="#getting_started">3. Getting Started</a>
+<li><a href="#getting-started">3. Getting Started</a>
<ul class="sectlevel2">
-<li><a href="#starting_the_router">3.1. Starting the Router</a></li>
+<li><a href="#starting-the-router">3.1. Starting the Router</a></li>
<li><a href="#routing_messages_in_a_peer_to_peer_configuration">3.2. Routing Messages in a Peer-to-Peer Configuration</a>
<ul class="sectlevel3">
-<li><a href="#starting_the_receiver_client">3.2.1. Starting the Receiver Client</a></li>
-<li><a href="#sending_messages">3.2.2. Sending Messages</a></li>
+<li><a href="#starting-the-receiver-client">3.2.1. Starting the Receiver Client</a></li>
+<li><a href="#sending-messages">3.2.2. Sending Messages</a></li>
</ul>
</li>
</ul>
</li>
-<li><a href="#router_configuration">4. Configuration</a>
+<li><a href="#router-configuration">4. Configuration</a>
<ul class="sectlevel2">
<li><a href="#accessing_the_router_configuration_file">4.1. Accessing the Router Configuration File</a></li>
<li><a href="#how_the_router_configuration_file_is_structured">4.2. How the Router Configuration File is Structured</a></li>
-<li><a href="#methods_for_changing_router_configuration">4.3. Changing a Router’s Configuration</a>
+<li><a href="#methods-for-changing-router-configuration">4.3. Changing a Router’s Configuration</a>
<ul class="sectlevel3">
-<li><a href="#making_permanent_change_to_router_configuration">4.3.1. Making a Permanent Change to the Router’s Configuration</a></li>
-<li><a href="#changing_configuration_for_running_router">4.3.2. Changing the Configuration for a Running Router</a></li>
+<li><a href="#making-permanent-change-to-router-configuration">4.3.1. Making a Permanent Change to the Router’s Configuration</a></li>
+<li><a href="#changing-configuration-for-running-router">4.3.2. Changing the Configuration for a Running Router</a></li>
</ul>
</li>
<li><a href="#default_configuration_settings">4.4. Default Configuration Settings</a></li>
<li><a href="#setting_essential_configuration_properties">4.5. Setting Essential Configuration Properties</a></li>
</ul>
</li>
-<li><a href="#router_network_connections">5. Network Connections</a>
+<li><a href="#router-network-connections">5. Network Connections</a>
<ul class="sectlevel2">
-<li><a href="#adding_incoming_connections">5.1. Listening for Incoming Connections</a></li>
-<li><a href="#adding_outgoing_connections">5.2. Adding Outgoing Connections</a></li>
+<li><a href="#adding-incoming-connections">5.1. Listening for Incoming Connections</a></li>
+<li><a href="#adding-outgoing-connections">5.2. Adding Outgoing Connections</a></li>
</ul>
</li>
-<li><a href="#security_config">6. Security</a>
+<li><a href="#security-config">6. Security</a>
<ul class="sectlevel2">
-<li><a href="#setting_up_ssl_for_encryption_and_authentication">6.1. Setting Up SSL/TLS for Encryption and Authentication</a></li>
-<li><a href="#setting_up_sasl_for_authentication_and_payload_encryption">6.2. Setting Up SASL for Authentication and Payload Encryption</a></li>
-<li><a href="#securing_incoming_connections">6.3. Securing Incoming Connections</a>
+<li><a href="#authenticating_remote_peers">6.1. Authenticating Remote Peers</a>
<ul class="sectlevel3">
-<li><a href="#adding_ssl_encryption_to_incoming_connection">6.3.1. Adding SSL/TLS Encryption to an Incoming Connection</a></li>
-<li><a href="#adding_sasl_authentication_to_incoming_connection">6.3.2. Adding SASL Authentication to an Incoming Connection</a></li>
-<li><a href="#adding_ssl_client_authentication_to_incoming_connection">6.3.3. Adding SSL/TLS Client Authentication to an Incoming Connection</a></li>
-<li><a href="#adding_sasl_payload_encryption_to_incoming_connection">6.3.4. Adding SASL Payload Encryption to an Incoming Connection</a></li>
+<li><a href="#setting-up-ssl-for-encryption-and-authentication">6.1.1. Setting Up SSL/TLS for Encryption and Authentication</a></li>
+<li><a href="#setting-up-sasl-for-authentication-and-payload-encryption">6.1.2. Setting Up SASL for Authentication and Payload Encryption</a></li>
+<li><a href="#securing-incoming-connections">6.1.3. Securing Incoming Connections</a></li>
+<li><a href="#securing-outgoing-connections">6.1.4. Securing Outgoing Connections</a></li>
+<li><a href="#integrating-with-kerberos">6.1.5. Integrating with Kerberos</a></li>
</ul>
</li>
-<li><a href="#securing_outgoing_connections">6.4. Securing Outgoing Connections</a>
+<li><a href="#authorizing_access_to_messaging_resources">6.2. Authorizing Access to Messaging Resources</a>
<ul class="sectlevel3">
-<li><a href="#adding_ssl_authentication_to_outgoing_connection">6.4.1. Adding SSL/TLS Client Authentication to an Outgoing Connection</a></li>
-<li><a href="#adding_sasl_authentication_to_outgoing_connection">6.4.2. Adding SASL Authentication to an Outgoing Connection</a></li>
+<li><a href="#types_of_policies">6.2.1. Types of Policies</a></li>
+<li><a href="#how_dispatch_router_applies_policies">6.2.2. How Dispatch Router Applies Policies</a></li>
+<li><a href="#configuring_global_policies">6.2.3. Configuring Global Policies</a></li>
+<li><a href="#configuring_vhost_policies">6.2.4. Configuring Vhost Policies</a></li>
+<li><a href="#example_configuring_a_vhost_policy">6.2.5. Example: Configuring a Vhost Policy</a></li>
+<li><a href="#example_using_a_vhost_policy_to_limit_memory_consumption_advanced">6.2.6. Example: Using a Vhost Policy to Limit Memory Consumption (Advanced)</a></li>
</ul>
</li>
</ul>
@@ -96,10 +99,10 @@
<li><a href="#configuring_message_routing">7.2. Configuring Message Routing</a>
<ul class="sectlevel3">
<li><a href="#addresses_2">7.2.1. Addresses</a></li>
-<li><a href="#routing_patterns_overview">7.2.2. Routing Patterns</a></li>
+<li><a href="#routing-patterns-overview">7.2.2. Routing Patterns</a></li>
<li><a href="#message_settlement_2">7.2.3. Message Settlement</a></li>
-<li><a href="#routing_messages_between_clients">7.2.4. Routing Messages Between Clients</a></li>
-<li><a href="#routing_messages_through_broker">7.2.5. Routing Messages Through a Broker Queue</a></li>
+<li><a href="#routing-messages-between-clients">7.2.4. Routing Messages Between Clients</a></li>
+<li><a href="#routing-messages-through-broker">7.2.5. Routing Messages Through a Broker Queue</a></li>
<li><a href="#example_routing_messages_through_broker_queues">7.2.6. Example: Routing Messages Through Broker Queues</a></li>
</ul>
</li>
@@ -108,7 +111,7 @@
<li><a href="#link_route_addresses_2">7.3.1. Link Route Addresses</a></li>
<li><a href="#link_route_routing_patterns">7.3.2. Link Route Routing Patterns</a></li>
<li><a href="#link_route_flow_control">7.3.3. Link Route Flow Control</a></li>
-<li><a href="#creating_link_route">7.3.4. Creating a Link Route</a></li>
+<li><a href="#creating-link-route">7.3.4. Creating a Link Route</a></li>
<li><a href="#example_using_a_link_route_to_provide_client_isolation">7.3.5. Example: Using a Link Route to Provide Client Isolation</a></li>
</ul>
</li>
@@ -116,7 +119,7 @@
</li>
<li><a href="#logging">8. Logging</a>
<ul class="sectlevel2">
-<li><a href="#logging_modules_you_can_configure">8.1. Logging Modules</a>
+<li><a href="#logging-modules-you-can-configure">8.1. Logging Modules</a>
<ul class="sectlevel3">
<li><a href="#the_code_default_code_logging_module">8.1.1. The <code>DEFAULT</code> Logging Module</a></li>
<li><a href="#the_code_router_code_logging_module">8.1.2. The <code>ROUTER</code> Logging Module</a></li>
@@ -132,7 +135,7 @@
<li><a href="#the_code_policy_code_logging_module">8.1.12. The <code>POLICY</code> Logging Module</a></li>
</ul>
</li>
-<li><a href="#configure_default_logging">8.2. Configuring Logging</a></li>
+<li><a href="#configure-default-logging">8.2. Configuring Logging</a></li>
<li><a href="#viewing_log_entries">8.3. Viewing Log Entries</a>
<ul class="sectlevel3">
<li><a href="#viewing_log_entries_on_the_console">8.3.1. Viewing Log Entries on the Console</a></li>
@@ -141,112 +144,66 @@
</li>
</ul>
</li>
-<li><a href="#policy">9. Policy</a>
+<li><a href="#management">9. Management</a>
<ul class="sectlevel2">
-<li><a href="#definitions">9.1. Definitions</a>
+<li><a href="#using_apache_qpid_dispatch_router_console">9.1. Using Apache Qpid Dispatch Router Console</a>
<ul class="sectlevel3">
-<li><a href="#vhost">9.1.1. vhost</a></li>
+<li><a href="#console-overview">9.1.1. Console Overview</a></li>
+<li><a href="#console-installation">9.1.2. Console Installation</a></li>
+<li><a href="#console-operation">9.1.3. Console Operation</a></li>
</ul>
</li>
-<li><a href="#policy_features">9.2. Policy Features</a>
+<li><a href="#monitoring-using-qdstat">9.2. Monitoring Dispatch Router Using <code>qdstat</code></a>
<ul class="sectlevel3">
-<li><a href="#total_connection_limit">9.2.1. Total Connection Limit</a></li>
-<li><a href="#vhost_policy">9.2.2. Vhost Policy</a></li>
-<li><a href="#default_vhost">9.2.3. Default Vhost</a></li>
+<li><a href="#syntax_for_using_code_qdstat_code">9.2.1. Syntax for Using <code>qdstat</code></a></li>
+<li><a href="#viewing_general_statistics_for_a_router">9.2.2. Viewing General Statistics for a Router</a></li>
+<li><a href="#viewing_a_list_of_connections_to_a_router">9.2.3. Viewing a List of Connections to a Router</a></li>
+<li><a href="#viewing_amqp_links_attached_to_a_router">9.2.4. Viewing AMQP Links Attached to a Router</a></li>
+<li><a href="#viewing_known_routers_on_a_network">9.2.5. Viewing Known Routers on a Network</a></li>
+<li><a href="#viewing_addresses_known_to_a_router">9.2.6. Viewing Addresses Known to a Router</a></li>
+<li><a href="#viewing_a_router_s_autolinks">9.2.7. Viewing a Router’s Autolinks</a></li>
+<li><a href="#viewing_the_status_of_a_router_s_link_routes">9.2.8. Viewing the Status of a Router’s Link Routes</a></li>
+<li><a href="#viewing_memory_consumption_information">9.2.9. Viewing Memory Consumption Information</a></li>
</ul>
</li>
-<li><a href="#policy_schema">9.3. Policy Schema</a>
+<li><a href="#managing-router">9.3. Managing Dispatch Router Using <code>qdmanage</code></a>
<ul class="sectlevel3">
-<li><a href="#global_policy">9.3.1. Global Policy</a></li>
-<li><a href="#vhost_policy_2">9.3.2. Vhost Policy</a></li>
-<li><a href="#vhost_user_group_settings_map">9.3.3. Vhost User Group Settings Map</a></li>
+<li><a href="#syntax_for_using_code_qdmanage_code">9.3.1. Syntax for Using <code>qdmanage</code></a></li>
+<li><a href="#managing_network_connections">9.3.2. Managing Network Connections</a></li>
+<li><a href="#managing_security">9.3.3. Managing Security</a></li>
+<li><a href="#managing_routing">9.3.4. Managing Routing</a></li>
+<li><a href="#managing_logging">9.3.5. Managing Logging</a></li>
</ul>
</li>
-<li><a href="#policy_wildcard_and_user_name_substitution">9.4. Policy Wildcard and User Name Substitution</a>
-<ul class="sectlevel3">
-<li><a href="#remote_host_wildcard">9.4.1. Remote Host Wildcard</a></li>
-<li><a href="#amqp_source_and_target_wildcard_and_name_substitution">9.4.2. AMQP Source and Target Wildcard and Name Substitution</a></li>
-</ul>
-</li>
-<li><a href="#composing_policies">9.5. Composing Policies</a>
-<ul class="sectlevel3">
-<li><a href="#example_1_user_policy_disabled">9.5.1. Example 1. User Policy Disabled</a></li>
-<li><a href="#example2">9.5.2. Example 2. All Users Have Simple Connection Limits</a></li>
-<li><a href="#example_3_admins_must_connect_from_localhost">9.5.3. Example 3. Admins Must Connect From Localhost</a></li>
-<li><a href="#example_4_limiting_possible_memory_consumption">9.5.4. Example 4. Limiting Possible Memory Consumption</a></li>
-</ul>
-</li>
-</ul>
-</li>
-<li><a href="#management">10. Management</a>
-<ul class="sectlevel2">
-<li><a href="#using_apache_qpid_dispatch_router_console">10.1. Using Apache Qpid Dispatch Router Console</a>
-<ul class="sectlevel3">
-<li><a href="#console-overview">10.1.1. Console Overview</a></li>
-<li><a href="#console-installation">10.1.2. Console Installation</a></li>
-<li><a href="#console-operation">10.1.3. Console Operation</a></li>
-</ul>
-</li>
-<li><a href="#monitoring_using_qdstat">10.2. Monitoring Dispatch Router Using <code>qdstat</code></a>
-<ul class="sectlevel3">
-<li><a href="#syntax_for_using_code_qdstat_code">10.2.1. Syntax for Using <code>qdstat</code></a></li>
-<li><a href="#viewing_general_statistics_for_a_router">10.2.2. Viewing General Statistics for a Router</a></li>
-<li><a href="#viewing_a_list_of_connections_to_a_router">10.2.3. Viewing a List of Connections to a Router</a></li>
-<li><a href="#viewing_amqp_links_attached_to_a_router">10.2.4. Viewing AMQP Links Attached to a Router</a></li>
-<li><a href="#viewing_known_routers_on_a_network">10.2.5. Viewing Known Routers on a Network</a></li>
-<li><a href="#viewing_addresses_known_to_a_router">10.2.6. Viewing Addresses Known to a Router</a></li>
-<li><a href="#viewing_a_router_s_autolinks">10.2.7. Viewing a Router’s Autolinks</a></li>
-<li><a href="#viewing_the_status_of_a_router_s_link_routes">10.2.8. Viewing the Status of a Router’s Link Routes</a></li>
-<li><a href="#viewing_memory_consumption_information">10.2.9. Viewing Memory Consumption Information</a></li>
-</ul>
-</li>
-<li><a href="#managing_router">10.3. Managing Dispatch Router Using <code>qdmanage</code></a>
-<ul class="sectlevel3">
-<li><a href="#syntax_for_using_code_qdmanage_code">10.3.1. Syntax for Using <code>qdmanage</code></a></li>
-<li><a href="#managing_network_connections">10.3.2. Managing Network Connections</a></li>
-<li><a href="#managing_security">10.3.3. Managing Security</a></li>
-<li><a href="#managing_routing">10.3.4. Managing Routing</a></li>
-<li><a href="#managing_logging">10.3.5. Managing Logging</a></li>
+<li><a href="#management_entities">9.4. Management Entities</a></li>
</ul>
</li>
-<li><a href="#management_entities">10.4. Management Entities</a></li>
-</ul>
-</li>
-<li><a href="#reliability">11. Reliability</a>
+<li><a href="#reliability">10. Reliability</a>
<ul class="sectlevel2">
-<li><a href="#path_redundancy">11.1. Path Redundancy</a></li>
-<li><a href="#path_redundancy_and_temporal_decoupling">11.2. Path Redundancy and Temporal Decoupling</a></li>
-<li><a href="#sharded_queue">11.3. Sharded Queue</a></li>
+<li><a href="#path_redundancy">10.1. Path Redundancy</a></li>
+<li><a href="#path_redundancy_and_temporal_decoupling">10.2. Path Redundancy and Temporal Decoupling</a></li>
+<li><a href="#sharded_queue">10.3. Sharded Queue</a></li>
</ul>
</li>
-<li><a href="#technical_details_specifications">12. Technical Details and Specifications</a>
+<li><a href="#technical-details-specifications">11. Technical Details and Specifications</a>
<ul class="sectlevel2">
-<li><a href="#client_compatibility">12.1. Client Compatibility</a></li>
-<li><a href="#amqp_mapping">12.2. AMQP Mapping</a>
+<li><a href="#client-compatibility">11.1. Client Compatibility</a></li>
+<li><a href="#amqp-mapping">11.2. AMQP Mapping</a>
<ul class="sectlevel3">
-<li><a href="#message_annotations">12.2.1. Message Annotations</a></li>
-<li><a href="#sourcetarget_capabilities">12.2.2. Source/Target Capabilities</a></li>
-<li><a href="#dynamic_node_properties">12.2.3. Dynamic-Node-Properties</a></li>
-<li><a href="#addresses_and_address_formats">12.2.4. Addresses and Address Formats</a></li>
-<li><a href="#implementation_of_the_amqp_management_specification">12.2.5. Implementation of the AMQP Management Specification</a></li>
+<li><a href="#message-annotations">11.2.1. Message Annotations</a></li>
+<li><a href="#sourcetarget-capabilities">11.2.2. Source/Target Capabilities</a></li>
+<li><a href="#dynamic-node-properties">11.2.3. Dynamic-Node-Properties</a></li>
+<li><a href="#addresses-and-address-formats">11.2.4. Addresses and Address Formats</a></li>
+<li><a href="#implementation-of-the-amqp-management-specification">11.2.5. Implementation of the AMQP Management Specification</a></li>
</ul>
</li>
</ul>
</li>
-<li><a href="#cyrus_sasl">Appendix A: Using Cyrus SASL to Provide Authentication</a>
+<li><a href="#cyrus-sasl">Appendix A: Using Cyrus SASL to Provide Authentication</a>
<ul class="sectlevel2">
-<li><a href="#generating_sasl_database">A.1. Generating a SASL Database</a></li>
+<li><a href="#generating-sasl-database">A.1. Generating a SASL Database</a></li>
<li><a href="#viewing_users_in_a_sasl_database">A.2. Viewing Users in a SASL Database</a></li>
-<li><a href="#configuring_sasl_database">A.3. Configuring a SASL Database</a></li>
-</ul>
-</li>
-<li><a href="#router_configuration_reference">Appendix B: Configuration Reference</a>
-<ul class="sectlevel2">
-<li><a href="#configuration_file">B.1. Configuration File</a>
-<ul class="sectlevel3">
-<li><a href="#configuration_sections">B.1.1. Configuration Sections</a></li>
-</ul>
-</li>
+<li><a href="#configuring-sasl-database">A.3. Configuring a SASL Database</a></li>
</ul>
</li>
</ul>
@@ -756,32 +713,86 @@ used. Address semantics include the following considerations:</p>
<div class="sect3">
<h4 id="routing_patterns">2.4.1. Routing Patterns</h4>
<div class="paragraph">
-<p>Routing patterns define the paths that a message with a mobile address can take across a network. These routing patterns can be used for both direct routing, in which the router distributes messages between clients without a broker, and indirect routing, in which the router enables clients to exchange messages through a broker.</p>
+<p>Routing patterns define the paths that a message with a mobile address
+can take across a network. These routing patterns can be used for both
+direct routing, in which the router distributes messages between
+clients without a broker, and indirect routing, in which the router
+enables clients to exchange messages through a broker.</p>
+</div>
+<div class="paragraph">
+<p>Note that the routing patterns fall into two categories: Anycast
+(Balanced and Closest) and Multicast. There is no concept of
+"unicast" in which there is only one consumer for an address.</p>
+</div>
+<div class="paragraph">
+<p>Anycast distribution delivers each message to one consumer whereas
+multicast distribution delivers each message to all consumers.</p>
+</div>
+<div class="paragraph">
+<p>Anycast delivery is reliable when the message deliveries are
+unsettled. There is a reliability contract that the router network
+abides by when delivering unsettled messages to anycast addresses.
+For every such delivery sent by a producer, the router network
+guarantees that one of the following outcomes will occur:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The delivery shall be settled with ACCEPTED or REJECTED disposition
+where the disposition is supplied by the consumer.</p>
+</li>
+<li>
+<p>The delivery shall be settled with RELEASED disposition, meaning
+that the message was not delivered to any consumer.</p>
+</li>
+<li>
+<p>The delivery shall be settled with MODIFIED disposition, meaning
+that the message may have been delivered to a consumer but should be
+considered in-doubt and re-sent.</p>
+</li>
+<li>
+<p>The connection to the producer shall be dropped, signifying that all
+unsettled deliveries should now be considered in-doubt by the
+producer and later re-sent.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Multicast delivery is not reliable. If a producer sends an unsettled
+delivery, the ingress router shall settle the delivery with ACCEPTED
+disposition regardless of whether the message was delivered to any
+consumers.</p>
+</div>
+<div class="sect4">
+<h5 id="balanced">Balanced</h5>
+<div class="paragraph">
+<p>An anycast method which allows multiple receivers to use the same
+address. In this case, messages (or links) are routed to exactly one
+of the receivers and the network attempts to balance the traffic load
+across the set of receivers using the same address. This routing
+delivers messages to receivers based on how quickly they settle the
+deliveries. Faster receivers get more messages.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="closest">Closest</h5>
+<div class="paragraph">
+<p>An anycast method in which even if there are more receivers for the
+same address, every message is sent along the shortest path to reach
+the destination. This means that only one receiver will get the
+message. Each message is delivered to the closest receivers in terms
+of topology cost. If there are multiple receivers with the same lowest
+cost, deliveries will be spread evenly among those receivers.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="multicast">Multicast</h5>
+<div class="paragraph">
+<p>Having multiple consumers on the same address at the same time,
+messages are routed such that each consumer receives one copy of the
+message.</p>
+</div>
</div>
-<table class="tableblock frame-all grid-all spread">
-<colgroup>
-<col style="width: 20%;">
-<col style="width: 80%;">
-</colgroup>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Pattern</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Balanced</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">An anycast method which allows multiple receivers to use the same address. In this case, messages (or links) are routed to exactly one of the receivers and the network attempts to balance the traffic load across the set of receivers using the same address. This routing delivers messages to receivers based on how quickly they settle the deliveries. Faster receivers get more messages.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Closest</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">An anycast method in which even if there are more receivers for the same address, every message is sent along the shortest path to reach the destination. This means that only one receiver will get the message. Each message is delivered to the closest receivers in terms of topology cost. If there are multiple receivers with the same lowest cost, deliveries will be spread evenly among those receivers.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Multicast</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Having multiple consumers on the same address at the same time, messages are routed such that each consumer receives one copy of the message.</p></td>
-</tr>
-</tbody>
-</table>
</div>
<div class="sect3">
<h4 id="routing_mechanisms">2.4.2. Routing Mechanisms</h4>
@@ -917,13 +928,13 @@ control.</p>
</div>
</div>
<div class="sect1">
-<h2 id="getting_started">3. Getting Started</h2>
+<h2 id="getting-started">3. Getting Started</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Before configuring Dispatch Router, 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.</p>
</div>
<div class="sect2">
-<h3 id="starting_the_router">3.1. Starting the Router</h3>
+<h3 id="starting-the-router">3.1. Starting the Router</h3>
<div class="olist arabic">
<div class="title">Procedure</div>
<ol class="arabic">
@@ -949,7 +960,7 @@ control.</p>
</td>
<td class="content">
<div class="paragraph">
-<p>You can specify a different configuration file with which to start the router. For more information, see <a href="#methods_for_changing_router_configuration"><em>Changing a Router’s Configuration</em></a>.</p>
+<p>You can specify a different configuration file with which to start the router. For more information, see <a href="#methods-for-changing-router-configuration"><em>Changing a Router’s Configuration</em></a>.</p>
</div>
</td>
</tr>
@@ -1039,15 +1050,15 @@ messages to that address.</p>
<div class="title">Procedure</div>
<ol class="arabic">
<li>
-<p><a href="#starting_the_receiver_client">Start the receiver client</a>.</p>
+<p><a href="#starting-the-receiver-client">Start the receiver client</a>.</p>
</li>
<li>
-<p><a href="#sending_messages">Send messages</a>.</p>
+<p><a href="#sending-messages">Send messages</a>.</p>
</li>
</ol>
</div>
<div class="sect3">
-<h4 id="starting_the_receiver_client">3.2.1. Starting the Receiver Client</h4>
+<h4 id="starting-the-receiver-client">3.2.1. Starting the Receiver Client</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1088,7 +1099,7 @@ $ python simple_recv.py -a 127.0.0.1:5672/examples -m 5</pre>
</div>
</div>
<div class="sect3">
-<h4 id="sending_messages">3.2.2. Sending Messages</h4>
+<h4 id="sending-messages">3.2.2. Sending Messages</h4>
<div class="paragraph">
<p>After starting the receiver client, you can send messages from the sender. These messages will travel through the router to the receiver.</p>
</div>
@@ -1135,7 +1146,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
</div>
</div>
<div class="sect1">
-<h2 id="router_configuration">4. Configuration</h2>
+<h2 id="router-configuration">4. Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Before starting Dispatch Router, you should understand where the router’s configuration file is stored, how the file is structured, and the methods you can use to modify it.</p>
@@ -1156,7 +1167,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
<p>When Dispatch Router is installed, <code>qdrouterd.conf</code> is installed in this directory by default. When the router is started, it runs with the settings defined in this file.</p>
</div>
<div class="paragraph">
-<p>For more information about the router configuration file (including available entities and attributes), see the <a href="https://qpid.apache.org/releases/qpid-dispatch-0.8.0/man/qdrouterd.html">qdrouterd man page</a>.</p>
+<p>For more information about the router configuration file (including available entities and attributes), see the <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.html" target="_blank" rel="noopener">qdrouterd man page</a>.</p>
</div>
</div>
</div>
@@ -1183,7 +1194,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
</div>
</div>
<div class="sect2">
-<h3 id="methods_for_changing_router_configuration">4.3. Changing a Router’s Configuration</h3>
+<h3 id="methods-for-changing-router-configuration">4.3. Changing a Router’s Configuration</h3>
<div class="paragraph">
<p>You can use different methods for changing a router’s configuration based on whether the router is currently running, and whether you want the change to take effect immediately.</p>
</div>
@@ -1191,15 +1202,15 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
<div class="title">Choices</div>
<ul>
<li>
-<p><a href="#making_permanent_change_to_router_configuration">Make a permanent change to the router’s configuration</a>.</p>
+<p><a href="#making-permanent-change-to-router-configuration">Make a permanent change to the router’s configuration</a>.</p>
</li>
<li>
-<p><a href="#changing_configuration_for_running_router">Change the configuration for a running router.</a></p>
+<p><a href="#changing-configuration-for-running-router">Change the configuration for a running router.</a></p>
</li>
</ul>
</div>
<div class="sect3">
-<h4 id="making_permanent_change_to_router_configuration">4.3.1. Making a Permanent Change to the Router’s Configuration</h4>
+<h4 id="making-permanent-change-to-router-configuration">4.3.1. Making a Permanent Change to the Router’s Configuration</h4>
<div class="paragraph">
<p>You can make a permanent change to the router’s configuration by editing the router’s configuration file directly. You must restart the router for the changes to take effect, but the changes will be saved even if the router is stopped.</p>
</div>
@@ -1226,7 +1237,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
</div>
<div class="listingblock">
<div class="content">
-<pre class="nowrap"># qdrouterd -d --conf /etc/qpid-dispatch/new-configuration-file.conf</pre>
+<pre class="nowrap">$ sudo qdrouterd -d --conf /etc/qpid-dispatch/new-configuration-file.conf</pre>
</div>
</div>
</li>
@@ -1234,7 +1245,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
</div>
</div>
<div class="sect3">
-<h4 id="changing_configuration_for_running_router">4.3.2. Changing the Configuration for a Running Router</h4>
+<h4 id="changing-configuration-for-running-router">4.3.2. Changing the Configuration for a Running Router</h4>
<div class="paragraph">
<p>If the router is running, you can change its configuration on the fly. The changes you make take effect immediately, but are lost if the router is stopped.</p>
</div>
@@ -1244,7 +1255,7 @@ $ python simple_send.py -a 127.0.0.1:5672/examples -m 5</pre>
<li>
<p>Use <code>qdmanage</code> to change the configuration.</p>
<div class="paragraph">
-<p>For more information about using <code>qdmanage</code>, see <a href="#managing_router">Managing Dispatch Router Using <em>qdmanage</em></a>.</p>
+<p>For more information about using <code>qdmanage</code>, see <a href="#managing-router">Managing Dispatch Router Using <em>qdmanage</em></a>.</p>
</div>
</li>
</ul>
@@ -1388,7 +1399,7 @@ address {
</dl>
</div>
<div class="paragraph">
-<p>For information about additional attributes, see <a href="#router_configuration_file_router">Router</a> in the <em>Configuration Reference</em>.</p>
+<p>For information about additional attributes, see <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.conf.html#_router">router</a> in the <code>qdrouterd.conf</code> man page.</p>
</div>
</div>
</div>
@@ -1400,10 +1411,10 @@ address {
<div class="ulist">
<ul>
<li>
-<p><a href="#setting_up_ssl_for_encryption_and_authentication">Set up SSL/TLS for encryption, authentication, or both</a></p>
+<p><a href="#setting-up-ssl-for-encryption-and-authentication">Set up SSL/TLS for encryption, authentication, or both</a></p>
</li>
<li>
-<p><a href="#setting_up_sasl_for_authentication_and_payload_encryption">Set up SASL for authentication and payload encryption</a></p>
+<p><a href="#setting-up-sasl-for-authentication-and-payload-encryption">Set up SASL for authentication and payload encryption</a></p>
</li>
</ul>
</div>
@@ -1417,10 +1428,10 @@ address {
<div class="ulist">
<ul>
<li>
-<p><a href="#adding_incoming_connections">Add incoming connections</a></p>
+<p><a href="#adding-incoming-connections">Add incoming connections</a></p>
</li>
<li>
-<p><a href="#adding_outgoing_connections">Add outgoing connections</a></p>
+<p><a href="#adding-outgoing-connections">Add outgoing connections</a></p>
</li>
</ul>
</div>
@@ -1434,13 +1445,13 @@ address {
<div class="ulist">
<ul>
<li>
-<p><a href="#routing_messages_between_clients">Configure the router to route messages between clients directly</a></p>
+<p><a href="#routing-messages-between-clients">Configure the router to route messages between clients directly</a></p>
</li>
<li>
-<p><a href="#routing_messages_through_broker">Configure the router to route messages through a broker queue</a></p>
+<p><a href="#routing-messages-through-broker">Configure the router to route messages through a broker queue</a></p>
</li>
<li>
-<p><a href="#creating_link_route">Create a link route to define a private messaging path between endpoints</a></p>
+<p><a href="#creating-link-route">Create a link route to define a private messaging path between endpoints</a></p>
</li>
</ul>
</div>
@@ -1456,13 +1467,13 @@ address {
</div>
</div>
<div class="sect1">
-<h2 id="router_network_connections">5. Network Connections</h2>
+<h2 id="router-network-connections">5. Network Connections</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Connections define how the router communicates with clients, other routers, and brokers. You can configure <em>incoming connections</em> to define how the router listens for data from clients and other routers, and you can configure <em>outgoing connections</em> to define how the router sends data to other routers and brokers.</p>
</div>
<div class="sect2">
-<h3 id="adding_incoming_connections">5.1. Listening for Incoming Connections</h3>
+<h3 id="adding-incoming-connections">5.1. Listening for Incoming Connections</h3>
<div class="paragraph">
<p>Listening for incoming connections involves setting the host and port on which the router should listen for traffic.</p>
</div>
@@ -1495,13 +1506,13 @@ address {
</dl>
</div>
<div class="paragraph">
-<p>For information about additional attributes, see <a href="#router_configuration_file_listener">Listener</a> in the <em>Configuration Reference</em>.</p>
+<p>For information about additional attributes, see <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.conf.html#_listener">listener</a> in the <code>qdrouterd.conf</code> man page.</p>
</div>
</div>
</div>
</li>
<li>
-<p>If necessary, <a href="#securing_incoming_connections">secure the connection</a>.</p>
+<p>If necessary, <a href="#securing-incoming-connections">secure the connection</a>.</p>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1513,12 +1524,12 @@ address {
</div>
</div>
<div class="sect2">
-<h3 id="adding_outgoing_connections">5.2. Adding Outgoing Connections</h3>
+<h3 id="adding-outgoing-connections">5.2. Adding Outgoing Connections</h3>
<div class="paragraph">
<p>Configuring outgoing connections involves setting the host and port on which the router connects to other routers and brokers.</p>
</div>
<div class="paragraph">
-<p>When a router connects to a broker, the broker might provide backup connection data that the router can use if the primary connection fails. If the primary connection fails, the router attempts to reconnect by using a combination of the primary and — if provided — backup connections in round-robin fashion until the connection is successful. For more information about viewing the backup connection data provided by the broker, see <a href="#managing_connectors">Managing Connectors</a>.</p>
+<p>When a router connects to a broker, the broker might provide backup connection data that the router can use if the primary connection fails. If the primary connection fails, the router attempts to reconnect by using a combination of the primary and — if provided — backup connections in round-robin fashion until the connection is successful. For more information about viewing the backup connection data provided by the broker, see <a href="#managing-connectors">Managing Connectors</a>.</p>
</div>
<div class="olist arabic">
<div class="title">Procedure</div>
@@ -1554,13 +1565,13 @@ address {
</dl>
</div>
<div class="paragraph">
-<p>For information about additional attributes, see <a href="#router_configuration_file_connector">Connector</a> in the <em>Configuration Reference</em>.</p>
+<p>For information about additional attributes, see <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.conf.html#_connector">connector</a> in the <code>qdrouterd.conf</code> man page.</p>
</div>
</div>
</div>
</li>
<li>
-<p>If necessary, <a href="#securing_outgoing_connections">secure the connection</a>.</p>
+<p>If necessary, <a href="#securing-outgoing-connections">secure the connection</a>.</p>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1574,9 +1585,14 @@ address {
</div>
</div>
<div class="sect1">
-<h2 id="security_config">6. Security</h2>
+<h2 id="security-config">6. Security</h2>
<div class="sectionbody">
<div class="paragraph">
+<p>Securing your router network involves configuring authentication and authorization. You can authenticate and encrypt the router’s connections using SSL/TLS or SASL. Additionally, you can authorize access to messaging resources by setting user connection restrictions and defining AMQP resource access control.</p>
+</div>
+<div class="sect2">
+<h3 id="authenticating_remote_peers">6.1. Authenticating Remote Peers</h3>
+<div class="paragraph">
<p>You can configure Dispatch Router to communicate with clients, routers, and brokers in a secure way by authenticating and encrypting the router’s connections. Dispatch Router supports the following security protocols:</p>
</div>
<div class="ulist">
@@ -1589,8 +1605,8 @@ address {
</li>
</ul>
</div>
-<div class="sect2">
-<h3 id="setting_up_ssl_for_encryption_and_authentication">6.1. Setting Up SSL/TLS for Encryption and Authentication</h3>
+<div class="sect3">
+<h4 id="setting-up-ssl-for-encryption-and-authentication">6.1.1. Setting Up SSL/TLS for Encryption and Authentication</h4>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1623,9 +1639,9 @@ address {
<pre class="nowrap">sslProfile {
name: <em>NAME</em>
ciphers: <em>CIPHERS</em>
- certDb: <em>PATH</em>.pem
+ caCertFile: <em>PATH</em>.pem
certFile: <em>PATH</em>.pem
- keyFile: <em>PATH</em>.pem
+ privateKeyFile: <em>PATH</em>.pem
password: <em>PASSWORD/PATH_TO_PASSWORD_FILE</em>
...
}</pre>
@@ -1660,15 +1676,15 @@ address {
<p>To see the full list of available ciphers, use the <code>openssl ciphers</code> command. For more information about each cipher, see the <a href="https://www.openssl.org/docs/manmaster/man1/ciphers.html" target="_blank" rel="noopener">ciphers man page</a>.</p>
</div>
</dd>
-<dt class="hdlist1"><code>certDb</code></dt>
+<dt class="hdlist1"><code>caCertFile</code></dt>
<dd>
-<p>The absolute path to the database that contains the public certificates of trusted certificate authorities (CA).</p>
+<p>The absolute path to the file that contains the public certificates of trusted certificate authorities (CA).</p>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="nowrap">certDb: /qdrouterd/ssl_certs/ca-cert.pem</pre>
+<pre class="nowrap">caCertFile: /qdrouterd/ssl_certs/ca-cert.pem</pre>
</div>
</div>
</dd>
@@ -1684,7 +1700,7 @@ address {
</div>
</div>
</dd>
-<dt class="hdlist1"><code>keyFile</code></dt>
+<dt class="hdlist1"><code>privateKeyFile</code></dt>
<dd>
<p>The absolute path to the file containing the PEM-formatted private key for the above certificate.</p>
<div class="paragraph">
@@ -1692,7 +1708,7 @@ address {
</div>
<div class="listingblock">
<div class="content">
-<pre class="nowrap">keyFile: /qdrouterd/ssl_certs/router-key-pwd.pem</pre>
+<pre class="nowrap">privateKeyFile: /qdrouterd/ssl_certs/router-key-pwd.pem</pre>
</div>
</div>
</dd>
@@ -1711,7 +1727,7 @@ address {
</dl>
</div>
<div class="paragraph">
-<p>For information about additional <code>sslProfile</code> attributes, see <a href="#router_configuration_file_sslprofile"><em>sslProfile</em></a> in the <em>Configuration Reference</em>.</p>
+<p>For information about additional <code>sslProfile</code> attributes, see <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.conf.html#_sslprofile">sslProfile</a> in the <code>qdrouterd.conf</code> man page.</p>
</div>
</div>
</div>
@@ -1719,8 +1735,8 @@ address {
</ul>
</div>
</div>
-<div class="sect2">
-<h3 id="setting_up_sasl_for_authentication_and_payload_encryption">6.2. Setting Up SASL for Authentication and Payload Encryption</h3>
+<div class="sect3">
+<h4 id="setting-up-sasl-for-authentication-and-payload-encryption">6.1.2. Setting Up SASL for Authentication and Payload Encryption</h4>
<div class="paragraph">
<p>If you plan to use SASL to authenticate connections, you must first add the SASL attributes to the <code>router</code> 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.</p>
</div>
@@ -1731,10 +1747,23 @@ address {
<div class="ulist">
<ul>
<li>
-<p><a href="#generating_sasl_database">The SASL database is generated.</a></p>
+<p><a href="#generating-sasl-database">The SASL database is generated.</a></p>
</li>
<li>
-<p><a href="#configuring_sasl_database">The SASL configuration file is configured.</a></p>
+<p><a href="#configuring-sasl-database">The SASL configuration file is configured.</a></p>
+</li>
+<li>
+<p>The Cyrus SASL plugin is installed for each SASL mechanism you plan to use.</p>
+<div class="paragraph">
+<p>Cyrus SASL uses plugins to support specific SASL mechanisms. Before you can use a particular SASL mechanism, the relevant plugin must be installed. For example, you need the <code>cyrus-sasl-plain</code> plugin to use SASL PLAIN authentication.</p>
+</div>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>To see a list of Cyrus SASL plugins in a <code>dnf</code>-based Linux system, use the <code>dnf search cyrus-sasl</code> command. To install a Cyrus SASL plugin, use the <code>dnf install <em>PLUGIN</em></code> command.</p>
+</div>
+</div>
+</div>
</li>
</ul>
</div>
@@ -1749,14 +1778,14 @@ address {
<div class="content">
<pre class="nowrap">router {
...
- saslConfigPath: <em>PATH</em>
+ saslConfigDir: <em>PATH</em>
saslConfigName: <em>FILE_NAME</em>
}</pre>
</div>
</div>
<div class="dlist">
<dl>
-<dt class="hdlist1"><code>saslConfigPath</code></dt>
+<dt class="hdlist1"><code>saslConfigDir</code></dt>
<dd>
<p>The absolute path to the SASL configuration file.</p>
<div class="paragraph">
@@ -1764,7 +1793,7 @@ address {
</div>
<div class="listingblock">
<div class="content">
-<pre class="nowrap">saslConfigPath: /qdrouterd/security</pre>
+<pre class="nowrap">saslConfigDir: /qdrouterd/security</pre>
</div>
</div>
</dd>
@@ -1788,8 +1817,8 @@ address {
</ul>
</div>
</div>
-<div class="sect2">
-<h3 id="securing_incoming_connections">6.3. Securing Incoming Connections</h3>
+<div class="sect3">
+<h4 id="securing-incoming-connections">6.1.3. Securing Incoming Connections</h4>
<div class="paragraph">
<p>You can secure incoming connections by configuring each connection’s <code>listener</code> entity for encryption, authentication, or both.</p>
</div>
@@ -1801,21 +1830,21 @@ address {
<div class="title">Choices</div>
<ul>
<li>
-<p><a href="#adding_ssl_encryption_to_incoming_connection">Add SSL/TLS encryption</a></p>
+<p><a href="#adding-ssl-encryption-to-incoming-connection">Add SSL/TLS encryption</a></p>
</li>
<li>
-<p><a href="#adding_sasl_authentication_to_incoming_connection">Add SASL authentication</a></p>
+<p><a href="#adding-sasl-authentication-to-incoming-connection">Add SASL authentication</a></p>
</li>
<li>
-<p><a href="#adding_ssl_client_authentication_to_incoming_connection">Add SSL/TLS client authentication</a></p>
+<p><a href="#adding-ssl-client-authentication-to-incoming-connection">Add SSL/TLS client authentication</a></p>
</li>
<li>
-<p><a href="#adding_sasl_payload_encryption_to_incoming_connection">Add SASL payload encryption</a></p>
+<p><a href="#adding-sasl-payload-encryption-to-incoming-connection">Add SASL payload encryption</a></p>
</li>
</ul>
</div>
-<div class="sect3">
-<h4 id="adding_ssl_encryption_to_incoming_connection">6.3.1. Adding SSL/TLS Encryption to an Incoming Connection</h4>
+<div class="sect4">
+<h5 id="adding-ssl-encryption-to-incoming-connection">Adding SSL/TLS Encryption to an Incoming Connection</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -1853,8 +1882,8 @@ address {
</ul>
</div>
</div>
-<div class="sect3">
-<h4 id="adding_sasl_authentication_to_incoming_connection">6.3.2. Adding SASL Authentication to an Incoming Connection</h4>
+<div class="sect4">
+<h5 id="adding-sasl-authentication-to-incoming-connection">Adding SASL Authentication to an Incoming Connection</h5>
<div class="paragraph">
<p>You can configure an incoming connection to authenticate the client using SASL. You can use SASL authentication with or without SSL/TLS encryption.</p>
</div>
@@ -1895,8 +1924,8 @@ address {
</ul>
</div>
</div>
-<div class="sect3">
-<h4 id="adding_ssl_client_authentication_to_incoming_connection">6.3.3. Adding SSL/TLS Client Authentication to an Incoming Connection</h4>
+<div class="sect4">
+<h5 id="adding-ssl-client-authentication-to-incoming-connection">Adding SSL/TLS Client Authentication to an Incoming Connection</h5>
<div class="paragraph">
<p>You can configure an incoming connection to authenticate the client using SSL/TLS.</p>
</div>
@@ -1938,8 +1967,8 @@ address {
</ul>
</div>
</div>
-<div class="sect3">
-<h4 id="adding_sasl_payload_encryption_to_incoming_connection">6.3.4. Adding SASL Payload Encryption to an Incoming Connection</h4>
+<div class="sect4">
+<h5 id="adding-sasl-payload-encryption-to-incoming-connection">Adding SASL Payload Encryption to an Incoming Connection</h5>
<div class="paragraph">
<p>If you do not use SSL/TLS, you can still encrypt the incoming connection by using SASL payload encryption.</p>
</div>
@@ -1981,8 +2010,8 @@ address {
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="securing_outgoing_connections">6.4. Securing Outgoing Connections</h3>
+<div class="sect3">
+<h4 id="securing-outgoing-connections">6.1.4. Securing Outgoing Connections</h4>
<div class="paragraph">
<p>You can secure outgoing connections by configuring each connection’s <code>connector</code> entity for encryption, authentication, or both.</p>
</div>
@@ -1994,15 +2023,15 @@ address {
<div class="title">Choices</div>
<ul>
<li>
-<p><a href="#adding_ssl_authentication_to_outgoing_connection">Add SSL/TLS authentication</a></p>
+<p><a href="#adding-ssl-authentication-to-outgoing-connection">Add SSL/TLS authentication</a></p>
</li>
<li>
-<p><a href="#adding_sasl_authentication_to_outgoing_connection">Add SASL authentication</a></p>
+<p><a href="#adding-sasl-authentication-to-outgoing-connection">Add SASL authentication</a></p>
</li>
</ul>
</div>
-<div class="sect3">
-<h4 id="adding_ssl_authentication_to_outgoing_connection">6.4.1. Adding SSL/TLS Client Authentication to an Outgoing Connection</h4>
+<div class="sect4">
+<h5 id="adding-ssl-authentication-to-outgoing-connection">Adding SSL/TLS Client Authentication to an Outgoing Connection</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2038,8 +2067,8 @@ address {
</ul>
</div>
</div>
-<div class="sect3">
-<h4 id="adding_sasl_authentication_to_outgoing_connection">6.4.2. Adding SASL Authentication to an Outgoing Connection</h4>
+<div class="sect4">
+<h5 id="adding-sasl-authentication-to-outgoing-connection">Adding SASL Authentication to an Outgoing Connection</h5>
<div class="paragraph">
<p>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.</p>
</div>
@@ -2086,894 +2115,872 @@ address {
</div>
</div>
</div>
+<div class="sect3">
+<h4 id="integrating-with-kerberos">6.1.5. Integrating with Kerberos</h4>
+<div class="paragraph">
+<p>By using the <code>GSSAPI</code> SASL mechanism, you can configure Dispatch Router to authenticate incoming connections using Kerberos.</p>
</div>
-</div>
-<div class="sect1">
-<h2 id="routing">7. Routing</h2>
-<div class="sectionbody">
+<div class="ulist">
+<div class="title">Prerequisites</div>
+<ul>
+<li>
+<p>A Kerberos infrastructure must be deployed in your environment.</p>
+</li>
+<li>
+<p>In the Kerberos environment, a service principal of <code>amqp/<em>HOSTNAME</em>@<em>REALM</em></code> must be configured.</p>
<div class="paragraph">
-<p>Routing is the process by which messages are delivered to their destinations. To accomplish this, Dispatch Router provides two routing mechanisms: <em>message routing</em> and <em>link routing</em>.</p>
+<p>This is the service principal that Dispatch Router uses.</p>
</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">Message routing</dt>
-<dd>
-<p>Routing is performed on messages as producers send them to a router. When a message arrives on a router, the router routes the message and its <em>settlement</em> based on the message’s <em>address</em> and <em>routing pattern</em>.</p>
+</li>
+<li>
+<p>The <code>cyrus-sasl-gssapi</code> package must be installed on each client and router host machine.</p>
+</li>
+<li>
+<p><a href="#setting-up-sasl-for-authentication-and-payload-encryption">SASL must be set up for Dispatch Router</a>.</p>
+</li>
+</ul>
+</div>
+<div class="olist arabic">
+<div class="title">Procedure</div>
+<ol class="arabic">
+<li>
+<p>On the router’s host machine, open the <code>/etc/sasl2/qdrouterd.conf</code> configuration file.</p>
<div class="openblock">
<div class="content">
-<div class="imageblock" style="text-align: center">
+<div class="exampleblock">
+<div class="title">Example 1. An <code>/etc/sasl2/qdrouterd.conf</code> Configuration File</div>
<div class="content">
-<img src="images/message-routing.png" alt="Message Routing">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">pwcheck_method: auxprop
+auxprop_plugin: sasldb
+sasldb_path: qdrouterd.sasldb
+keytab: /etc/krb5.keytab
+mech_list: ANONYMOUS DIGEST-MD5 EXTERNAL PLAIN GSSAPI</pre>
</div>
-<div class="title">Figure 2. Message Routing</div>
</div>
-<div class="paragraph">
-<p>In this diagram, the message producer attaches a link to the router, and then sends a message over the link. When the router receives the message, it identifies the message’s destination based on the message’s address, and then uses its routing table to determine the best route to deliver the message either to its destination or to the next hop in the route. All dispositions (including settlement) are propagated along the same path that the original message transfer took. Flow control is handled between the sender and the router, and then between the router and the receiver.</p>
</div>
</div>
</div>
-</dd>
-<dt class="hdlist1">Link routing</dt>
-<dd>
-<p>Routing is performed on link-attach frames, which are chained together to form a virtual messaging path that directly connects a sender and receiver. Once a link route is established, the transfer of message deliveries, flow frames, and dispositions is performed across the link route.</p>
+</div>
+</li>
+<li>
+<p>Verify the following:</p>
+<div class="ulist">
+<ul>
+<li>
+<p>The <code>mech_list</code> attribute contains the <code>GSSAPI</code> mechanism.</p>
+</li>
+<li>
+<p>The <code>keytab</code> attribute points to the location of the keytab file.</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>Open the router’s configuration file.</p>
+</li>
+<li>
+<p>For each incoming connection that should use Kerberos for authentication, set the router’s <code>listener</code> to use the <code>GSSAPI</code> mechanism.</p>
<div class="openblock">
<div class="content">
-<div class="imageblock" style="text-align: center">
+<div class="exampleblock">
+<div class="title">Example 2. A <code>listener</code> in the Router Configuration File</div>
<div class="content">
-<img src="images/link-routing.png" alt="Link Routing">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">listener {
+ ...
+ authenticatePeer: yes
+ saslMechanisms: GSSAPI
+}</pre>
+</div>
+</div>
</div>
-<div class="title">Figure 3. Link Routing</div>
</div>
<div class="paragraph">
-<p>In this diagram, a router is connected to clients and to a broker, and it provides a link route to a queue on the broker (my_queue). The sender connects to the router, and the router propagates the link-attaches to the broker to form a direct link between the sender and the broker. The sender can begin sending messages to the queue, and the router passes the deliveries along the link route directly to the broker queue.</p>
+<p>For more information about these attributes, see <a href="#adding-sasl-authentication-to-incoming-connection">Adding SASL Authentication to an Incoming Connection</a>.</p>
</div>
</div>
</div>
-</dd>
-</dl>
+</li>
+</ol>
+</div>
+</div>
</div>
<div class="sect2">
-<h3 id="comparison_of_message_routing_and_link_routing">7.1. Comparison of Message Routing and Link Routing</h3>
+<h3 id="authorizing_access_to_messaging_resources">6.2. Authorizing Access to Messaging Resources</h3>
<div class="paragraph">
-<p>While you can use either message routing or link routing to deliver messages to a destination, they differ in several important ways. Understanding these differences will enable you to choose the proper routing approach for any particular use case.</p>
+<p>You can restrict the number of user connections, and control access to AMQP messaging resources by configuring <em>policies</em>.</p>
</div>
<div class="sect3">
-<h4 id="when_to_use_message_routing">7.1.1. When to Use Message Routing</h4>
+<h4 id="types_of_policies">6.2.1. Types of Policies</h4>
<div class="paragraph">
-<p>Message routing is the default routing mechanism. You can use it to route messages on a per-message basis between clients directly (direct-routed messaging), or to and from broker queues (brokered messaging).</p>
+<p>You can configure two different types of policies: <em>global policies</em> and <em>vhost policies</em>.</p>
</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Global policies</dt>
+<dd>
+<p>Settings for the router. A global policy defines the maximum number of incoming user connections for the router (across all vhost policies), and defines how the router should use vhost policies.</p>
+</dd>
+<dt class="hdlist1">Vhost policies</dt>
+<dd>
+<p>Connection and AMQP resource limits for a messaging endpoint (called an AMQP virtual host, or <em>vhost</em>). A vhost policy defines what a client can access on a messaging endpoint over a particular connection.</p>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
-<p>Message routing is best suited to the following requirements:</p>
+<p>A vhost is typically the name of the host to which the client connection is directed. For example, if a client application opens a connection to the <code>amqp://mybroker.example.com:5672/queue01</code> URL, the vhost would be <code>mybroker.example.com</code>.</p>
</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Default, basic message routing.</p>
-<div class="paragraph">
-<p>Dispatch Router automatically routes messages by default, so manual configuration is only required if you want routing behavior that is different than the default.</p>
+</td>
+</tr>
+</table>
</div>
-</li>
-<li>
-<p>Message-based routing patterns.</p>
-<div class="paragraph">
-<p>Message routing supports both anycast and multicast routing patterns. You can load-balance individual messages across multiple consumers, and multicast (or fan-out) messages to multiple subscribers.</p>
+</dd>
+</dl>
</div>
-</li>
-<li>
-<p>Sharding messages across multiple broker instances when message delivery order is not important.</p>
<div class="paragraph">
-<p>Sharding messages from one producer might cause that producer’s messages to be received in a different order than the order in which they were sent.</p>
-</div>
-</li>
-</ul>
+<p>The resource limits defined in global and vhost policies are applied to user connections only. The limits do not affect inter-router connections or router connections that are outbound to waypoints.</p>
</div>
-<div class="paragraph">
-<p>Message routing is not suitable for any of the following requirements:</p>
</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Dedicated path through the router network.</p>
+<div class="sect3">
+<h4 id="how_dispatch_router_applies_policies">6.2.2. How Dispatch Router Applies Policies</h4>
<div class="paragraph">
-<p>For inter-router transfers, all message deliveries are placed on the same inter-router link. This means that the traffic for one address might affect the delivery of the traffic for another address.</p>
+<p>Dispatch Router uses both global and vhost policies to determine whether to permit a connection, and if it is permitted, to apply the appropriate resource limits.</p>
</div>
-</li>
-<li>
-<p>Granular, end-to-end flow control.</p>
<div class="paragraph">
-<p>With message routing, end-to-end flow control is based on the settlement of deliveries and therefore might not be optimal in every case.</p>
+<p>When a client creates a connection to the router, the router first determines whether to allow or deny the connection. This decision is based on the following criteria:</p>
</div>
-</li>
+<div class="ulist">
+<ul>
<li>
-<p>Transaction support.</p>
+<p>Whether the connection will exceed the router’s global connection limit (defined in the global policy)</p>
</li>
<li>
-<p>Server-side selectors.</p>
+<p>Whether the connection will exceed the vhost’s connection limits (defined in the vhost policy that matches the host to which the connection is directed)</p>
</li>
</ul>
</div>
-</div>
-<div class="sect3">
-<h4 id="when_to_use_link_routing">7.1.2. When to Use Link Routing</h4>
<div class="paragraph">
-<p>Link routing requires more detailed configuration than message routing as well as an AMQP container that can accept incoming link-attaches (typically a broker). However, link routing enables you to satisfy more advanced use cases than message routing.</p>
+<p>If the connection is allowed, the router assigns the user (the authenticated user name from the connection) to a user group, and enforces the user group’s resource limits for the lifetime of the connection.</p>
+</div>
</div>
+<div class="sect3">
+<h4 id="configuring_global_policies">6.2.3. Configuring Global Policies</h4>
<div class="paragraph">
-<p>You can use link routing if you need to meet any of the following requirements:</p>
+<p>You can set the incoming connection limit for the router and define how it should use vhost policies by configuring a global policy.</p>
</div>
<div class="ulist">
+<div class="title">Procedure</div>
<ul>
<li>
-<p>Dedicated path through the router network.</p>
-<div class="paragraph">
-<p>With link routing, each link route has dedicated inter-router links through the network. Each link has its own dedicated message buffers, which means that the address will not have "head-of-line" blocking issues with other addresses.</p>
+<p>In the router configuration file, add a <code>policy</code> section.</p>
+<div class="openblock">
+<div class="content">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">policy = {
+ maxConnections: 10000 <b class="conum">(1)</b>
+ enableVhostPolicy: true <b class="conum">(2)</b>
+ policyDir: /etc/qpid-dispatch/policies/ <b class="conum">(3)</b>
+ defaultVhost: $default <b class="conum">(4)</b>
+}</pre>
</div>
-</li>
-<li>
-<p>Sharding messages across multiple broker instances with guaranteed delivery order.</p>
-<div class="paragraph">
-<p>Link routing to a sharded queue preserves the delivery order of the producer’s messages by causing all messages on that link to go to the same broker instance.</p>
</div>
+<div class="colist arabic">
+<ol>
+<li>
+<p>The maximum number of concurrent client connections allowed for this router. This limit is always enforced, even if no other policy settings have been defined. The limit is applied to all incoming connections regardless of remote host, authenticated user, or targeted vhost. The default (and the maximum) value is <code>65535</code>.</p>
</li>
<li>
-<p>End-to-end flow control.</p>
+<p>Enables the router to enforce the connection denials and resource limits defined in the configured vhost policies. The default is <code>false</code>, which means that the router will not enforce any vhost policies.</p>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
<div class="paragraph">
-<p>Flow control is "real" in that credits flow across the link route from the receiver to the sender.</p>
+<p>Setting <code>enableVhostPolicy</code> to <code>false</code> improves the router’s performance.</p>
+</div>
+</td>
+</tr>
+</table>
</div>
</li>
<li>
-<p>Transaction support.</p>
-<div class="paragraph">
-<p>Link routing supports local transactions to a broker.</p>
-</div>
+<p>The absolute path to a directory that holds vhost policy definition files in JSON format (<code>*.json</code>). The router processes all of the vhost policies in each JSON file that is in this directory. For more information, see <a href="#configuring-vhost-policies-json">Configuring Vhost Policies as JSON Files</a>.</p>
</li>
<li>
-<p>Server-side selectors.</p>
-<div class="paragraph">
-<p>With a link route, consumers can provide server-side selectors for broker subscriptions.</p>
+<p>The name of the default vhost policy, which is applied to any connection for which a vhost policy has not been configured. The default is <code>$default</code>. If <code>defaultVhost</code> is not defined, then default vhost processing is disabled.</p>
+</li>
+</ol>
+</div>
+</div>
</div>
</li>
</ul>
</div>
</div>
-</div>
-<div class="sect2">
-<h3 id="configuring_message_routing">7.2. Configuring Message Routing</h3>
+<div class="sect3">
+<h4 id="configuring_vhost_policies">6.2.4. Configuring Vhost Policies</h4>
<div class="paragraph">
-<p>With message routing, routing is performed on messages as producers send them to a router. When a message arrives on a router, the router routes the message and its <em>settlement</em> based on the message’s <em>address</em> and <em>routing pattern</em>.</p>
+<p>You configure vhost policies to define the connection limits and AMQP resource limits for a messaging endpoint.</p>
</div>
<div class="paragraph">
-<p>With message routing, you can do the following:</p>
+<p>A vhost policy consists of the following:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>Route messages between clients (direct-routed, or brokerless messaging)</p>
+<p>Connection limits</p>
<div class="paragraph">
-<p>This involves configuring an address with a routing pattern. All messages sent to the address will be routed based on the routing pattern.</p>
+<p>These limits control the number of users that can be connected to the vhost simultaneously.</p>
</div>
</li>
<li>
-<p>Route messages through a broker queue (brokered messaging)</p>
+<p>User groups</p>
<div class="paragraph">
-<p>This involves configuring a waypoint address to identify the broker queue and then connecting the router to the broker. All messages sent to the waypoint address will be routed to the broker queue.</p>
+<p>A user group defines the messaging resources that the group members are permitted to access. Each user group defines the following:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>A set of users that can connect to the vhost (the group members)</p>
+</li>
+<li>
+<p>The remote hosts from which the group members may connect to the router network</p>
+</li>
+<li>
+<p>The AMQP resources that the group members are permitted to access on the vhost</p>
+</li>
+</ul>
</div>
</li>
</ul>
</div>
-<div class="sect3">
-<h4 id="addresses_2">7.2.1. Addresses</h4>
<div class="paragraph">
-<p>Addresses determine how messages flow through your router network. An address designates an endpoint in your messaging network, such as:</p>
+<p>You can use the following methods to configure vhost policies:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>Endpoint processes that consume data or offer a service</p>
+<p><a href="#configuring-vhost-policies-router">Configure vhost policies directly in the router configuration file</a></p>
</li>
<li>
-<p>Topics that match multiple consumers to multiple producers</p>
+<p><a href="#configuring-vhost-policies-json">Configure vhost policies as JSON files</a></p>
</li>
+</ul>
+</div>
+<div class="sect4">
+<h5 id="configuring-vhost-policies-router">Configuring Vhost Policies in the Router Configuration File</h5>
+<div class="paragraph">
+<p>You can configure vhost policies in the router configuration file by configuring <code>vhost</code> entities. However, if multiple routers in your router network should be configured with the same vhost configuration, you will need to add the <code>vhost</code> configuration to each router’s configuration file.</p>
+</div>
+<div class="olist arabic">
+<div class="title">Procedure</div>
+<ol class="arabic">
<li>
-<p>Entities within a messaging broker:</p>
-<div class="ulist">
-<ul>
+<p>In the router configuration file, add a <code>vhost</code> section and define the connection limits for it.</p>
+<div class="openblock">
+<div class="content">
+<div class="paragraph">
+<p>The connection limits apply to all users that are connected to the vhost. These limits control the number of users that can be connected simultaneously to the vhost.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">vhost = {
+ hostname: example.com <b class="conum">(1)</b>
+ maxConnections: 10000 <b class="conum">(2)</b>
+ maxConnectionsPerUser: 1000 <b class="conum">(3)</b>
+ maxConnectionsPerHost: 1000 <b class="conum">(4)</b>
+ allowUnknownUser: false <b class="conum">(5)</b>
+ ...
+}</pre>
+</div>
+</div>
+<div class="colist arabic">
+<ol>
<li>
-<p>Queues</p>
+<p>The host name of the vhost. This vhost policy will be applied to any client connection that is directed to the hostname that you specify.</p>
</li>
<li>
-<p>Durable Topics</p>
+<p>The global maximum number of concurrent client connections allowed for this vhost. The default is <code>65535</code>.</p>
</li>
<li>
-<p>Exchanges</p>
+<p>The maximum number of concurrent client connections allowed for any user. The default is <code>65535</code>.</p>
</li>
-</ul>
-</div>
+<li>
+<p>The maximum number of concurrent client connections allowed for any remote host (the host from which the client is connecting). The default is <code>65535</code>.</p>
</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>When a router receives a message, it uses the message’s address to determine where to send the message (either its destination or one step closer to its destination).</p>
+<li>
+<p>Whether unknown users (users who are not members of a defined user group) are allowed to connect to the vhost. Unknown users are assigned to the <code>$default</code> user group and receive <code>$default</code> settings. The default is <code>false</code>, which means that unknown users are not allowed.</p>
+</li>
+</ol>
</div>
</div>
-<div class="sect3">
-<h4 id="routing_patterns_overview">7.2.2. Routing Patterns</h4>
-<div class="paragraph">
-<p>Each address has one of the following routing patterns, which define the path that a message with the address can take across the messaging network:</p>
</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">Balanced</dt>
-<dd>
-<p>An anycast method that allows multiple consumers to use the same address. Each message is delivered to a single consumer only, and Dispatch Router attempts to balance the traffic load across the router network.</p>
+</li>
+<li>
+<p>In the <code>vhost</code> section, beneath the connection settings that you added, add the necessary user groups.</p>
<div class="openblock">
<div class="content">
<div class="paragraph">
-<p>If multiple consumers are attached to the same address, each router determines which outbound path should receive a message by considering each path’s current number of unsettled deliveries. This means that more messages will be delivered along paths where deliveries are settled at higher rates.</p>
+<p>A user group defines what messaging resources the members of the group are allowed to access.</p>
</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>Dispatch Router neither measures nor uses message settlement time to determine which outbound path to use.</p>
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">vhost {
+ ...
+ groups: {
+ admin: { <b class="conum">(1)</b>
+ users: admin1, admin2 <b class="conum">(2)</b>
+ remoteHosts: 127.0.0.1, ::1 <b class="conum">(3)</b>
+ sources: * <b class="conum">(4)</b>
+ targets: * <b class="conum">(5)</b>
+ },
+ ...
+ }
+}</pre>
</div>
-</td>
-</tr>
-</table>
+</div>
+<div class="colist arabic">
+<ol>
+<li>
+<p>The name of the user group.</p>
+</li>
+<li>
+<p>A list of authenticated users for this user group. Use commas to separate multiple users. A user may belong to only one vhost user group.</p>
+</li>
+<li>
+<p>A list of remote hosts from which the users may connect. A host can be a hostname, IP address, or IP address range. Use commas to separate multiple hosts. To allow access from all remote hosts, specify a wildcard <code>*</code>. To deny access from all remote hosts, leave this attribute blank.</p>
+</li>
+<li>
+<p>A list of AMQP source addresses from which users in this group may receive messages. To specify multiple AMQP addresses, separate the addresses with either a comma or a space. If you do not specify any addresses, users in this group are not allowed to receive messages from any addresses.</p>
+<div class="paragraph">
+<p>You can use the substitution token <code>{user}</code> to specify an AMQP address that contains a user’s authenticated user name. This enables you to allow access to resources specific to each user in the user group without having to name each user individually. You can only specify the <code>{user}</code> token once in an AMQP address name. If there are multiple tokens in an address, only the leftmost token will be substituted.</p>
</div>
<div class="paragraph">
-<p>In this scenario, the messages are spread across both receivers regardless of path length:</p>
+<p>You can use an asterisk (<code>*</code>) wildcard to match one or more characters in an AMQP address. However, this wildcard is only recognized if it is the last character in the address name.</p>
</div>
-<div class="imageblock" style="text-align: center">
+<div class="exampleblock">
+<div class="title">Example 3. Allowing Access to All Addresses</div>
<div class="content">
-<img src="images/balanced-routing.png" alt="Balanced Message Routing">
-</div>
-<div class="title">Figure 4. Balanced Message Routing</div>
-</div>
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">sources: *</pre>
</div>
</div>
-</dd>
-<dt class="hdlist1">Closest</dt>
-<dd>
-<p>An anycast method in which every message is sent along the shortest path to reach the destination, even if there are other consumers for the same address.</p>
-<div class="paragraph">
-<p>Dispatch Router determines the shortest path based on the topology cost to reach each of the consumers. If there are multiple consumers with the same lowest cost, messages will be spread evenly among those consumers.</p>
</div>
-<div class="paragraph">
-<p>In this scenario, all messages sent by <code>Sender</code> will be delivered to <code>Receiver 1</code>:</p>
</div>
-<div class="imageblock" style="text-align: center">
+<div class="exampleblock">
+<div class="title">Example 4. Restricting Access to All Addresses</div>
<div class="content">
-<img src="images/closest-routing.png" alt="Closest Message Routing">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">sources:</pre>
</div>
-<div class="title">Figure 5. Closest Message Routing</div>
</div>
-</dd>
-<dt class="hdlist1">Multicast</dt>
-<dd>
-<p>Messages are sent to all consumers attached to the address. Each consumer will receive one copy of the message.</p>
-<div class="paragraph">
-<p>In this scenario, all messages are sent to all receivers:</p>
</div>
-<div class="imageblock" style="text-align: center">
+</div>
+<div class="exampleblock">
+<div class="title">Example 5. Allowing Access to Specific Addresses</div>
<div class="content">
-<img src="images/multicast-routing.png" alt="Multicast Message Routing">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">sources: myaddress01, myaddress02, myaddress03</pre>
</div>
-<div class="title">Figure 6. Multicast Message Routing</div>
</div>
-</dd>
-</dl>
</div>
</div>
-<div class="sect3">
-<h4 id="message_settlement_2">7.2.3. Message Settlement</h4>
+<div class="exampleblock">
+<div class="title">Example 6. Allowing Access to User-Specific Addresses</div>
+<div class="content">
<div class="paragraph">
-<p>Message settlement is negotiated between the producer and the router when the producer establishes a link to the router. Depending on the settlement pattern, messages might be delivered with any of the following degrees of reliability:</p>
+<p>This definition allows access to any address that meets any of the following rules:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>At most once</p>
+<p>Starts with the prefix <code>tmp_</code> and ends with the user name</p>
</li>
<li>
-<p>At least once</p>
+<p>Starts with the prefix <code>temp</code> followed by any additional characters</p>
</li>
<li>
-<p>Exactly once</p>
+<p>Starts with the user name, is followed by <code>-home-</code>, and ends with any additional characters</p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>Dispatch Router treats all messages as either <em>pre-settled</em> or <em>unsettled</em>, and it is responsible for propagating the settlement of each message it routes.</p>
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">sources: tmp_{user}, temp*, {user}-home-*</pre>
+</div>
</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1">Pre-settled</dt>
-<dd>
-<p>Sometimes called <em>fire and forget</em>, the router settles the incoming and outgoing deliveries and propagates the settlement to the message’s destination. However, it does not guarantee delivery.</p>
-</dd>
-<dt class="hdlist1">Unsettled</dt>
-<dd>
-<p>The router propagates the settlement between the sender and receiver, and guarantees one of the following outcomes:</p>
-<div class="ulist">
-<ul>
-<li>
-<p>The message is delivered and settled, with the consumer’s disposition indicated.</p>
-</li>
-<li>
-<p>The delivery is settled with a disposition of <code>RELEASED</code>.</p>
-<div class="paragraph">
-<p>This means that the message did not reach its destination.</p>
</div>
-</li>
-<li>
-<p>The delivery is settled with a disposition of <code>MODIFIED</code>.</p>
-<div class="paragraph">
-<p>This means that the message might or might not have reached its destination. The delivery is considered to be "in-doubt" and should be re-sent if "at least once" delivery is required.</p>
</div>
</li>
<li>
-<p>The link, session, or connection to Dispatch Router was dropped, and all deliveries are "in-doubt".</p>
+<p>A list of AMQP target addresses from which users in this group may send messages. You can specify multiple AMQP addresses and use user name substitution and wildcards the same way as with source addresses.</p>
</li>
-</ul>
+</ol>
</div>
-</dd>
-</dl>
</div>
</div>
-<div class="sect3">
-<h4 id="routing_messages_between_clients">7.2.4. Routing Messages Between Clients</h4>
+</li>
+<li>
+<p>If necessary, add any advanced user group settings to the vhost user group.</p>
<div class="paragraph">
-<p>You can route messages between clients without using a broker. In a brokerless scenario (sometimes called <em>direct-routed messaging</em>), Dispatch Router routes messages between clients directly.</p>
+<p>The advanced user group settings enable you to define resource limits based on the AMQP connection open, session begin, and link attach phases of the connection. For more information, see <a href="https://qpid.apache.org/releases/qpid-dispatch-1.0.1/man/qdrouterd.conf.html#_vhostUserGroupSettings" target="_blank" rel="noopener">Vhost User Group Settings</a>.</p>
+</div>
+</li>
+</ol>
+</div>
</div>
+<div class="sect4">
+<h5 id="configuring-vhost-policies-json">Configuring Vhost Policies as JSON Files</h5>
<div class="paragraph">
-<p>To route messages between clients, you configure an address with a routing distribution pattern. When a router receives a message with this address, the message is routed to its destination or destinations based on the address’s routing distribution pattern.</p>
+<p>As an alternative to using the router configuration file, you can configure vhost policies in JSON files. If you have multiple routers that need to share the same vhost configuration, you can put the vhost configuration JSON files in a location accessible to each router, and then configure the routers to apply the vhost policies defined in these JSON files.</p>
</div>
<div class="olist arabic">
<div class="title">Procedure</div>
<ol class="arabic">
<li>
-<p>In the router’s configuration file, add an <code>address</code> section:</p>
-<div class="openblock">
+<p>Determine where to store the vhost policy JSON files.</p>
+<div class="paragraph">
+<p>The directory should be accessible by each router that needs to apply these vhost policies.</p>
+</div>
+</li>
+<li>
+<p>In the directory you determined, create a JSON file for each vhost policy.</p>
+<div class="paragraph">
+<p>The vhost policy is configured the same way as a <code>vhost</code> entity in the router configuration file, only using JSON syntax. For more information about vhost policy attributes, see <a href="#configuring-vhost-policies-router">Configuring Vhost Policies in the Router Configuration File</a>.</p>
+</div>
+<div class="exampleblock">
+<div class="title">Example 7. Sample Vhost Policy JSON File</div>
<div class="content">
<div class="listingblock">
<div class="content">
-<pre class="nowrap">address {
- prefix: <em>ADDRESS_PREFIX</em>
- distribution: balanced|closest|multicast
- ...
-}</pre>
+<pre class="highlightjs highlight nowrap"><code class="language-json hljs" data-lang="json">{
+ "vhost": {
+ "name": "example.com",
+ "maxConnectionsPerUser": 100,
+ "allowUnknownUser": true,
+ "groups": {
+ "admin": {
+ "users": ["admin1", "admin2"],
+ "sources": "*",
+ "targets": "*"
+ },
+ "developers": {
+ "users": ["dev1", "dev2", "dev3"],
+ "remoteHosts": "*",
+ "sources": ["myqueue1", "myqueue2"],
+ "targets": ["myqueue1", "myqueue2"]
+ }
+ }
+ }
+}</code></pre>
</div>
</div>
-<div class="dlist">
-<dl>
-<dt class="hdlist1"><code>prefix</code> | <code>pattern</code></dt>
-<dd>
-<p>The address or group of addresses to which the address settings should be applied. You can specify a prefix to match an exact address or beginning segment of an address. Alternatively, you can specify a pattern to match an address using wildcards.</p>
-<div class="paragraph">
-<p>A <em>prefix</em> matches either an exact address or the beginning segment within an address that is delimited by either a <code>.</code> or <code>/</code> character. For example, the prefix <code>my_address</code> would match the address <code>my_address</code> as well as <code>my_address.1</code> and <code>my_address/1</code>. However, it would not match <code>my_address1</code>.</p>
</div>
-<div class="paragraph">
-<p>A <em>pattern</em> matches an address that corresponds to a pattern. A pattern is a sequence of words delimited by either a <code>.</code> or <code>/</code> character. You can use wildcard characters to represent a word. The <code>*</code> character matches exactly one word, and the <code>#</code> character matches any sequence of zero or more words.</p>
</div>
-<div class="paragraph">
-<p>The <code>*</code> and <code>#</code> characters are reserved as wildcards. Therefore, you should not use them in the message address.</p>
+</li>
+<li>
+<p>In the router configuration file, locate the <code>policy</code> entity and set the <code>policyDir</code> attribute to point to the directory where the vhost policy JSON files are stored.</p>
+<div class="exampleblock">
+<div class="title">Example 8. A <code>policy</code> Entity</div>
+<div class="content">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">policy = {
+ maxConnections: 1000
+ enableVhostPolicy: true
+ policyDir: /etc/vhost-policies/ <b class="conum">(1)</b>
+ defaultVhost: $default
+}</pre>
</div>
-<div class="paragraph">
-<p>The following table shows some examples of address patterns:</p>
</div>
-<table class="tableblock frame-all grid-all spread">
-<colgroup>
-<col style="width: 25%;">
-<col style="width: 75%;">
-</colgroup>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">This pattern…​</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Matches…​</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news/*/sports</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news/europe/sports</code> and <code>news/usa/sports</code>, but not <code>news</code> or <code>news/europe/fr/sports</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news/#</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>news</code>, <code>news/europe</code>, <code>news/usa</code>, <code>news/usa/sports</code></p></td>
-</tr>
-</tbody>
-</table>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>You can convert a <code>prefix</code> value to a <code>pattern</code> by appending <code>/#</code> to it. For example, the prefix <code>a/b/c</code> is equivalent to the pattern <code>a/b/c/#</code>.</p>
+<div class="colist arabic">
+<ol>
+<li>
+<p>The absolute path to a directory that holds vhost policy definition files in JSON format (*.json). The router processes all of the vhost policies in each JSON file that is in this directory.</p>
+</li>
+</ol>
+</div>
</div>
-</td>
-</tr>
-</table>
</div>
-</dd>
-<dt class="hdlist1"><code>distribution</code></dt>
-<dd>
-<p>The message distribution pattern. The default is <code>balanced</code>, but you can specify any of the following options:</p>
-<div class="ulist">
-<ul>
-<li>
-<p><code>balanced</code> - Messages sent to the address will be routed to one of the receivers, and the routing network will attempt to balance the traffic load based on the rate of settlement.</p>
</li>
<li>
-<p><code>closest</code> - Messages sent to the address are sent on the shortest path to reach the destination. It means that if there are multiple receivers for the same address, only the closest one will receive the message.</p>
+<p>Repeat the previous step for each additional router that should use the vhost policies located in the vhost policy directory.</p>
</li>
-<li>
-<p><code>multicast</code> - Messages are sent to all receivers that are attached to the address in a <em>publish/subscribe</em> model.</p>
-<div class="paragraph">
-<p>For more information about message distribution patterns, see <a href="#routing_patterns_overview">Routing Patterns</a>.</p>
+</ol>
</div>
-</li>
-</ul>
</div>
-</dd>
-</dl>
</div>
+<div class="sect3">
+<h4 id="example_configuring_a_vhost_policy">6.2.5. Example: Configuring a Vhost Policy</h4>
<div class="paragraph">
-<p>For information about additional attributes, see <a href="#router_configuration_file_address">Address</a> in the <em>Configuration Reference</em>.</p>
+<p>In this example, a vhost policy defines resource limits for clients connecting to the <code>example.com</code> host.</p>
</div>
+<div class="exampleblock">
+<div class="title">Example 9. A Vhost Policy in the Router Configuration File</div>
+<div class="content">
+<div class="listingblock">
+<div class="content">
+<pre class="nowrap">vhost {
+ name: example.com <b class="conum">(1)</b>
+ maxConnectionsPerUser: 10 <b class="conum">(2)</b>
+ allowUnknownUser: true <b class="conum">(3)</b>
+ groups: {
+ admin: {
+ users: admin-01, admin-02 <b class="conum">(4)</b>
+ remoteHosts: 127.0.0.1, ::1 <b class="conum">(5)</b>
+ sources: * <b class="conum">(6)</b>
+ targets: * <b class="conum">(6)</b>
+ },
+ $default: {
+ remoteHosts: * <b class="conum">(7)</b>
+ sources: news*, sports*, chat* <b class="conum">(8)</b>
+ targets: chat* <b class="conum">(9)</b>
+ }
+ }
+}</pre>
</div>
</div>
+<div class="colist arabic">
+<ol>
+<li>
+<p>The rules defined in this vhost policy will be applied to any user connecting to <code>example.com</code>.</p>
</li>
<li>
-<p>Add the same <code>address</code> section to any other routers that need to use the address.</p>
-<div class="paragraph">
-<p>The <code>address</code> that you added to this router configuration file only controls how this router distributes messages sent to the address. If you have additional routers in your router network that should distribute messages for this address, then you must add the same <code>address</code> section to each of their configuration files.</p>
-</div>
+<p>Each user can open up to 10 connections to the vhost.</p>
+</li>
+<li>
+<p>Any user can connect to this vhost. Users that are not part of the <code>admin</code> group are assigned to the <code>$default</code> group.</p>
+</li>
+<li>
+<p>If the <code>admin-01</code> or <code>admin-02</code> user connects to the vhost, they are assigned to the <code>admin</code> user group.</p>
+</li>
+<li>
+<p>Users in the <code>admin</code> user group must connect from localhost. If the admin user attempts to connect from any other host, the connection will be denied.</p>
+</li>
+<li>
+<p>Users in the admin user group can send and receive from any address offered by the vhost.</p>
+</li>
+<li>
+<p>Any non-admin user is permitted to connect from any host.</p>
+</li>
+<li>
+<p>Non-admin users are permitted to receive messages from any addresses that start with the <code>news</code>, <code>sports</code>, or <code>chat</code> prefixes.</p>
+</li>
+<li>
+<p>Non-admin users are permitted to send messages to any address that start with the <code>chat</code> prefix.</p>
</li>
</ol>
</div>
</div>
+</div>
+</div>
<div class="sect3">
-<h4 id="routing_messages_through_broker">7.2.5. Routing Messages Through a Broker Queue</h4>
+<h4 id="example_using_a_vhost_policy_to_limit_memory_consumption_advanced">6.2.6. Example: Using a Vhost Policy to Limit Memory Consumption (Advanced)</h4>
<div class="paragraph">
-<p>You can route messages to and from a broker queue to provide clients with access to the queue through a router. In this scenario, clients connect to a router to send and receive messages, and the router routes the messages to or from the broker queue.</p>
+<p>By using the advanced vhost policy attributes, you can control how much system buffer memory a user connection can potentially consume.</p>
</div>
<div class="paragraph">
-<p>You
<TRUNCATED>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org