Installing the Apache ActiveMQ Management Servlet – meshIQ

This article explains how to deploy the servlet into ActiveMQ and configure Jetty to expose the meshIQ Management REST API at /api/management.

The Apache ActiveMQ Management Servlet is a small web application which is installed directly into ActiveMQ. Once it's running, it allows to view and update the broker's activemq.xml configuration file over plain HTTP, no need to log into the server or edit the file.

Prerequisites

ActiveMQ is installed and configured.
Permission to modify the ActiveMQ Jetty configuration.

Procedure

Download the meshiq-mgmt.war file from https://data.meshiq.com/.
Deploy the WAR file

Copy the generated WAR file to ActiveMQ's webapps directory:
```
${ACTIVEMQ_HOME}/webapps/meshiq-mgmt.war
```

Update the ActiveMQ Configuration

Before editing the configuration, back up the existing jetty.xml file.

The configuration changes depend on the ActiveMQ version.

ActiveMQ 6.0.x–6.2.x

Depending on the structure of jetty.xml, use one of the following methods.

Method 1: Add the meshiq-mgmt Bean

Add the following meshiq-mgmt bean to ${activemq.conf}/jetty.xml to expose
the management servlet under /api/management.

<bean id="meshiq-mgmt" class="org.eclipse.jetty.webapp.WebAppContext">
<property name="contextPath" value="/api/management"/> 
<property name="war" value="${activemq.home}/webapps/meshiq-mgmt.war"/> 
<property name="logUrlOnStart" value="true"/> 
</bean>

Then add the meshiq-mgmt bean to the existing contexts collection:

<bean id="contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection">
    <property name="handlers">
        <list>
           <ref bean="meshiq-mgmt"/>
        </list>
    </property>
</bean>

Method 2: Add the WebAppContext Directly

If jetty.xml contains the following handler collection:

<bean id="secHandlerCollection" class="org.eclipse.jetty.server.handler.HandlerCollection">

add the following WebAppContext to its existing handlers list:

<bean class="org.eclipse.jetty.webapp.WebAppContext"> 
<property name="contextPath" value="/api/management"/> 
<property name="war" value="${activemq.home}/webapps/meshiq-mgmt.war"/> 
<property name="logUrlOnStart" value="true"/> 
</bean>

Do not add both methods. Use the method that matches the structure of your ActiveMQ jetty.xml.

ActiveMQ 6.3.x

ActiveMQ 6.3.x uses separate Jetty configuration files for the web application and its security.

Configure the Web Application

Edit ${ACTIVEMQ_CONF}/jetty/jetty-webapps.xml, Locate the existing Contexts configuration: <Configure class="org.eclipse.jetty.server.handler.ContextHandlerCollection" id="Contexts">

Add the following WebAppContext using the existing addHandler call:

<Call name="addHandler">
   <Arg>
     <New class="org.eclipse.jetty.ee11.webapp.WebAppContext">
       <Set name="contextPath">/api/management</Set>
       <Set name="war"><Property name="activemq.home" default="."/>/webapps/meshiq-mgmt.war</Set>
       <Set name="logUrlOnStart">true</Set>
     </New>
   </Arg>
 </Call>

Configure Security

Edit ${ACTIVEMQ_CONF}/jetty/jetty-security.xml, Locate the existing insertHandler configuration and add the management security handler to it.

<Call name="insertHandler">
   <Arg>
     <!-- Outermost: only allow configured client IPs to reach the console. -->
     <New class="org.eclipse.jetty.server.handler.InetAccessHandler">
       <Set name="handler">
        <!-- Path-based authorization; its tail is linked to Contexts by insertHandler. -->
         <New id="consoleSecurityHandler" class="org.eclipse.jetty.security.SecurityHandler$PathMapped">
<!-- ... -->
           <!-- Management Servlet (/api/management/*) is restricted to the admins role. -->
           <Call name="put">
             <Arg>/api/management/*</Arg>
             <Arg>
               <Call class="org.eclipse.jetty.security.Constraint" name="from">
                 <Arg><Array type="java.lang.String"><Item>admins</Item></Array></Arg>
               </Call>
             </Arg>
           </Call>

The following rule:

<Arg>/api/management/*</Arg>

applies the security rule to all URLs under /api/management/

The following configuration:

<Item>admins</Item>

restricts access to users who have the admins role.

Do not remove or replace the existing security configuration. Add the management security rule to the appropriate location in the existing jetty-security.xml.

Restart the ActiveMQ Broker

After completing the configuration changes, restart the ActiveMQ broker.

Verify the Management API

After ActiveMQ has restarted, verify that the management API is accessible.

Retrieve the Configuration

For example:

curl -u admin:admin \
http://localhost:8161/api/management/configuration/

If authentication is successful, the API should return the ActiveMQ configuration.

PUT and POST requests validate the XML before updating the configuration. A timestamped backup of the original activemq.xml is created before the file is replaced. The broker is not automatically restarted. The changes take effect after the next broker restart.