Chapter 8. Configuring network connections

Procedure

1. 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.

2. 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:

   connector {
       host: 192.0.2.1
       port: 5001
       role: inter-router
       ...
   }

   host

   The IP address (IPv4 or IPv6) or hostname on which the router will connect.

   port

   The port number or symbolic service name, defined in /etc/services, 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.

3. 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 previous step:

   listener {
       host: 0.0.0.0
       port: 5001
       role: inter-router
       ...
   }

   host

   The IP address (IPv4 or IPv6) or hostname on which the router will listen.

   port

   The port number or symbolic service name, defined in /etc/services, 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.

4. 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.

Procedure

1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

2. Configure a listener with the normal role.

   listener {
       host: primary.example.com
       port: 5672
       role: normal
       failoverUrls: secondary.example.com:20000, tertiary.example.com
       ...
   }

   host

   The IP address (IPv4 or IPv6) or hostname on which the router will listen.

   port

   The port number or symbolic service name, defined in /etc/services, 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”.

Procedure

1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

2. 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.

   connector {
       name: my-broker
       host: 192.0.2.10
       port: 5672
       role: route-container
       ...
   }

   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, defined in /etc/services, 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.

Procedure

1. Open the /etc/qpid-dispatch/qdrouterd.conf configuration file.

2. Add arbitrary JSON to the connector configuration using the 'openProperties' attribute.

   This example adds the property label with the value green.

   connector {
      name: broker
      role: route-container
      host: 127.0.0.1
      port: 22180
      saslMechanisms: ANONYMOUS
      openProperties: {
         "label": "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:

   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
   }