Chapter 5. Configuration

Before starting AMQ Interconnect, 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.

5.1. Accessing the Router Configuration File

The router’s configuration is defined in the router configuration file. You can access this file to view and modify that configuration.

Procedure

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

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

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

5.2. How the Router Configuration File is Structured

Before you can make changes to a router configuration file, you should understand how the file is structured.

The configuration file contains sections. A section is a configurable entity, and it contains a set of attribute name-value pairs that define the settings for that entity. The syntax is as follows:

sectionName {
    attributeName: attributeValue
    attributeName: attributeValue
    ...
}

5.3. Changing a Router’s Configuration

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.

5.3.1. Making a Permanent Change to the Router’s Configuration

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.

Procedure

  1. Do one of the following:

    • Edit the default configuration file (/etc/qpid-dispatch/qdrouterd.conf).
    • Create a new configuration file.
  2. Start (or restart) the router.

    If you created a new configuration file, you must specify the path using the --conf parameter. For example, the following command starts the router with a non-default configuration file:

    # qdrouterd -d --conf /etc/qpid-dispatch/new-configuration-file.conf

5.3.2. Changing the Configuration for a Running Router

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.

Procedure

5.4. Default Configuration Settings

The router’s configuration file 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.

When you installed AMQ Interconnect, the default configuration file was added at the following path: /etc/qpid-dispatch/qdrouterd.conf. It includes some basic configuration settings that define the router’s operating mode, how it listens for incoming connections, and routing patterns for the message routing mechanism.

Default Configuration File

router {
    mode: standalone 1
    id: Router.A 2
}

listener { 3
    host: 0.0.0.0 4
    port: amqp 5
    authenticatePeer: no 6
}

address { 7
    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. It is required, and the router will not start if this attribute is not defined.
3
The listener entity handles incoming connections from client endpoints.
4
The IP address on which the router will listen for incoming connections. By default, the router is configured to listen on all network interfaces.
5
The port on which the router will listen for incoming connections. By default, the default AMQP port (5672) is specified with a symbolic service name.
6
Specifies whether the router should authenticate peers before they can connect to the router. By default, peer authentication is not required.
7
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.

5.5. Setting Essential Configuration Properties

The router’s default configuration settings enable the router to run with minimal configuration. However, you may need to change some of these settings for the router to run properly in your environment.

Procedure

  1. Open the router’s configuration file.

    If you are changing the router’s default configuration file, the file is located at /etc/qpid-dispatch/qdrouterd.conf.

  2. To define essential router information, change the following attributes as needed in the router section:

    router {
        mode: STANDALONE/INTERIOR
        id: ROUTER_ID
    }
    mode

    Specify one of the following modes:

    • standalone - Use this mode if the router does not communicate with other routers and is not part of a router network. When operating in this mode, the router only routes messages between directly connected endpoints.
    • interior - Use this mode if the router is part of a router network and needs to collaborate with other routers.
    id
    The unique identifier for the router. This ID will also be the container name at the AMQP protocol level.

    For information about additional attributes, see Router in the Configuration Reference.

  3. If necessary for your environment, secure the router.

  4. Connect the router to other routers, clients, and brokers.

  5. Set up routing for your environment:

  6. Set up logging.