Chapter 8. Configuring network connections
Chapter 8. Configuring network connections AMQ Interconnect connects clients, servers, AMQP services, and other routers through network connections. To connect the router to other messaging endpoints, you configure listeners to accept connections, and connectors to make outbound connections. However, connections are bidirectional - once the connection is established, message traffic flows in both directions. You can do the following: Connect a router to another router Listen for client connections Connect a router to an external AMQP container Add metadata to connections Understand connection failover 8.1. Connecting routers To connect a router to another router in the router network, you configure a connector on one router to create the outbound connection, and a listener on the other router to accept the connection. Because connections are bidirectional, there should only be one connection between any pair of routers. Once the connection is established, message traffic flows in both directions. This procedure describes how to connect a router to another router in the router network. Procedure Determine the direction of the connection. Decide which router should be the "connector", and which should be the "listener". The direction of the connection establishment is sometimes arbitrary, but consider the following factors: IP network boundaries and firewalls Generally, inter-router connections should always be established from more private to more public. For example, to connect a router in a private IP network to another router in a public location (such as a public cloud provider), the router in the private network must be the "connector" and the router in the public location must be the "listener". This is because the public location cannot reach the private location by TCP/IP without the use of VPNs or other firewall features designed to allow public-to-private access. Network topology The topology of the router network may affect the direction in which connections should be established between the routers. For example, a star-topology that has a series of routers connected to one or two central "hub" routers should have "listeners" on the hub and "connectors" on the spokes. That way, new spoke routers may be added without changing the configuration of the hub. On the router that should create the connection, open the /etc/qpid-dispatch/qdrouterd.conf configuration file and add a connector . This example creates a connector for an inter-router connection between two interior routers: host The IP address (IPv4 or IPv6) or hostname on which the router will connect. port The port number or symbolic service name on which the router will connect. role The role of the connection. If the connection is between two interior routers, specify inter-router . If the connection is between an interior router and an edge router, specify edge . On the router that should accept the connection establishment, open the /etc/qpid-dispatch/qdrouterd.conf configuration file and verify that an inter-router listener is configured. This example creates a listener to accept the connection establishment configured in the step: host The IP address (IPv4 or IPv6) or hostname on which the router will listen. port The port number or symbolic service name on which the router will listen. role The role of the connection. If the connection is between two interior routers, specify inter-router . If the connection is between an interior router and an edge router, specify edge . If the router should connect to any other routers, repeat this procedure. Edge routers can only connect to interior routers. They cannot connect to other edge routers. Additional resources After connecting a router to another router, secure the connection. For more information, see Section 9.1, "Securing connections between routers" . 8.2. Listening for client connections To enable a router to listen for and accept connections from AMQP clients, you configure a listener . Once the connection is enabled on the router, clients can connect to it using the same methods they use to connect to a broker. From the client's perspective, the router connection and link establishment are identical to a broker connection and link establishment. Note Instead of configuring a listener to listen for connections from the client, you can configure a connector to initiate connections to the client. In this case, the router will use the connector to initiate the connection, but it will not create any links. Links are only created by the peer that accepts the connection. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. Configure a listener with the normal role. host The IP address (IPv4 or IPv6) or hostname on which the router will listen. port The port number or symbolic service name on which the router will listen. role The role of the connection. Specify normal to indicate that this connection is used for message delivery for AMQP clients. failoverUrls (optional) A comma-separated list of backup URLs the client can use to reconnect if the established connection is lost. Each URL must use the following form: [(amqp|amqps|ws|wss)://]( HOST | IP ADDRESS )[:port] For more information, see Section 8.5, "Understanding connection failover" . Additional resources After enabling a router to listen for client connections, secure the connection. For more information, see Section 9.2, "Securing incoming client connections" . 8.3. Connecting to external AMQP containers To enable a router to establish a connection to an external AMQP container (such as a message broker), you configure a connector . Note Instead of configuring a connector to initiate connections to the AMQP container, you can configure a listener to listen for connections from the AMQP container. However, in this case, the addresses on the AMQP container are available for routing only after the AMQP container has created a connection. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. Configure a connector with the route-container role. This example creates a connector that initiates connections to a broker. The addresses on the broker will be available for routing once the router creates the connection and it is accepted by the broker. name The name of the connector . Specify a name that describes the entity to which the router will connect. host The IP address (IPv4 or IPv6) or hostname to which the router will connect. port The port number or symbolic service name to which the router will connect. role The role of the connection. Specify route-container to indicate that this connection is for an AMQP container that holds known addresses. Additional resources After enabling a router to connect to an external AMQP container, configure any necessary security credentials. For more information, see Section 9.3, "Securing outgoing connections" . 8.4. Adding metadata to connections In a complex topology, it can be useful to add metadata to connections so that messages can be handled programmatically. Procedure Open the /etc/qpid-dispatch/qdrouterd.conf configuration file. Add arbitrary JSON to the connector configuration using the 'openProperties' attribute. This example adds the property label with the value green . Note the following restrictions on the JSON entries: ASCII characters only for keys The following keys are not allowed: product version failover-server-list network-host port scheme hostname any key starting with qd. any key starting with x-opt-qd. The openProperties attribute can only be set for a connector with a normal or route-container role. You cannot set the attribute for connectors that have the following settings: role: inter-router role: edge http: true The JSON format supports lists, maps and multiple entries, for example: 8.5. Understanding connection failover If a connection between a router and a remote host fails, connection failover enables the connection to be reestablished automatically on an alternate URL. A router can use connection failover for both incoming and outgoing connections. Connection failover for outgoing connections By default, when you configure a connector on a router, the router attempts to maintain an open network transport connection to the configured remote host and port. If the connection cannot be established, the router continually retries until the connection is established. If the connection is established and then fails, the router immediately attempts to reestablish the connection. When the router establishes a connection to a remote host, the client may provide the router with alternate connection information (sometimes called failover lists) that it can use if the connection is lost. In these cases, rather than attempting to reestablish the connection on the same host, the router will also try the alternate hosts. Connection failover is particularly useful when the router establishes outgoing connections to a cluster of servers providing the same service. Connection failover for incoming connections You can configure a listener on a router to provide a list of failover URLs to be used as backups. If the connection is lost, the client can use these failover URLs to reestablish the connection to the router.
connector { host: 192.0.2.1 port: 5001 role: inter-router } listener { host: 0.0.0.0 port: 5001 role: inter-router } listener { host: primary.example.com port: 5672 role: normal failoverUrls: secondary.example.com:20000, tertiary.example.com } connector { name: my-broker host: 192.0.2.10 port: 5672 role: route-container } connector { name: broker role: route-container host: 127.0.0.1 port: 22180 saslMechanisms: ANONYMOUS openProperties: { "label": "green" } } connector { name: broker role: route-container host: 127.0.0.1 port: 22180 saslMechanisms: ANONYMOUS openProperties: { "foo": "bar", "integer": 7, "list": ["a", 1, "b", -9, true], "map": {"key1": null, "key2": [1, 2, 3]}, } cost: 10 }