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. Methods for Using Pattern Matching and Wildcards

The router configuration file supports pattern matching and wildcards to enable you to match multiple values for certain attributes. However, the syntax varies based on the type of entity that you are configuring.

5.3.1. Pattern Matching for Addresses

In some router configuration scenarios, you might need to use pattern matching to match a range of addresses rather than a single, literal address. Address patterns match any address that corresponds to the pattern.

An address pattern is a sequence of tokens (typically words) that are delimited by either . or / characters. They also can contain special wildcard characters that represent words:

  • * represents exactly one word
  • # represents zero or more words

Example 5.1. Address Pattern

This address contains two tokens, separated by the / delimiter:

my/address

Example 5.2. Address Pattern with Wildcard

This address contains three tokens. The * is a wildcard, representing any single word that might be between my and address:

my/*/address

The following table shows some address patterns and examples of the addresses that would match them:

This pattern…​Matches…​But not…​

news/*

news/europe

news/usa

news

news/usa/sports

news/#

news

news/europe

news/usa/sports

europe

usa

news/europe/#

news/europe

news/europe/sports

news/europe/politics/fr

news/usa

europe

news/*/sports

news/europe/sports

news/usa/sports

news

news/europe/fr/sports

5.3.2. Pattern Matching for Vhost Policy Hostnames

In a vhost policy, vhost hostnames can be either literal hostnames or patterns that cover a range of hostnames.

A hostname pattern is a sequence of words with one or more of the following wildcard characters:

  • * represents exactly one word
  • # represents zero or more words

The following table shows some examples of hostname patterns:

This pattern…​Matches…​But not…​

*.example.com

www.example.com

example.comsrv2.www.example.com

#.example.com

example.comwww.example.coma.b.c.d.example.com

myhost.com

www.*.test.example.com

www.a.test.example.com

www.test.example.comwww.a.b.c.test.example.com

www.#.test.example.com

www.test.example.comwww.a.test.example.comwww.a.b.c.test.example.com

test.example.com

Vhost hostname pattern matching applies the following precedence rules:

Policy patternPrecedence

Exact match

High

*

Medium

#

Low

Note

AMQ Interconnect does not permit you to create vhost hostname patterns that conflict with existing patterns. This includes patterns that can be reduced to be the same as an existing pattern. For example, you would not be able to create the #.#.#.#.com pattern if #.com already exists.

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

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

5.4.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.5. 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.6. 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/EDGE
        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.
    • edge - Use this mode if the router is an edge router that will connect to a network of interior 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 qdrouterd.conf man page.

  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.