Creating a broker in ActiveMQ Artemis

In the upcoming release of Red Hat A-MQ 7, the underlying open source upstream project shifts to ActiveMQ Artemis. If you would like to get a preview of what is coming, Red Hat JBoss A-MQ 7.0-Beta can be downloaded from Red Hat’s site. In addition, documentation around the new features and components can be found at the Product Documentation site.

For people familiar with previous version of Red Hat A-MQ (current release 6.3), you will notice the changes immediately. First, the distribution no longer comes packaged inside a Karaf container by default. Rather, it is a standalone product with a set of scripts that allow you to create broker topologies.

For example, in previous releases my first steps after downloading JBoss A-MQ was:

  1. Update /etc/users.properties to enable a user login.
  2. Update /etc/activemq.xml to make configurations such as persistence, destinations, and topology.
  3. Start the karaf container via /bin/karaf

In Artemis, the process is:

  1. Execute ${ARTEMIS_HOME}/bin/artemis create <options> myBroker.
  2. This creates an installation, in which you then can execute ${BROKER_HOME}/bin/artemis run.

So as you can see, the ceremony around creating and configuring a broker is different.

In future posts, I will discuss other changes in the Artemis release, but for now I will discuss the create broker process in great detail.

As discussed in Red Hat A-MQ 7.0-Beta documentation, this is a typical example of creating a broker:

$ sudo mkdir /var/lib/amq7
$ cd /var/lib/amq7
$ sudo <ARTEMIS_INSTALL_DIR>/bin/artemis create myBroker

This will invoke an interactive process that specifies the username, password, access. But what if you wanted to a complete list of all options for creating a broker? Well, here you go:

--host : The host name of the broker (Default: 0.0.0.0 or input if clustered).
--ping : A comma separated string to be passed on to the broker config as network-check-list. The broker will shutdown when all these addresses are unreachable.
--default-port : The port number to use for the main 'artemis' acceptor (Default: 61616).
--http-port : The port number to use for embedded web server (Default: 8161).
--ssl-key : The key store path for embedded web server
--ssl-key-password : The key store password.
--use-client-auth : If the embedded server requires client authenticiation.
--ssl-trust : The trust store path in case of client authentication.
--ssl-trust-password : The trust store password.
--name : The name of the broker (Default: same as host).
--port-offset : Off sets the ports of every acceptor.
--force : Overwrite configuration at destination directory.
--home : Directory where ActiveMQ Artemis is installed.
--data : Directory where ActiveMQ Data is used. Paths are relative to artemis.instance.
--clustered : Enable clustering.
--max-hops : Number of hops on the cluster configuration.
--message-load-balancing : Load balancing policy on cluster. [ON_DEMAND (default) | STRICT | OFF].
--replicated : Enable broker replication.
--shared-store : Enable broker shared store.
--slave : Valid for shared store or replication: this is a slave server.
--failover-on-shutdown : Valid for shared store: will shutdown trigger a failover? (Default : false).
--cluster-user : The cluster user to use for clustering. (Default: input)
--cluster-password : The cluster password to use for clustering. (Default: input).
--encoding : The encoding that text files should use.
--java-options : Extra java options to be passed to the profile.
--allow-anonymous : Enables anonymous configuration on security, opposite of --require-login (Default: input).
--require-login : This will configure security to require user / password, opposite of --allow-anonymous.
--no-autotune : Disable auto tuning on the journal.
--user : The username (Default: input).
--password : The user's password (Default: input).
--role : The name of the role created (Default: input).
--no-web : This will remove the web serer definition from bootstrap.xml.
--queues : comma separated list of jms queues.
--topics : comma separated list of jms topics.
--aio : sets the journal as asyncio.
--nio : sets the journal as nio.
--disable-persistence : Disable message persistence to the journal.
--no-ampq-acceptor : Disable the AMQP specific acceptor.
--no-mqtt-acceptor : Disable the MQTT specific acceptor.
--no-stomp-acceptor : Disable the STOMP specific acceptor.
--no-hornetq-acceptor : Disable the HornetQ specific acceptor.
--no-fsync : Disable usage of fdatasync (channel.force(false) from java nio) on the journal

Those are all the options available as of 7.0-Beta, and for most purposes it covers the majority of what is needed to created a broker. Once the broker is created, you can then edit the /etc/broker.xml to make any further changes as required.

But what if you wanted to provision an environment and absolutely did not want to make further edits to broker.xml? Is there a way to have complete control of all text in the broker.xml? Yes!

This is accomplished by traversing to the ${ARTEMIS_HOME}/etc directory. By default, the /etc directory contains the following:

etc/org/apache/activemq/artemis/cli/commands/etc/artemis.profile.cmd
etc/org/apache/activemq/artemis/cli/commands/etc/artemis.profile
etc/org/apache/activemq/artemis/cli/commands/etc/bootstrap-web-settings.txt

You will notice that these files contain the text that is ‘copied’ over to the broker configuration files such as broker.xml during the creation process. There are a number of other files that are not included, but if you were to add them to this directory then it would override the default configuration that is stored in the artemis-cli.jar.

For a complete list of the files, you can take a look at the defaults stored in source code for Artemis. For example, what if you wanted to override the default broadcast-group name, discovery-group name, or cluster-connection name? To accomplish this, just create the following file

/etc/org/apache/activemq/artemis/cli/commands/etc/cluster-settings.txt

And place the following text in the file:

<broadcast-groups>
<broadcast-group name="bg-fancyBroadcastName">
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
<broadcast-period>5000</broadcast-period>
<connector-ref>artemis</connector-ref>
</broadcast-group>
</broadcast-groups>
<discovery-groups>
<discovery-group name="dg-fancyDiscoveryName">
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
<refresh-timeout>10000</refresh-timeout>
</discovery-group>
</discovery-groups>
<cluster-connections>
<cluster-connection name="fancyCluster">
<address>jms</address>
<connector-ref>artemis</connector-ref>
<message-load-balancing>${message-load-balancing}</message-load-balancing>
<max-hops>${max-hops}</max-hops>
<discovery-group-ref discovery-group-name="dg-fancyDiscoveryName"/
</cluster-connection>
</cluster-connections>

This will cause the artemis ‘create’ command to pick up this file on next execution instead of the default file. This pattern can be applied for any part of the broker.xml, bootstrap.xml, or even the artemis shell scripts. Just add your version of the file in /etc directory and it gets picked up!

Now why would you want to do this? Perhaps you want to minimize the amount of text editing performed by a provisioning tool such as ansible, puppet, simple scripting, or the creation of docker images. It *may* also be easier to track configurations in a git repository and have tools fetch those defaults during deployment instead of trying to make decisions during the provision.

So there is a complete list of all the ways to configure the ‘artemis create broker’ command, as well as a process to override the defaults included in the ‘create’ command. Good luck with creating new brokers and in future posts we will take a look at the features in Artemis and differences from the current ActiveMQ release.