Chapter 6. Network Connections

Connections define how the router communicates with clients, other routers, and brokers. You can configure incoming connections to define how the router listens for data from clients and other routers, and you can configure outgoing connections to define how the router sends data to other routers and brokers.

6.1. Listening for Incoming Connections

AMQ Interconnect provides listeners that accept client connections. A client connecting to a router listener uses the same methods that it would use to connect to a broker. From the client’s perspective, the router connection and link establishment are identical to broker connection and link establishment.

Several types of listeners are defined by their role.

RoleDescription

normal

The connection is used for AMQP clients using normal message delivery.

inter-router

The connection is assumed to be to another interior router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.

route-container

The connection is a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the remote resource has created a connection.

edge

The connection is between an edge router and an interior router.

Procedure

  1. In the router’s configuration file, add a listener:

    listener {
        host: HOST_NAME/ADDRESS
        port: PORT_NUMBER/NAME
        ...
    }
    host
    Either an IP address (IPv4 or IPv6) or hostname on which the router should listen for incoming connections.
    port
    The port number or symbolic service name on which the router should listen for incoming connections.

    For information about additional attributes, see listener in the qdrouterd.conf man page.

  2. If necessary, secure the connection.

    If you have set up SSL/TLS or SASL in your environment, you can configure the router to only accept encrypted or authenticated communication on this connection.

  3. If you want the router to listen for incoming connections on additional hosts or ports, configure an additional listener entity for each host and port.

6.2. Adding Outgoing Connections

You can configure AMQ Interconnect to create outbound connections to messaging brokers or other AMQP entities using connectors. A connector is defined with the network address of the broker and the name or names of the resources that are available in that broker. When a router connects to a broker through a connector, it uses the same methods a normal messaging client would use when connecting to the broker.

Several types of connectors are defined by their role.

RoleDescription

normal

The connection is used for AMQP clients using normal message delivery. On this connector the router will initiate the connection but it will never create any links. Links are to be created by the peer that accepts the connection.

inter-router

The connection is assumed to be to another interior router in the network. Inter-router discovery and routing protocols can only be used over inter-router connections.

route-container

The connection is to a broker or other resource that holds known addresses. The router will use this connection to create links as necessary. The addresses are available for routing only after the router has created a connection to the remote resource.

edge

The connection is between an edge router and an interior router.

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 Section 10.3.2.2, “Managing Connectors”.

Procedure

  1. In the router’s configuration file, add a connector:

    connector {
        name: NAME
        host: HOST_NAME/ADDRESS
        port: PORT_NUMBER/NAME
        ...
    }
    name
    The name of the connector. You should specify a name that describes the entity to which the connector connects. This name is used by configured addresses (for example, a linkRoute entity) in order to specify which connection should be used for them.
    host
    Either an IP address (IPv4 or IPv6) or hostname on which the router should connect.
    port
    The port number or symbolic service name on which the router should connect.

    For information about additional attributes, see connector in the qdrouterd.conf man page.

  2. If necessary, secure the connection.

    If you have set up SSL/TLS or SASL in your environment, you can configure the router to only send encrypted or authenticated communication on this connection.

  3. For each remaining router or broker to which this router should connect, configure an additional connector entity.

6.3. Connection Failover

In AMQ Interconnect, a connector attempts to maintain an open network transport connection to the configured remote host and port. If the connection cannot be established, the connector will continually retry until the connection is established. If an established connection is lost, the connector shall immediately attempt to re-establish the connection.

Connection Failover is a mechanism by which the remote host can provide alternate connection information for the connector to use in the event the established connection is lost. In this case, rather than attempting to re-establish the connection to the same host, the connector shall try the alternate hosts as well. This is useful in the case where the remote host is formed by a cluster or array of servers providing the same service.

AMQ Interconnect can participate in Connection Failover as both a client (initiator of transport connections) and a server (recipient of transport connections). In the client role, connectors shall always honor the failover lists provided by connected servers. As a server, a listener may be configured to provide a failover list to the clients that connect to it.

Listener attribute failoverUrls is an optional component that contains a comma-separated list of URLs to be used as backups for this listener. Each URL is of the form:

[(amqp|amqps|ws|wss)://]host_or_ip[:port]

When a client establishes a connection to this listener, it will be provided with this list of backup URLs to be used in the event that this connection is lost.

As an example, a listener may be configured like this:

listener {
    host: primary.domain.com
    port: amqp
    failoverUrls: secondary.domain.com:20000, tertiary.domain.com
    .
    .
    .
}