Chapter 3. Getting started

This section provides a quick introduction to AMQ Interconnect by showing you how to install AMQ Interconnect, start the router with the default configuration settings, and distribute messages between two clients.

3.1. Installing AMQ Interconnect on Red Hat Enterprise Linux

AMQ Interconnect is distributed as a set of RPM packages, which are available through your Red Hat subscription.

Procedure

  1. Ensure your subscription has been activated and your system is registered.

    For more information about using the Customer Portal to activate your Red Hat subscription and register your system for packages, see Appendix A, Using your subscription.

  2. Subscribe to the required repositories:

    Red Hat Enterprise Linux 6
    $ sudo subscription-manager repos --enable=amq-interconnect-1-for-rhel-6-server-rpms --enable=amq-clients-2-for-rhel-6-server-rpms
    Red Hat Enterprise Linux 7
    $ sudo subscription-manager repos --enable=amq-interconnect-1-for-rhel-7-server-rpms --enable=amq-clients-2-for-rhel-7-server-rpms
    Red Hat Enterprise Linux 8
    $ sudo subscription-manager repos --enable=amq-interconnect-1-for-rhel-8-x86_64-rpms --enable=amq-clients-2-for-rhel-8-x86_64-rpms
  3. Use the yum or dnf command to install the qpid-dispatch-router, qpid-dispatch-tools, and qpid-dispatch-console packages and their dependencies:

    $ sudo yum install qpid-dispatch-router qpid-dispatch-tools qpid-dispatch-console
  4. Use the which command to verify that the qdrouterd executable is present.

    $ which qdrouterd
    /usr/sbin/qdrouterd

    The qdrouterd executable should be located at /usr/sbin/qdrouterd.

3.2. Exploring the default router configuration file

The router’s configuration file (qdrouterd.conf) controls the way in which the router functions. The default configuration file contains the minimum number of settings required for the router to run. As you become more familiar with the router, you can add to or change these settings, or create your own configuration files.

By default, the router configuration file defines the following settings for the router:

  • Operating mode
  • How it listens for incoming connections
  • Routing patterns for the message routing mechanism

Procedure

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

    When AMQ Interconnect is installed, qdrouterd.conf is installed in this directory. When the router is started, it runs with the settings defined in this file.

  2. Review the default settings in qdrouterd.conf.

    Default configuration file

    router {
        mode: standalone 1
        id: Router.A 2
    }
    
    listener { 3
        host: 0.0.0.0
        port: amqp
        authenticatePeer: no
    }
    
    address { 4
        prefix: closest
        distribution: closest
    }
    
    address {
        prefix: multicast
        distribution: multicast
    }
    
    address {
        prefix: unicast
        distribution: closest
    }
    
    address {
        prefix: exclusive
        distribution: closest
    }
    
    address {
        prefix: broadcast
        distribution: multicast
    }

    1
    By default, the router operates in standalone mode. This means that it can only communicate with endpoints that are directly connected to it. It cannot connect to other routers, or participate in a router network.
    2
    The unique identifier of the router. This ID is used as the container-id (container name) at the AMQP protocol level. If it is not specified, the router shall generate a random identifier at startup.
    3
    The listener entity handles incoming connections from client endpoints. By default, the router listens on all network interfaces on the default AMQP port (5672).
    4
    By default, the router is configured to use the message routing mechanism. Each address entity defines how messages that are received with a particular address prefix should be distributed. For example, all messages with addresses that start with closest will be distributed using the closest distribution pattern.
    Note

    If a client requests a message with an address that is not defined in the router’s configuration file, the balanced distribution pattern will be used automatically.

Additional resources

  • For more information about the router configuration file (including available entities and attributes), see the qdrouterd man page.

3.3. Starting the router

After installing AMQ Interconnect, you start the router by using the qdrouterd command.

Procedure

  1. Start the router:

    $ qdrouterd

    The router starts, using the default configuration file stored at /etc/qpid-dispatch/qdrouterd.conf.

  2. Review the qdrouterd command output to verify the router status.

    This example shows that the router was correctly installed, is running, and is ready to route traffic between clients:

    $ qdrouterd
    Fri May 20 09:38:03 2017 SERVER (info) Container Name: Router.A
    Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone mode
    Fri May 20 09:38:03 2017 ROUTER (info) Router Core thread running. 0/Router.A
    Fri May 20 09:38:03 2017 ROUTER (info) In-process subscription M/$management
    Fri May 20 09:38:03 2017 AGENT (info) Activating management agent on $_management_internal
    Fri May 20 09:38:03 2017 ROUTER (info) In-process subscription L/$management
    Fri May 20 09:38:03 2017 ROUTER (info) In-process subscription L/$_management_internal
    Fri May 20 09:38:03 2017 DISPLAYNAME (info) Activating DisplayNameService on $displayname
    Fri May 20 09:38:03 2017 ROUTER (info) In-process subscription L/$displayname
    Fri May 20 09:38:03 2017 CONN_MGR (info) Configured Listener: 0.0.0.0:amqp proto=any role=normal
    Fri May 20 09:38:03 2017 POLICY (info) Policy configured maximumConnections: 0, policyFolder: '', access rules enabled: 'false'
    Fri May 20 09:38:03 2017 POLICY (info) Policy fallback defaultApplication is disabled
    Fri May 20 09:38:03 2017 SERVER (info) Operational, 4 Threads Running

Additional resources

3.4. Sending test messages

After starting the router, send some test messages to see how the router can connect two endpoints by distributing messages between them.

This procedure demonstrates a simple configuration consisting of a single router with two clients connected to it: a sender and a receiver. The receiver wants to receive messages on a specific address, and the sender sends messages to that address.

A broker is not used in this procedure, so there is no "store and forward" mechanism in the middle. Instead, the messages flow from the sender, through the router, to the receiver only if the receiver is online, and the sender can confirm that the messages have arrived at their destination.

Prerequisites

AMQ Python must be installed. For more information, see Using the AMQ Python Client.

Procedure

  1. Navigate to the AMQ Python examples directory.

    $ cd <install-dir>/examples/python/
    <install-dir>
    The directory where you installed AMQ Python.
  2. Start the simple_recv.py receiver client.

    $ python simple_recv.py -a 127.0.0.1:5672/examples -m 5

    This command starts the receiver and listens on the examples address (127.0.0.1:5672/examples). The receiver is also set to receive a maximum of five messages.

    Note

    In practice, the order in which you start senders and receivers does not matter. In both cases, messages will be sent as soon as the receiver comes online.

  3. In a new terminal window, navigate to the Python examples directory and run the simple_send.py example:

    $ cd <install-dir>/examples/python/
    $ python simple_send.py -a 127.0.0.1:5672/examples -m 5

    This command sends five auto-generated messages to the examples address (127.0.0.1:5672/examples) and then confirms that they were delivered and acknowledged by the receiver:

    all messages confirmed
  4. Verify that the receiver client received the messages.

    The receiver client should display the contents of the five messages:

    {u'sequence': 1L}
    {u'sequence': 2L}
    {u'sequence': 3L}
    {u'sequence': 4L}
    {u'sequence': 5L}

3.5. Next steps

After using AMQ Interconnect to distribute messages between two clients, you can use the following sections to learn more about AMQ Interconnect configuration, deployment, and management.

Change the router’s configuration
AMQ Interconnect ships with default settings that are suitable for many basic use cases. You can further experiment with the standalone router that you used in the Getting started example by changing the router’s essential properties, network connections, security settings, logging, and routing mechanisms.
Install and configure AMQ Interconnect
AMQ Interconnect is typically deployed in router networks. You can design a router network of any arbitrary topology to interconnect the endpoints in your messaging network.
Monitor and manage AMQ Interconnect
You can use the web console and command-line management tools to monitor the status and performance of the routers in your router network.