The bootstrap configuration file, <broker-instance-dir>/etc/bootstrap.xml, is read when the broker first starts. It is used to configure the web server, security, and the broker configuration file.

<broker xmlns="http://activemq.org/schema">
   <jaas-security domain="activemq"/>
   <server configuration="file:${artemis.instance}/etc/broker.xml"/>
   <!-- The web server is only bound to loalhost by default -->
   <web bind="http://localhost:8161" path="web">
       <app url="jolokia" war="jolokia-war-1.3.2.redhat-1.war"/>
       <app url="hawtio" war="hawtio-web.war"/>
       <app url="artemis-plugin" war="artemis-plugin.war"/>
   </web>
</broker>

Note that you can change the location for the broker.xml configuration file and for the bound url of the web server and its applications, including A-MQ Console.

For more details on the console persistence, see Using A-MQ 7 Console.

The broker accepts AMQP SASL Authentication and will use this to map onto the underlying session created for the connection so you can use the normal broker security configuration.

An AMQP link is a uni-directional transport for messages between a source and a target, i.e. a client and the broker. A link will have an endpoint of which there are two kinds, a sender and a receiver. At the broker, a sender will have its messages converted into a broker message and forwarded to its destination or target. A receiver will map onto a broker’s consumer and convert broker messages back into AMQP messages before being delivered.

If an AMQP link is dynamic, a temporary queue will be created and either the remote source or the remote target address will be set to the name of the temporary queue. If the link is not dynamic, the address of the remote target or source will be used for the queue. If the remote target or source does not exist, an exception will be sent.

Although AMQP has no notion of topics it is still possible to treat AMQP consumers or receivers as subscriptions rather than just consumers on a queue. By default any receiving link that attaches to an address with the prefix jms.topic. will be treated as a subscription and a subscription queue will be created. If the Terminus Durability is either UNSETTLED_STATE or CONFIGURATION then the queue will be made durable, similar to a JMS durable subscription and given a name made up from the container ID and the link name, something like my-container-id:my-link-name. if the Terminus Durability is configured as NONE then a volatile queue will be created.

The prefix can be changed by configuring the Acceptor and setting the pubSubPrefix like so

<acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;pubSubPrefix=foo.bar.</acceptor>

A-MQ Broker also supports the qpid-jms client and will respect its use of topics regardless of the prefix used for the address.

An AMQP links target can also be a Coordinator, the Coordinator is used to handle transactions. If a coordinator is used the underlying HormetQ session will be transacted and will be either rolled back or committed via the coordinator.

MQTT offers 3 quality of service levels.

Each message (or topic subscription) can define a quality of service that is associated with it. The quality of service level defined on a topic is the maximum level a client is willing to accept. The quality of service level on a message is the desired quality of service level for this message. The broker will attempt to deliver messages to subscribers at the highest quality of service level based on what is defined on the message and topic subscription.

Each quality of service level offers a level of guarantee by which a message is sent or received:

MQTT has an interesting feature in which messages can be "retained" for a particular address. This means that once a retain message has been sent to an address, any new subscribers to that address will receive the last sent retain message before any others messages, this happens even if the retained message was sent before a client has connected or subscribed. An example of where this feature might be useful is in environments such as IoT where devices need to quickly get the current state of a system when they are on boarded into a system.

A will message can be sent when a client initially connects to a broker. Clients are able to set a "will message" as part of the connect packet. If the client abnormally disconnects, say due to a device or network failure the broker will proceed to publish the will message to the specified address (as defined also in the connect packet). Other subscribers to the will topic receive the will message and can react to it saccordingly. This feature can be useful in an IoT style scenario to detect errors across a potentially large scale deployment of devices.

MQTT addresses are hierarchical much like a file system, and use "/" character to separate hierarchical levels. Subscribers are able to subscribe to specific topics or to whole branches of a hierarchy.

To subscribe to branches of an address hierarchy a subscriber can use wild cards.

There are 2 types of wild card in MQTT:

The broker provides native support for Stomp. To be able to send and receive Stomp messages, configure a NettyAcceptor with a protocols parameter set to have stomp:

<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor>

With this configuration, the broker will accept Stomp connections on the port 61613 (which is the default port of the Stomp brokers).

See the stomp example located under <install-dir>/examples/protocols which shows how to configure a broker with Stomp.

The broker currently does not support virtual hosting, which means the 'host' header in CONNECT frame will be ignored.

Message acknowledgements are not transactional. The ACK frame can not be part of a transaction (it will be ignored if its transaction header is set).

When receiving Stomp messages via a JMS consumer or a QueueBrowser, the messages by default will not contain any JMS properties, such as JMSMessageID. Because this may inconvenience clients who want to use an ID, the broker provides a parameter to set a message ID on each incoming Stomp message. If you want each Stomp message to have a unique ID, just set the stompEnableMessageId to true, as in the example below:

<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor>

When the server starts with the above setting, each stomp message sent through this acceptor will have an extra property added. The property key is amq-message-id and the value is a String representation of a long type internal message id prefixed with “STOMP”, like:

amq-message-id : STOMP12345

If stomp-enable-message-id is not specified in the configuration, the default is false.

Stomp clients may send very large bodies of frames which can exceed the size of the brokers server’s internal buffer, causing unexpected errors. To prevent this situation from happening, the broker provides a Stomp configuration attribute stompMinLargeMessageSize. This attribute can be configured inside a stomp acceptor, as a parameter. For example:

<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240</acceptor>

The type of this attribute is integer. When this attributed is configured, the broker will check the size of the body of each Stomp frame coming from connections established with this acceptor. If the size of the body is equal to or greater than the value of stompMinLargeMessageSize, the message will be persisted as a large message. When a large message is delivered to a stomp consumer, the HorentQ server will automatically handle the conversion from a large message to a normal message, before sending it to the client.

If a large message is compressed, the server will uncompressed it before sending it to stomp clients. The default value of stompMinLargeMessageSize is the same as the default value of [min-large-message-size](#large-messages.core.config).

The broker specifies a minimum value for both client and server heart-beat intervals. The minimum interval for both client and server heartbeats is 500 milliseconds. That means if a client sends a CONNECT frame with heartbeat values lower than 500, the server will default the value to 500 milliseconds regardless of the values of the heart-beat header in the frame.

<acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTtl=20000</acceptor>

Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and broker Core API, our Stomp implementation checks for presence of the content-length header to decide how to map a Stomp message to a JMS message or a Core message.

If the Stomp message does not have a content-length header, it will be mapped to a JMS TextMessage or a Core message with a single nullable SimpleString in the body buffer.

Alternatively, if the Stomp message has a content-length header, it will be mapped to a JMS BytesMessage or a Core message with a byte[] in the body buffer.

The same logic applies when mapping a JMS message or a Core message to Stomp. A Stomp client can check the presence of the content-length header to determine the type of the message body (String or bytes).

Stomp clients deal with destinations when sending messages and subscribing. Destination names are string values which are mapped to some form of destination on the server - how the server translates these is left to the server implementation.

In brokers, these destinations are mapped to addresses and queues. When a Stomp client sends a message (using a SEND frame), the specified destination is mapped to an address. When a Stomp client subscribes (or unsubscribes) for a destination (using a SUBSCRIBE or UNSUBSCRIBE frame), the destination is mapped to a broker queue.

JMS destinations are also mapped to broker addresses and queues. If you want to use Stomp to send messages to JMS destinations, the Stomp destinations must follow the same convention:

Aside from having no authentication at all, "anonymous access" is the most basic configuration. In this configuration, any user who connects without credentials or with the wrong credentials will be authenticated automatically and assigned a specific user and role. This functionality is provided by the "Guest" login module.

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule required
      org.apache.activemq.jaas.guest.user="guest"
      org.apache.activemq.jaas.guest.role="guest";
};

In this configuration the "Guest" login module will assign users the username "guest" and the role "guest". This is relevant for role-based authorization which is discussed in a subsequent section.

The "entry" is "activemq" and that name would be referenced in bootstrap.xml like so:

<jaas-security domain="activemq"/>

Guest Login Module Details

The guest login module allows users without credentials (and, depending on how it is configured, possibly also users with invalid credentials) to access the broker. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule.

It is common for the guest login module to be chained with another login module, such as a properties login module. Read more about that use-case in the Section 7.1.5, “Configuring Multiple Login Modules for Authentication” section.

When basic username and password validation is required the simplest option is to use the "Properties" login module. This login module will check the user’s credentials against a set of local property files. Here’s an example login.config:

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required
        org.apache.activemq.jaas.properties.user="users.properties"
        org.apache.activemq.jaas.properties.role="roles.properties";
};

The user properties file follows the pattern of user=password. For example:

user1=secret
user2=swordfish
user3=myPassword

There are 3 users defined here - user1, user2, and user3. The user1 user has a password of secret while user2 has a password of swordfish and user3 has a password of myPassword.

The role properties file follows the pattern of role=user where the user can be a comma delimited list of users in that particular role. For example:

admin=user1,user2
developer=user3

There are 2 groups defined here - admin and developer. The users user1 and user2 belong to the admin role and the user user3 belongs to the developer role.

The "entry" is "activemq" and that name would be referenced in bootstrap.xml like so:

<jaas-security domain="activemq"/>

Basic User and Password Login Module Details

The JAAS properties login module provides a simple store of authentication data, where the relevant user data is stored in a pair of flat files. This is convenient for demonstrations and testing, but for an enterprise system, the integration with LDAP is preferable. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule.

In the context of the properties login module, the users.properties file consists of a list of properties of the form, UserName=Password. For example, to define the users system, user, and guest, you could create a file like the following:

system=manager
user=password
guest=password

The roles.properties file consists of a list of properties of the form, Role=UserList, where UserList is a comma-separated list of users. For example, to define the roles admins, users, and guests, you could create a file like the following:

admins=system
users=system,user
guests=guest

The JAAS certificate authentication login module must be used in combination with SSL and the clients must be configured with their own certificate. In this scenario, authentication is actually performed during the SSL/TLS handshake, not directly by the JAAS certificate authentication plug-in.

The role of the plug-in is as follows:

The JAAS certificate login module stores a collection of certificate DNs in a pair of flat files. The files associate a username and a list of group IDs with each DN.

The certificate login module is implemented by org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule.

The following activemq login entry shows how to configure certificate login module in the login.config file:

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
        debug=true
        org.apache.activemq.jaas.textfiledn.user="users.properties"
        org.apache.activemq.jaas.textfiledn.role="roles.properties";
};

In the preceding example, the JAAS realm is configured to use a single org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule login module. The options supported by this login module are as follows:

In the context of the certificate login module, the users.properties file consists of a list of properties of the form, UserName=StringifiedSubjectDN. For example, to define the users, system, user, and guest, one could create a file like the following:

system=CN=system,O=Progress,C=US
user=CN=humble user,O=Progress,C=US
guest=CN=anon,O=Progress,C=DE

Each username is mapped to a subject DN, encoded as a string (where the string encoding is specified by RFC 2253). For example, the system username is mapped to the CN=system,O=Progress,C=US subject DN. When performing authentication, the plug-in extracts the subject DN from the received certificate, converts it to the standard string format, and compares it with the subject DNs in the users.properties file by testing for string equality. Consequently, you must be careful to ensure that the subject DNs appearing in the users.properties file are an exact match for the subject DNs extracted from the user certificates.

Note: Technically, there is some residual ambiguity in the DN string format. For example, the domainComponent attribute could be represented in a string either as the string, DC, or as the OID, 0.9.2342.19200300.100.1.25. Normally, you do not need to worry about this ambiguity. But it could potentially be a problem, if you changed the underlying implementation of the Java security layer.

The easiest way to obtain the subject DNs from the user certificates is by invoking the keytool utility to print the certificate contents. To print the contents of a certificate in a keystore, perform the following steps:

The roles.properties file consists of a list of properties of the form, Role=UserList, where UserList is a comma-separated list of users. For example, to define the roles admins, users, and guests, you could create a file like the following:

admins=system
users=system,user
guests=guest

The LDAP login module enables authentication and authorization by checking the incoming credentials against user data stored in a central X.500 directory server. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule.

Here’s an example login.config:

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required
        debug=true
        initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
        connectionURL="ldap://localhost:1024"
        connectionUsername="uid=admin,ou=system"
        connectionPassword=secret
        connectionProtocol=s
        authentication=simple
        userBase="ou=system"
        userSearchMatching="(uid={0})"
        userSearchSubtree=false
        roleBase="ou=system"
        roleName=cn
        roleSearchMatching="(member=uid={1},ou=system)"
        roleSearchSubtree=false
        ;
};

Add user entries under the node specified by the userBase option. When creating a new user entry in the directory, choose an object class that supports the userPassword attribute (for example, the person or inetOrgPerson object classes are typically suitable). After creating the user entry, add the userPassword attribute, to hold the user’s password.

If role data must be stored in dedicated role entries (where each node represents a particular role), create a role entry as follows. Create a new child of the roleBase node, where the objectClass of the child is groupOfNames. Set the cn (or whatever attribute type is specified by roleName) of the new child node equal to the name of the role/group. Define a member attribute for each member of the role/group, setting the member value to the DN of the corresponding user (where the DN is specified either fully, uid=jdoe,ou=User,ou=ActiveMQ,ou=system, or partially, uid=jdoe).

If roles need to be added to user entries, that requires directory schema customization by adding a suitable attribute type to the user entry’s object class. The chosen attribute type must be capable of handling multiple values.

It is possible to combine login modules to accommodate more complex use-cases. The most common reason to combine login modules is to support authentication for both anonymous users and users who submit credentials.

The following snippet shows how to configure a JAAS login entry for the use case where users with no credentials or invalid credentials are logged in as guests (via the guest login module) and users who submit valid credentials are logged in with the corresponding role/permissions (via the properties login module).

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
      debug=true
      org.apache.activemq.jaas.properties.user="users.properties"
      org.apache.activemq.jaas.properties.role="roles.properties";

  org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
      debug=true
      org.apache.activemq.jaas.guest.user="guest"
      org.apache.activemq.jaas.guest.role="restricted";
};

Depending on the user login data, authentication proceeds as follows:

The following example shows how to configure a JAAS login entry for the use case where only those users with no credentials are logged in as guests. To support this use case, you must set the credentialsInvalidate option to true in the configuration of the guest login module. One should also note that, compared with the preceding example, the order of the login modules is reversed and the flag attached to the properties login module is changed to requisite.

activemq {
    org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
        debug=true
       credentialsInvalidate=true
       org.apache.activemq.jaas.guest.user="guest"
       org.apache.activemq.jaas.guest.role="guests";

    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite
        debug=true
        org.apache.activemq.jaas.properties.user="users.properties"
        org.apache.activemq.jaas.properties.role="roles.properties";
};

Depending on the user login data, authentication proceeds as follows:

Here is a simple example of what might go in broker.xml to allow message production on an address named queue1:

<security-settings>
    <security-setting match="queue1">
        <permission type="send" roles="producer"/>
    </security-setting>
</security-settings>

The match of the <security-setting> defines the name of the address to which the permission should apply, queue1 in this case. The send permission is granted to users in the producer role.

Here is a simple example of what might go in broker.xml to allow message consumption on an address named queue1:

<security-settings>
    <security-setting match="queue1">
        <permission type="consume" roles="consumer"/>
    </security-setting>
</security-settings>

The match of the <security-setting> defines the name of the address to which the permission should apply, queue1 in this case. The consume permission is granted to users in the consumer role.

Here is what might go in broker.xml to allow complete access to addresses and and queues. This would be useful, for example, in a development scenario where anonymous authentication was configured to assign the role guest to every user:

<security-settings>
    <security-setting match="#">
        <permission type="createDurableQueue" roles="guest"/>
        <permission type="deleteDurableQueue" roles="guest"/>
        <permission type="createNonDurableQueue" roles="guest"/>
        <permission type="deleteNonDurableQueue" roles="guest"/>
        <permission type="send" roles="guest"/>
        <permission type="consume" roles="guest"/>
        <permission type="manage" roles="guest"/>
    </security-setting>
</security-settings>

The match of the <security-setting> defines a wildcard for the address to which the permission should apply, # in this case. All permissions are granted to users in the guest role.

For information about more complex use-cases see the Section 7.2.5, “Configure Multiple Security Settings for Address Groups and Sub-groups” section.

The LegacyLDAPSecuritySettingPlugin security-setting-plugin will read the security information that was previously handled by LDAPAuthorizationMap and the cachedLDAPAuthorizationMap in Apache ActiveMQ 5.x and turn it into corresponding security settings where possible. The security implementations of the two brokers do not match perfectly

so some translation must occur to achieve near equivalent functionality.

Here is an example of the plugin’s configuration:

<security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
   <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
   <setting name="connectionURL" value="ldap://localhost:1024"/>
   <setting name="connectionUsername" value="uid=admin,ou=system"/>
   <setting name="connectionPassword" value="secret"/>
   <setting name="connectionProtocol" value="s"/>
   <setting name="authentication" value="simple"/>
</security-setting-plugin>

The name of the queue or topic defined in LDAP will serve as the "match" for the security-setting, the permission value will be mapped from the ActiveMQ 5.x type to the Artemis type, and the role will be mapped as-is. Since the name of the queue or topic coming from LDAP will server as the "match" for the security-setting the security-setting may not be applied as expected to JMS destinations since Artemis always prefixes JMS destinations with "jms.queue." or "jms.topic." as necessary.

ActiveMQ 5.x only has 3 permission types - read, write, and admin. These permission types are described on their website. However, as described previously, ActiveMQ Artemis has 6 permission types - createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue, send, consume, and manage. Here’s how the old types are mapped to the new types:

As mentioned, there are a few places where a translation was performed to achieve some equivalence.:

Let us take a simple example, here’s a security block from

broker.xml file:

<security-setting match="globalqueues.europe.#">
   <permission type="createDurableQueue" roles="admin"/>
   <permission type="deleteDurableQueue" roles="admin"/>
   <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
   <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
   <permission type="send" roles="admin, europe-users"/>
   <permission type="consume" roles="admin, europe-users"/>
</security-setting>

The ‘#’ character signifies "any sequence of words". Words are delimited by the ‘.’ character. For a full description of the wildcard syntax please see [Understanding the Wildcard Syntax](wildcard-syntax.md). The above security block applies to any address that starts with the string "globalqueues.europe.":

Only users who have the admin role can create or delete durable queues bound to an address that starts with the string "globalqueues.europe."

Any users with the roles admin, guest, or europe-users can create or delete temporary queues bound to an address that starts with the string "globalqueues.europe."

Any users with the roles admin or europe-users can send messages to these addresses or consume messages from queues bound to an address that starts with the string "globalqueues.europe."

The mapping between a user and what roles they have is handled by the security manager. Apache ActiveMQ Artemis ships with a user manager that reads user credentials from a file on disk, and can also plug into JAAS or JBoss Application Server security.

For more information on configuring the security manager, please see 'Changing the Security Manager'.

There can be zero or more security-setting elements in each xml file. Where more than one match applies to a set of addresses the more specific match takes precedence.

Let us look at an example of that, here’s another security-setting block:

<security-setting match="globalqueues.europe.orders.#">
   <permission type="send" roles="europe-users"/>
   <permission type="consume" roles="europe-users"/>
</security-setting>

In this security-setting block the match 'globalqueues.europe.orders.#' is more specific than the previous match 'globalqueues.europe.\#'. So any addresses which match 'globalqueues.europe.orders.\#' will take their security settings only from the latter security-setting block.

Note that settings are not inherited from the former block. All the settings will be taken from the more specific matching block, so for the address 'globalqueues.europe.orders.plastics' the only permissions that exist are send and consume for the role europe-users. The permissions createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue are not inherited from the other security-setting block.

By not inheriting permissions, it allows you to effectively deny permissions in more specific security-setting blocks by simply not specifying them. Otherwise it would not be possible to deny permissions in sub-groups of addresses.

One-way TLS is configured in the URL of the relevant acceptor in broker.xml. Here is a very basic acceptor configuration which does not use TLS:

<acceptor name="artemis">tcp://0.0.0.0:61616</acceptor>

Here is that same acceptor configured to use one-way TLS:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>

This acceptor uses 3 additional parameters - sslEnabled, keyStorePath, and keyStorePassword. These 3, at least, are required to enable one-way TLS.

Two-way TLS uses the same sslEnabled, keyStorePath, and keyStorePassword properties as one-way TLS, but it adds needClientAuth to tell the client it should present a certificate of its own. For example:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>

This configuration assumes that the client’s certificate will be signed by a trusted provider. If the client’s certificate is not signed by a trusted provider (e.g., it is self-signed) then the server will need to import the client’s certificate into a trust-store and configure the acceptor with trustStorePath and trustStorePassword. For example:

<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>

TLS Configuration Details

A-MQ Broker supports multiple protocols, and each protocol and platform will have different ways to specify TLS parameters. However, in the case of a client using the Core protocol (e.g., a bridge) the TLS parameters are configured on the connector URL much like on the broker’s acceptor.

With a symmetric cluster, every node in the cluster is connected to every other node in the cluster. This means that every node in the cluster is no more than one hop away from every other node.

To form a symmetric cluster, every node in the cluster defines a cluster connection with the attribute max-hops set to 1. Typically, the cluster connection will use broker discovery in order to know what other brokers in the cluster it should connect to, although it is possible to explicitly define each target broker too in the cluster connection if, for example, UDP is not available on your network.

With a symmetric cluster, each node knows about all the queues that exist on all of the other nodes, and what consumers they have. With this knowledge, it can determine how to load balance and redistribute messages around the nodes.

With a chain cluster, each node in the cluster is not connected to every node in the cluster directly. Instead, the nodes form a chain with a node on each end of the chain and all other nodes just connecting to the previous and next nodes in the chain.

An example of a chain cluster would be a three node chain consisting of nodes A, B and C. Node A is hosted in one network and has many producer clients connected to it sending order messages. Due to corporate policy, the order consumer clients need to be hosted in a different network, and that network is only accessible via a third network. In this setup, node B acts as a mediator with no producers or consumers on it. Any messages arriving on node A will be forwarded to node B, which will in turn forward them to node C where they can be consumed. Node A does not need to directly connect to C, but all of the nodes can still act as a part of the cluster.

To set up a cluster in this way, node A would define a cluster connection that connects to node B, and node B would define a cluster connection that connects to node C. In this case, the cluster connections only need to be in one direction, because messages are moving from node A→B→C and never from C→B→A.

For this topology, you would set max-hops to 2. With a value of 2, the knowledge of what queues and consumers that exist on node C would be propagated from node C to node B to node A. Node A would then know to distribute messages to node B when they arrive, even though node B has no consumers itself. It would know that a further hop away is node C, which does have consumers.

If the size of a cluster changes frequently in your environment, you can scale it up or down with no message loss (even for non-durable messages).

You can scale up clusters by adding nodes, in which case there is no risk of message loss. Similarly, you can scale clusters down by removing nodes. However, to prevent message loss, you must first configure the broker to send its messages to another node in the cluster.

To scale down a cluster:

Broker discovery uses UDP, multicast, or JGroups to broadcast broker connection settings.

A broadcast group is the means by which a broker broadcasts connectors over the network. A connector defines a way in which a client (or other broker) can make connections to the broker. For more information about connectors, see Chapter 4, Configuring Network Connections.

The broadcast group takes a set of connector pairs. Each connector pair contains connection settings for a live and backup broker (if one exists), and broadcasts them on the network. Depending on which broadcasting technique you use to configure the cluster, the connector pair information is broadcasted through either UDP or JGroups.

Broadcast groups are defined in the broker configuration file broker.xml. There can be many broadcast groups per broker. All broadcast groups must be defined in a broadcast-groups element.

<broadcast-groups>
   <broadcast-group name="my-broadcast-group">
      <local-bind-address>172.16.9.3</local-bind-address>
      <local-bind-port>5432</local-bind-port>
      <group-address>231.7.7.7</group-address>
      <group-port>9876</group-port>
      <broadcast-period>2000</broadcast-period>
      <connector-ref connector-name="netty-connector"/>
   </broadcast-group>
</broadcast-groups>

<broadcast-groups>
   <broadcast-group name="my-broadcast-group">
      <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
      <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
      <broadcast-period>2000</broadcast-period>
    <connector-ref connector-name="netty-connector"/>
   </broadcast-group>
</broadcast-groups>

<config xmlns="urn:org:jgroups"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/JGroups-3.0.xsd">
 <TCP loopback="true"
    recv_buf_size="20000000"
    send_buf_size="640000"
    discard_incompatible_packets="true"
    max_bundle_size="64000"
    max_bundle_timeout="30"
    enable_bundling="true"
    use_send_queues="false"
    sock_conn_timeout="300"

    thread_pool.enabled="true"
    thread_pool.min_threads="1"
    thread_pool.max_threads="10"
    thread_pool.keep_alive_time="5000"
    thread_pool.queue_enabled="false"
    thread_pool.queue_max_size="100"
    thread_pool.rejection_policy="run"

    oob_thread_pool.enabled="true"
    oob_thread_pool.min_threads="1"
    oob_thread_pool.max_threads="8"
    oob_thread_pool.keep_alive_time="5000"
    oob_thread_pool.queue_enabled="false"
    oob_thread_pool.queue_max_size="100"
    oob_thread_pool.rejection_policy="run"/>

 <FILE_PING location="../file.ping.dir"/>
 <MERGE2 max_interval="30000"
    min_interval="10000"/>
 <FD_SOCK/>
 <FD timeout="10000" max_tries="5" />
 <VERIFY_SUSPECT timeout="1500"  />
 <BARRIER />
 <pbcast.NAKACK
    use_mcast_xmit="false"
    retransmit_timeout="300,600,1200,2400,4800"
    discard_delivered_msgs="true"/>
 <UNICAST timeout="300,600,1200" />
 <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
    max_bytes="400000"/>
 <pbcast.GMS print_local_addr="true" join_timeout="3000"
    view_bundling="true"/>
 <FC max_credits="2000000"
    min_threshold="0.10"/>
 <FRAG2 frag_size="60000"  />
 <pbcast.STATE_TRANSFER/>
 <pbcast.FLUSH timeout="0"/>
</config>

While the broadcast group defines how connector information is broadcast from a broker, a discovery group defines how connector information is received from a broadcast endpoint (a UDP multicast address or JGroup channel).

A discovery group maintains a list of connector pairs - one for each broadcast by a different broker. As it receives broadcasts on the broadcast endpoint from a particular broker, it updates its entry in the list for that broker.

If it has not received a broadcast from a particular broker for a length of time, it will remove that broker’s entry from its list.

Discovery groups are used in two places in the broker:

Although a discovery group always accepts broadcasts, its current list of available live and backup brokers is only used when an initial connection is made. After that point, broker discovery is performed over the normal broker connections.

For cluster connections, you define discovery groups in the broker.xml configuration file, in the discovery-groups element. You can define multiple discovery groups.

<discovery-groups>
   <discovery-group name="my-discovery-group">
      <local-bind-address>172.16.9.7</local-bind-address>
      <group-address>231.7.7.7</group-address>
      <group-port>9876</group-port>
      <refresh-timeout>10000</refresh-timeout>
   </discovery-group>
</discovery-groups>

<discovery-groups>
   <discovery-group name="my-broadcast-group">
      <jgroups-file>test-jgroups-file_ping.xml</jgroups-file>
      <jgroups-channel>activemq_broadcast_channel</jgroups-channel>
      <refresh-timeout>10000</refresh-timeout>
   </discovery-group>
</discovery-groups>

You can use JMS or the core API to configure a broker client to discover a list of brokers to which it can connect.

java.naming.factory.initial = ActiveMQInitialContextFactory
connectionFactory.myConnectionFactory=udp://231.7.7.7:9876

final String groupAddress = "231.7.7.7";

final int groupPort = 9876;

ConnectionFactory jmsConnectionFactory =
ActiveMQJMSClient.createConnectionFactory(new DiscoveryGroupConfiguration(groupAddress, groupPort,
                       new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)), JMSFactoryType.CF);

Connection jmsConnection1 = jmsConnectionFactory.createConnection();

Connection jmsConnection2 = jmsConnectionFactory.createConnection();

final String groupAddress = "231.7.7.7";
final int groupPort = 9876;
BrokerLocator factory = ActiveMQClient.createBrokerLocatorWithHA(new DiscoveryGroupConfiguration(groupAddress, groupPort,
                           new UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();

If you cannot use UDP on your network, you can discover brokers by configuring the connections with a list of possible brokers. This list can be a single broker that you know will always be available, or a list of brokers where at least one will be available.

If you provide a list of brokers, you do not need to know where every broker is going to be hosted. Instead, you can configure these brokers to connect to the reliable brokers. After they are connected, the connection details are propagated by the broker to which it is connected.

java.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory
connectionFactory.myConnectionFactory=(tcp://myhost:61616,tcp://myhost2:61616)

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "61616");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "61617");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);

ActiveMQConnectionFactory cf = ActiveMQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);

HashMap<String, Object> map = new HashMap<String, Object>();
map.put("host", "myhost");
map.put("port", "61616");
TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
HashMap<String, Object> map2 = new HashMap<String, Object>();
map2.put("host", "myhost2");
map2.put("port", "61617");
TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);

BrokerLocator locator = ActiveMQClient.createBrokerLocatorWithHA(server1, server2);
ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session = factory.createSession();

Cluster connections group brokers into clusters so that messages can be load-balanced between the nodes of the cluster. You can configure multiple cluster connections for each broker.

To configure cluster connections, in the broker.xml configuration file, add cluster-connection elements like the following:

<cluster-connections>
   <cluster-connection name="my-cluster">
      <address>jms</address>
      <connector-ref>netty-connector</connector-ref>
      <check-period>1000</check-period>
      <connection-ttl>5000</connection-ttl>
      <min-large-message-size>50000</min-large-message-size>
      <call-timeout>5000</call-timeout>
      <retry-interval>500</retry-interval>
      <retry-interval-multiplier>1.0</retry-interval-multiplier>
      <max-retry-interval>5000</max-retry-interval>
      <initial-connect-attempts>-1</initial-connect-attempts>
      <reconnect-attempts>-1</reconnect-attempts>
      <use-duplicate-detection>true</use-duplicate-detection>
      <message-load-balancing>ON_DEMAND</message-load-balancing>
      <max-hops>1</max-hops>
      <confirmation-window-size>32000</confirmation-window-size>
      <call-failover-timeout>30000</call-failover-timeout>
      <notification-interval>1000</notification-interval>
      <notification-attempts>2</notification-attempts>
      <discovery-group-ref discovery-group-name="my-discovery-group"/>
   </cluster-connection>
</cluster-connections>

In the above cluster connection, all parameters have been explicitly specified. You can configure the following parameters:

When creating connections between nodes of a cluster to form a cluster connection, the broker uses a cluster user and cluster password.

To configure the cluster user and password, in the broker.xml configuration file, specify the following:

<cluster-user>ACTIVEMQ.CLUSTER.ADMIN.USER</cluster-user>
<cluster-password>CHANGE ME!!</cluster-password>

You should change these values from their default, or remote clients will be able to make connections to the broker using the default values. The broker will also detect the default credentials when it starts, and display a warning.

The broker supports two different strategies for backing up a server shared store and replication. Which is configured via the ha-policy configuration element.

<ha-policy>
   <replication/>
</ha-policy>

or

<ha-policy>
   <shared-store/>
</ha-policy>

As well as these 2 strategies there is also a 3rd called live-only. This of course means there will be no Backup Strategy and is the default if none is provided, however this is used to configure scale-down, covered in a later chapter.

The ha-policy type configures which strategy a cluster should use to provide the backing up of a servers data. Within this configuration element is configured how a server should behave within the cluster, either as a master (live), slave (backup) or colocated (both live and backup). This would look something like:

<ha-policy>
   <replication>
      <master/>
   </replication>
</ha-policy>

or

<ha-policy>
   <shared-store/>
      <slave/>
   </shared-store/>
</ha-policy>

or

<ha-policy>
   <replication>
      <colocated/>
   </replication>
</ha-policy>

When using replication, the live and the backup servers do not share the same data directories, all data synchronization is done over the network. Therefore all (persistent) data received by the live server will be duplicated to the backup.

Notice that upon start-up the backup server will first need to synchronize all existing data from the live server before becoming capable of replacing the live server should it fail. So unlike when using shared storage, a replicating backup will not be a fully operational backup right after start-up, but only after it finishes synchronizing the data with its live server. The time it will take for this to happen will depend on the amount of data to be synchronized and the connection speed.

Replication will create a copy of the data at the backup. One issue to be aware of is: in case of a successful fail-over, the backup’s data will be newer than the one at the live’s storage. If you configure your live server to perform a failback to live server when restarted, it will synchronize its data with the backup’s. If both servers are shutdown, the administrator will have to determine which one has the latest data.

The replicating live and backup pair must be part of a cluster. The Cluster Connection also defines how backup servers will find the remote live servers to pair with. See Configure Clusters for details on how this is done, and how to configure a cluster connection. Notice that:

Within a cluster, there are two ways that a backup server will locate a live server to replicate from, these are:

As an example of using group-name, suppose you have 5 live servers and 6 backup servers. You could divide the servers into two groups.

After joining the cluster the backups with group-name=fish will search for live servers with group-name=fish to pair with. Since there is one backup too many, the fish will remain with one spare backup. Meanwhile, the 2 backups with group-name=bird will pair with live servers live4 and live5.

The backup will search for any live server that it is configured to connect to. It then tries to replicate with each live server in turn until it finds a live server that has no current backup configured. If no live server is available it will wait until the cluster topology changes and repeats the process.

Much like in the shared-store case, when the live server stops or crashes, its replicating backup will become active and take over its duties. Specifically, the backup will become active when it loses connection to its live server. This can be problematic because this can also happen because of a temporary network problem. In order to address this issue, the backup will try to determine whether it still can connect to the other servers in the cluster. If it can connect to more than half the servers, it will become active, if more than half the servers also disappeared with the live, the backup will wait and try reconnecting with the live. This avoids a split brain situation.

<ha-policy>
   <replication>
      <master/>
   </replication>
</ha-policy>
.
<cluster-connections>
   <cluster-connection name="my-cluster">
    ...
   </cluster-connection>
</cluster-connections>

<ha-policy>
   <replication>
      <slave/>
   </replication>
</ha-policy>

When using a shared store, both live and backup servers share the same entire data directory using a shared file system. This means the paging directory, journal directory, large messages and binding journal.

When failover occurs and a backup server takes over, it will load the persistent storage from the shared file system and clients can connect to it.

This style of high availability differs from data replication in that it requires a shared file system which is accessible by both the live and backup nodes. Typically this will be some kind of high performance Storage Area Network (SAN). Red Hat does not recommend you use Network Attached Storage (NAS), e.g. NFS mounts to store any shared journal (NFS is slow).

The advantage of shared-store high availability is that no replication occurs between the live and backup nodes, this means it does not suffer any performance penalties due to the overhead of replication during normal operation.

The disadvantage of shared store replication is that it requires a shared file system, and when the backup server activates it needs to load the journal from the shared store which can take some time depending on the amount of data in the store.

If you require the highest performance during normal operation, have access to a fast SAN and live with a slightly slower failover (depending on amount of data).

<ha-policy>
   <shared-store>
      <master/>
   </shared-store>
</ha-policy>
.
<cluster-connections>
   <cluster-connection name="my-cluster">
  ...
   </cluster-connection>
</cluster-connections>

<ha-policy>
   <shared-store>
      <slave/>
   </shared-store>
</ha-policy>

<ha-policy>
   <shared-store>
      <slave>
         <allow-failback>true</allow-failback>
      </slave>
   </shared-store>
</ha-policy>

<ha-policy>
   <replication>
      <master>
         <check-for-live-server>true</check-for-live-server>
      <master>
   </replication>
</ha-policy>

<ha-policy>
   <shared-store>
      <master>
         <failover-on-shutdown>true</failover-on-shutdown>
      </master>
   </shared-store>
</ha-policy>

<ha-policy>
   <shared-store>
      <slave>
         <allow-failback>true</allow-failback>
      </slave>
   </shared-store>
</ha-policy>

.HA Shared Store Slave Policy

11.1.3.3. Colocated Backup Servers

It is also possible when running standalone to colocate backup servers in the same JVM as another live server. Live Servers can be configured to request another live server in the cluster to start a backup server in the same JVM either using shared store or replication. The new backup server will inherit its configuration from the live server creating it apart from its name, which will be set to colocated_backup_n where n is the number of backups the server has created, and any directories and its Connectors and Acceptors which are discussed later on in this chapter. A live server can also be configured to allow requests from backups and also how many backups a live server can start. this way you can evenly distribute backups around the cluster. This is configured via the ha-policy element in the broker.xml file , as in the example below.

<ha-policy>
   <replication>
      <colocated>
         <request-backup>true</request-backup>
         <max-backups>1</max-backups>
         <backup-request-retries>-1</backup-request-retries>
         <backup-request-retry-interval>5000</backup-request-retry-interval>
         <master/>
         <slave/>
      </colocated>
   <replication>
</ha-policy>

The above example is configured to use replication, in this case the master and slave configurations must match those for normal replication as in the previous chapter. A shared-store ha policy is also supported.

<ha-policy>
   <replication>
      <colocated>
         <excludes>
            <connector-ref>remote-connector</connector-ref>
         </excludes>
      ...
</ha-policy>

An alternative to using Live/Backup groups is to configure scaledown. when configured for scale down a server can copy all its messages and transaction state to another live server. The advantage of this is that you do not need full backups to provide some form of HA, however there are disadvantages with this approach the first being that it only deals with a server being stopped and not a server crash. The caveat here is if you configure a backup to scale down.

Another disadvantage is that it is possible to lose message ordering. This happens in the following scenario, say you have 2 live servers and messages are distributed evenly between the servers from a single producer, if one of the servers scales down then the messages sent back to the other server will be in the queue after the ones already there, so server 1 could have messages 1,3,5,7,9 and server 2 would have 2,4,6,8,10, if server 2 scales down the order in server 1 would be 1,3,5,7,9,2,4,6,8,10.

<ha-policy>
   <live-only>
      <scale-down>
         <connectors>
            <connector-ref>server1-connector</connector-ref>
         </connectors>
      </scale-down>
   </live-only>
</ha-policy>

<ha-policy>
   <live-only>
      <scale-down>
         <discovery-group-ref discovery-group-name="my-discovery-group"/>
      </scale-down>
   </live-only>
</ha-policy>

<ha-policy>
   <live-only>
      <scale-down>
         ...
         <group-name>my-group</group-name>
      </scale-down>
   </live-only>
</ha-policy>

<ha-policy>
   <replication>
      <colocated>
         <backup-request-retries>44</backup-request-retries>
         <backup-request-retry-interval>33</backup-request-retry-interval>
         <max-backups>3</max-backups>
         <request-backup>false</request-backup>
         <backup-port-offset>33</backup-port-offset>
         <master>
            <group-name>purple</group-name>
            <check-for-live-server>true</check-for-live-server>
            <cluster-name>abcdefg</cluster-name>
         </master>
         <slave>
            <group-name>tiddles</group-name>
            <max-saved-replicated-journals-size>22</max-saved-replicated-journals-size>
            <cluster-name>33rrrrr</cluster-name>
            <restart-backup>false</restart-backup>
            <scale-down>
               <!--a grouping of servers that can be scaled down to-->
               <group-name>boo!</group-name>
               <!--either a discovery group-->
               <discovery-group-ref discovery-group-name="wahey"/>
            </scale-down>
         </slave>
      </colocated>
   </replication>
</ha-policy>

The brokers clients can be configured to receive knowledge of all live and backup servers, so that in event of connection failure at the client - live server connection, the client will detect this and reconnect to the backup server. The backup server will then automatically recreate any sessions and consumers that existed on each connection before failover, thus saving the user from having to hand-code manual reconnection logic.

Clients detect connection failure when it has not received packets from the server within the time given by client-failure-check-period. If the client does not receive data in good time, it will assume the connection has failed and attempt failover. Also if the socket is closed by the OS, usually if the server process is killed rather than the machine itself crashing, then the client will failover straight away.

Clients can be configured to discover the list of live-backup server groups in a number of different ways. They can be configured explicitly or probably the most common way of doing this is to use server discovery for the client to automatically discover the list. Alternatively, the clients can explicitly connect to a specific server and download the current servers and backups. For full details on how to configure server discovery, please See Configure Clusters for more information.

To enable automatic client failover, the client must be configured to allow non-zero reconnection attempts.

By default failover will only occur after at least one connection has been made to the live server. In other words, by default, failover will not occur if the client fails to make an initial connection to the live server - in this case it will simply retry connecting to the live server according to the reconnect-attempts property and fail after this number of attempts.

JMS provides a standard mechanism for getting notified asynchronously of connection failure: java.jms.ExceptionListener. Please consult the JMS javadoc or any good JMS tutorial for more information on how to use this.

The broker core API also provides a similar feature in the form of the class org.apache.activemq.artemis.core.client.SessionFailureListener

Any ExceptionListener or SessionFailureListener instance will always be called by the broker on event of connection failure, irrespective of whether the connection was successfully failed over, reconnected or reattached, however you can find out if reconnect or reattach has happened by either the failedOver flag passed in on the connectionFailed on SessionfailureListener or by inspecting the error code on the javax.jms.JMSException which will be one of the following:

JMSException error codes .HA Replication Colocation Policy

In some cases you may not want automatic client failover, and prefer to handle any connection failure yourself, and code your own manually reconnection logic in your own failure handler. This is known as application-level failover, since the failover is handled at the user application level.

To implement application-level failover, if you are using JMS then you need to set an ExceptionListener class on the JMS connection. The ExceptionListener will be called by the broker in the event that connection failure is detected. In your ExceptionListener, you would close your old JMS connections, potentially look up new connection factory instances from JNDI and creating new connections.

If you are using the core API, then the procedure is very similar: you would set a FailureListener on the core ClientSession instances.

You will also need to configure credentials for logging into HawtIO. When you create an instance of A-MQ Broker you will be prompted for a default user and role. To use this for the HawtIO login credentials, update the JAVA_ARGS property in the artemis.profile configuration file and add the default role. So, if you set the default role as admin then add the following.

The security realm and role used by HawtIO are configured in the <broker-instance-dir>/etc/artemis.profile file.

-Dhawtio.realm=activemq -Dhawtio.role=admin -Dhawtio.rolePrincipalClasses=org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal

By default HawtIO will use the default security realm of activemq, which is configured by default in the <broker-instance-dir>/etc/login.config file.

The role used by HawtIO should be configured in the <broker-instance-dir>/etc/artemis-roles.properties file. Any user that has been assigned this role will be allowed access to log in to the management console. For a full explanation of configuring security with the broker, refer to Configuring Security.

If you are using the default broker configuration, then simply go to http://localhost:8161/hawtio/login and log in using any user credentials that have the role configured for HawtIO.

After a successful login you will see an Artemis tab displayed. Click on this to see a screen like the following.

If you have installed HawtIO standalone and want to connect to a remote broker, you will need to connect to it by clicking on the connect tab and entering the Jolokia path.

You can access the HawtIO console securely using https. Use the following steps.

When clicking on the Artemis tab on the left you will see a sanitized version of the Artemis JMX tree. This is the entry point into the extra functionality that the Artemis HawtIO plugin gives you, as well as the the usual JMX attributes and operations. To view the full JMX tree, click on the JMX tab.

To Create a new JMS queue, click on the Queue folder in the JMX tree. In the Create tab, enter the name of the queue you want to create, and then click Create queue.

Alternatively, if the Queue folder is not showing, click on the Server folder in the JMX tree. In the Create tab, choose the queue option and click on Create queue.

Creating a topic is exactly the same as Creating a queue except that you either click on the Topic folder in the JMX tree or choose the Topic option when using the server option.

Sometimes it is desirable to test an installation by sending a test message or to simply send a message. To do this, choose the queue from the JMX tab that you want to send the message to and click on the Send tab. Fill in the message content and any headers and click on the Send message button.

It is also possible to browse a queue and inspect the messages in that queue. To do this, click on the queue you want to browse in the JMX tree and click on the Browse tab. By default, you will see the first 200 messages that are in the queue.

It is also possible to look at the message content by clicking on the message ID of the message you want to view. You will then see something like the following.

This screen will allow you to iterate over the browsed messages using the casette buttons and also move or delete the messages.

The Broker Diagram shows a visualisation of all the resources in an Artemis Topology, including brokers (master and slave), queues, topics and consumers. To view the diagram, click on the Diagram tab.

To control what appears in the diagram, click on the View drop down in the top right and choose what you want to appear.

There are some preferences that are needed for certain screens. These can be set by using the user drop down box in the top right hand corner and choosing the Preferences option and clicking on the Artemis tab.

JMS Resources (connection factories and destinations) can be created using the JMSServerControl class (with the ObjectName org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Server or the resource name jms.server).

The broker can be managed using JMX. The management API is exposed by the broker using MBeans interfaces. The broker registers its resources with the domain org.apache.activemq.

For example, the ObjectName to manage a JMS Queue exampleQueue is:

org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=JMS,serviceType=Queue,name="exampleQueue"

and the MBean is:

org.apache.activemq.artemis.api.jms.management.JMSQueueControl

The MBean’s ObjectName are built using the helper class org.apache.activemq.artemis.api.core.management.ObjectNameBuilder. You can also use jconsole to find the ObjectName of the MBeans you want to manage.

Managing the broker using JMX is identical to management of any Java Applications using JMX. It can be done by reflection or by creating proxies of the MBeans.

<jmx-management-enabled>false</jmx-management-enabled>

<jmx-domain>my.org.apache.activemq</jmx-domain>

{"timestamp":1422019706,"status":200,"request":{"mbean":"org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server","attribute":"Version","type":"read"},"value":"1.0.0.SNAPSHOT (Active Hornet, 126)"}

The core management API in A-MQ Broker is called by sending Core messages to a special address, the management address.

Management messages are regular Core messages with well-known properties that the server needs to understand to interact with the management API:

When such a management message is sent to the management address, The broker will handle it, extract the information, invoke the operation on the managed resources and send a management reply to the management message’s reply-to address (specified by ClientMessageImpl.REPLYTO_HEADER_NAME).

A ClientConsumer can be used to consume the management reply and retrieve the result of the operation (if any) stored in the reply’s body. For portability, results are returned as a JSON String rather than Java Serialization (the org.apache.activemq.artemis.api.core.management.ManagementHelper can be used to convert the JSON string to Java objects).

These steps can be simplified to make it easier to invoke management operations using Core messages:

For example, to find out the number of messages in the core queue exampleQueue:

ClientSession session = ...
ClientRequestor requestor = new ClientRequestor(session, "jms.queue.activemq.management");
ClientMessage message = session.createMessage(false);
ManagementHelper.putAttribute(message, "core.queue.exampleQueue", "messageCount");
session.start();
ClientMessage reply = requestor.request(m);
int count = (Integer) ManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");

Management operation name and parameters must conform to the Java interfaces defined in the management packages.

Names of the resources are built using the helper class org.apache.activemq.artemis.api.core.management.ResourceNames and are straightforward (core.queue.exampleQueue for the Core Queue exampleQueue, jms.topic.exampleTopic for the JMS Topic exampleTopic, etc.).

<management-address>jms.queue.activemq.management</management-address>

<security-setting match="jms.queue.activemq.management">
 <permission type="manage" roles="admin" />
</security-setting>

Using JMS messages to manage A-MQ Broker is very similar to using core API.

An important difference is that JMS requires a JMS queue to send the messages to (instead of an address for the core API).

The management queue is a special queue and needs to be instantiated directly by the client:

Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");

All the other steps are the same than for the Core API but they use JMS API instead:

For example, to know the number of messages in the JMS queue exampleQueue:

Queue managementQueue = ActiveMQJMSClient.createQueue("activemq.management");

QueueSession session = ...
QueueRequestor requestor = new QueueRequestor(session, managementQueue);
connection.start();
Message message = session.createMessage();
JMSManagementHelper.putAttribute(message, "jms.queue.exampleQueue", "messageCount");
Message reply = requestor.request(message);
int count = (Integer)JMSManagementHelper.getResult(reply);
System.out.println("There are " + count + " messages in exampleQueue");

The broker emits notifications to inform listeners of potentially interesting events (creation of new resources, security violation, etc.).

These notifications can be received by 3 different ways:

<management-notification-address>activemq.notifications</management-notification-address>

<!-- notifications will be consumed from "notificationsTopic" JMS Topic -->
<management-notification-address>jms.topic.notificationsTopic</management-notification-address>

Topic notificationsTopic = ActiveMQJMSClient.createTopic("notificationsTopic");

Session session = ...
MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic);
notificationConsumer.setMessageListener(new MessageListener()
{
   public void onMessage(Message notif)
   {
      System.out.println("------------------------");
      System.out.println("Received notification:");
      try
      {
         Enumeration propertyNames = notif.getPropertyNames();
         while (propertyNames.hasMoreElements())
         {
            String propertyName = (String)propertyNames.nextElement();
            System.out.format("  %s: %s\n", propertyName, notif.getObjectProperty(propertyName));
         }
      }
      catch (JMSException e)
      {
      }
      System.out.println("------------------------");
   }
});

Message counters can be used to obtain information on queues over time as The broker keeps a history on queue metrics.

They can be used to show trends on queues. For example, using the management API, it would be possible to query the number of messages in a queue at regular interval. However, this would not be enough to know if the queue is used: the number of messages can remain constant because nobody is sending or receiving messages from the queue or because there are as many messages sent to the queue than messages consumed from it. The number of messages in the queue remains the same in both cases but its use is widely different.

Message counters gives additional information about the queues:

<message-counter-enabled>true</message-counter-enabled>

<!-- keep history for a week -->
<message-counter-max-day-history>7</message-counter-max-day-history>
<!-- sample the queues every minute (60000ms) -->
<message-counter-sample-period>60000</message-counter-sample-period>

// retrieve a connection to the brokers MBeanServer
MBeanServerConnection mbsc = ...
JMSQueueControlMBean queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
   on,
   JMSQueueControl.class,
   false);
// message counters are retrieved as a JSON String
String counters = queueControl.listMessageCounter();
// use the MessageCounterInfo helper class to manipulate message counters more easily
MessageCounterInfo messageCounter = MessageCounterInfo.fromJSON(counters);
System.out.format("%s message(s) in the queue (since last sample: %s)\n",
messageCounter.getMessageCount(),
messageCounter.getMessageCountDelta());