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.

When you create a broker instance, this option is the default if the libaio package can be found.

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.

When you create a broker instance, this option is the default if the libaio package cannot be found.

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