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.
| 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 JBoss AMQ Broker uses to start a broker instance. Use it to change the location of |
| 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 toFORCE, 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 toFORCE, 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 that are used to save messages, transactions, and other state.
There are several elements that are needed to configure the broker to persist to a message journal. These include the following.
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 true the journal persists to the directories specified and using the specified journal type of NIO. Alternative journal types are ASYNCIO and JDBC.
For more details on configuring persistence, refer to Configuring Persistence.
