Red Hat Training

A Red Hat training course is available for Red Hat AMQ

Chapter 5. Configuration

In the previous chapter you saw how to install AMQ Broker and how to start a broker instance. You should understand how the broker instance you created is configured and what the important aspects of the default configuration are.

You configure brokers by editing plain text and XML files. Changing a broker’s configuration typically involves opening the appropriate configuration file, locating the proper location for the relevant configuration within the XML schema, and then adding or removing XML elements and attributes.

5.1. Configuration Files and Locations

All of a broker’s configuration files are found in the directory BROKER_INSTANCE_DIR/etc. The table below lists each file and describes what they do.

Table 5.1. Broker Configuration Files

File(s)Description

broker.xml

The main configuration file. Use this file to configure most aspects of the broker, such as network connections, security settings, message addresses, and so on.

bootstrap.xml

The file that AMQ Broker uses to start a broker instance. Use it to change the location of broker.xml, configure the web server, and set some security settings.

logging.properties

Use this file to set logging properties for the broker instance.

artemis.profile

Sets environment variables used while the broker instance is running.

login.config artemis-users.properties artemis-roles.properties

Security-related files. Use these files to set up authentication for user access to the broker instance.

The schema for the broker’s XML configuration files are found under the product installation at INSTALL_DIR/schema. Consult the XSD files, especially artemis-configuration.xsd, for the schema definitions of the XML configuration elements used in this guide as well as a description of each element.

5.2. Default Configuration

The following sections identify important aspects of the default configuration found in broker.xml after first installing a broker instance.

5.2.1. Reloading Configuration Updates

You can configure the broker to perform a periodic check for changes in the configuration files and, if any are found, reload the configuration to activate them.

The check interval is configured using the configuration-file-refresh-period setting in broker.xml. The default is 5000 milliseconds.

After this function is activated, the broker automatically checks for, and reloads, changes in the following modules:

Address Settings and Queues

When the configuration file is reloaded, the address settings determine how to handle addresses and queues that have been deleted from the configuration file.

  • config-delete-addresses - If this is set to FORCE, then the address (and its queues) that was deleted from the configuration file will be deleted when the configuration file is reloaded. If there are any messages in the queues, they are removed also.
  • config-delete-queues - If this is set to FORCE, then the queue that was deleted from the configuration file will be deleted when the configuration file is reloaded. If there are any messages in the queue, they are removed also.

Destinations can be explicitly removed by using CLI or management operations.

Security Settings
SSL/TLS key and truststores on an existing acceptor can be reloaded to establish new certificates without any impact to existing clients. Connected clients, even those with older or differing certificates, can continue to send and receive messages. For most circumstances, other administrative operations exist to remove clients when appropriate.

5.2.2. Acceptors

Brokers listen for incoming client connections by using an acceptor configuration element to define the port and protocols a client can use to make connections. Be default AMQ Broker includes configuration for several acceptors.

Default Acceptor Configuration in broker.xml

<configuration>
  <core>
  ...
  <acceptors>
   <!-- Default ActiveMQ Artemis Acceptor.  Multi-protocol adapter.  Currently supports ActiveMQ Artemis Core, OpenWire, STOMP, AMQP, MQTT, and HornetQ Core. -->
   <!-- performance tests have shown that openWire performs best with these buffer sizes -->
   <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576</acceptor>

   <!-- AMQP Acceptor.  Listens on default AMQP port for AMQP traffic.-->
   <acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP</acceptor>

   <!-- STOMP Acceptor. -->
   <acceptor name="stomp">tcp://0.0.0.0:61613?protocols=STOMP</acceptor>

   <!-- HornetQ Compatibility Acceptor.  Enables HornetQ Core and STOMP for legacy HornetQ clients. -->
   <acceptor name="hornetq">tcp://0.0.0.0:5445?protocols=HORNETQ,STOMP</acceptor>

   <!-- MQTT Acceptor -->
   <acceptor name="mqtt">tcp://0.0.0.0:1883?protocols=MQTT</acceptor>
  </acceptors>
  ...
 </core>
</configuration>

See Networking Connections for details on acceptors and connectors configuration. For more information on the protocols supported by the broker, refer to Protocols.

5.2.3. Addresses and Queues

The default configuration defines two queues. The first one handles messages that arrive with no known destination and is known as a Dead Letter Queue (DLQ). The second queue holds messages that have lived past their expiration and therefore should not be routed to their original destination and is known as an Expiry Queue.

Default JMS Queues in broker.xml

<configuration>
<core>
    ...
    <addresses>
        <address name="DLQ">
           <anycast>
              <queue name="DLQ" />
           </anycast>
        </address>
        <address name="ExpiryQueue">
           <anycast>
              <queue name="ExpiryQueue" />
           </anycast>
        </address>
    </addresses>
  </core>
</configuration>

The default configuration also uses the concept of an address setting to establish a default, or catch all, set of configuration that is applied to any created queue or topic.

Default Address Setting in broker.xml

<configuration>
 <core>
  ...
  <address-settings>
   <!--default for catch all-->
   <address-setting match="#">
      <dead-letter-address>jms.queue.DLQ</dead-letter-address>
      <expiry-address>jms.queue.ExpiryQueue</expiry-address>
      <redelivery-delay>0</redelivery-delay>
      <max-size-bytes>10485760</max-size-bytes>
      <message-counter-history-day-limit>10</message-counter-history-day-limit>
      <address-full-policy>BLOCK</address-full-policy>
   </address-setting>
  </address-settings>
 </core>
</configuration>

Note how the address-setting uses a wildcard syntax to dictate which queues and addresses are to have the configuration applied. In this case the single # symbol tells AMQ Broker to apply the configuration to all queues and topics.

5.2.4. Security

AMQ Broker contains a flexible role-based security model for applying security to queues, based on their addresses. Also, just like an address setting, you can use a wildcard syntax, as does the default configuration.

Default Security Configuration in broker.xml

<configuration>
  <core>
    ...
    <security-settings>
       <security-setting match="#">
          <permission type="createNonDurableQueue" roles="amq"/>
          <permission type="deleteNonDurableQueue" roles="amq"/>
          <permission type="createDurableQueue" roles="amq"/>
          <permission type="deleteDurableQueue" roles="amq"/>
          <permission type="createAddress" roles="amq"/>
          <permission type="deleteAddress" roles="amq"/>
          <permission type="consume" roles="amq"/>
          <permission type="browse" roles="amq"/>
          <permission type="send" roles="amq"/>
          <!-- we need this otherwise ./artemis data imp wouldn't work -->
          <permission type="manage" roles="amq"/>
       </security-setting>
    </security-settings>
    ...
  </core>

Note all the types of permission that can be used as part of a security setting. For more details on permission types and other security topics see the Security chapter.

5.2.5. Message Persistence

By default, AMQ Broker persistence uses an append only file journal that consists of a set of files on disk. The journal saves messages, transactions, and other information. As an alternative to using a journal, you can configure persistence to use a JDBC connection to write to a database table. A third option is to disable persistence completely.

Default Persistence Configuration in broker.xml

<configuration>
  <core>
    ...
    <persistence-enabled>true</persistence-enabled>
    <!-- this could be ASYNCIO or NIO-->
    <journal-type>ASYNCIO</journal-type>
    <paging-directory>./data/paging</paging-directory>
    <bindings-directory>./data/bindings</bindings-directory>
    <journal-directory>./data/journal</journal-directory>
    <large-messages-directory>./data/large-messages</large-messages-directory>
    <journal-datasync>true</journal-datasync>
    <journal-min-files>2</journal-min-files>
    <journal-pool-files>-1</journal-pool-files>
    ...
  </core>
</configuration>

When persistence-enabled is set to true the journal persists to the directories specified.

The two valid options for journal-type are:

ASYNCIO

Use this option to maintain journals by using libaio. This option is recommended if you are running the broker with Linux Kernel 2.6 or later.

If the libaio package is found when creating the broker instance, then the ASYNCIO option is set by default.

NIO

Use this option to maintain journals by using Java. This option is automatically enabled when journal-type is set to ASYNCIO, but the libaio package cannot be found.

If the libaio package is not found when creating the broker instance, then the NIO option is set by default.

For more details about the available options and how to configure them, see Configuring Persistence.

5.3. Modularizing the Broker Configuration File

AMQ Broker supports XML inclusions in the broker.xml configuration file, which enables you to break broker.xml into separate files. For example, if you have multiple brokers that share the same set of addresses and address settings, you can define the addresses in a separate file, and then include that file in each broker’s broker.xml configuration file.

You must create a separate XML file for each section to include it in the broker.xml file. For example, you must create separate files for address-settings and security-settings sections. If you include two sections in a single XML file and start the broker, you will get an error something similar to The markup in the document following the root element must be well-formed..

Note

Add the following line inside the <configuration> tag at the beginning of the broker.xml file if it is not listed. 

xmlns:xi="http://www.w3.org/2001/XInclude"

Procedure

  • Add the include tag and the file name with full path in the broker.xml file to include the XML configuration from another file: 

    <xi:include href="/opt/my-broker-config/my-addresses.xml"/>

    In the above example, the my-address-settings.xml file is sourced into the broker.xml file.

You must ensure XML elements in separated files must be namespaced correctly. For example, if address-settings element was separated, it must have the element namespace defined as below: 

<address-settings xmlns="urn:activemq:core">
Note

The broker reloads configuration updates based on the frequency set in the configuration-file-refresh-period setting in the broker.xml file. For more information, see Reloading Configuration Updates.

Additional Resources