Management Swiftlet

Overview

The Management Swiftlet provides centralized management and administration capabilities for the SwiftMQ router. It enables both interactive CLI-based management and remote administration via JMX and a message-based interface, supporting authentication, role-based access control, and event-driven updates for connected tools.

Features

CLI-Based Management

The Management Swiftlet exposes a hierarchical CLI (Command Line Interface) for interactive router management. The CLI supports context navigation, entity and property manipulation, and command execution. Contexts are navigated using commands such as cd, and commands are parsed and executed within the current context. Internal commands (such as listing entities or properties) and regular commands are supported. The CLI can be accessed by local tools or remotely via the message interface or JMX.

Authentication and Password Protection

CLI access can be protected by enabling authentication via the authentication-enabled property. When enabled, users must authenticate using a password before executing management commands. The password is configured via the password property. The authentication mechanism can be customized by specifying a different challenge/response factory class in the crfactory-class property.

Role-Based Access Control

When admin-roles-enabled is set to true, CLI access is governed by roles defined in the roles entity list. Each role specifies context filters using SQL-like predicates (with % as wildcard) to include or exclude access to specific parts of the management tree. Filters can also mark contexts as read-only and specify which commands are granted. This allows fine-grained control over which users can view or modify router configuration and execute management commands.

Configuration Example:

<swiftlet name="sys$mgmt" authentication-enabled="true" password="secret" admin-roles-enabled="true">
  <roles>
    <role name="admin">
      <context-filters>
        <context-filter name="all" cli-context-predicate="/%" type="include" read-only="false" granted-commands="*"/>
      </context-filters>
    </role>
  </roles>
</swiftlet>

JMX Management Interface

The Management Swiftlet can expose the entire router configuration and management tree as JMX MBeans, allowing remote management via standard JMX tools. Each entity and property in the configuration is mapped to MBean attributes and operations. JMX support can be enabled or disabled via the enabled property under the jmx entity. Object names can be grouped or flat, and the MBean server usage is configurable (platform server, named server, or creating a new named server).

Dynamic MBean Registration

Entities are dynamically registered and unregistered as MBeans as they are added or removed from the configuration. Property changes and entity events are reflected in real time in the JMX view.

Object Name Grouping

The groupable-objectnames property controls whether JMX object names are grouped by entity hierarchy or presented as flat names, aiding in large deployments.

MBean Server Selection

The usage-option and server-name properties under mbean-server allow selection of the JMX MBean server: using the platform server, connecting to a named server, or creating a new named server.

Configuration Example:

<swiftlet name="sys$mgmt">
  <jmx enabled="true" groupable-objectnames="true">
    <mbean-server usage-option="use-platform-server"/>
  </jmx>
</swiftlet>

Message-Based Management Interface

The Management Swiftlet provides a message-based interface for remote administration by listening on a configurable queue (default: swiftmqmgmt-message-interface). When enabled, management commands can be sent as text messages to this queue. The interface supports authentication (if enabled), command execution, and returns results as reply messages. The interface can be enabled or disabled via the enabled property under the message-interface entity, and the request queue name is configurable.

Command Execution via JMS

Clients send TextMessage requests containing CLI commands to the management queue. The Swiftlet processes each command, optionally authenticating the user, and sends the result as a reply to the specified JMSReplyTo queue or a queue named in the JMS_SWIFTMQ_MGMT_REPLY_QUEUE property.

Result Formatting and Options

The property JMS_SWIFTMQ_MGMT_SHOW_COMMANDS_IN_RESULT can be set on the request message to control whether the executed commands are included in the result output.

Configuration Example:

<swiftlet name="sys$mgmt">
  <message-interface enabled="true" request-queue-name="myadminqueue"/>
</swiftlet>

Event-Driven Updates and Usage Tracking

The Management Swiftlet maintains an event queue to track configuration changes, property updates, and router events. Connected administration tools (such as SwiftMQ Explorer or JMX clients) receive updates about changes in real time. The flush interval for the event queue is configurable via the flush-interval property. The Swiftlet also tracks connected administration tools in the usage entity list, recording details such as host name, tool name, connect time, and lease timeout.

Connect/Disconnect Logging

When admintool-connect-logging-enabled is true, the Swiftlet logs connect and disconnect events for administration tools, aiding in auditing and monitoring.

Lease Management

Each connected tool is assigned a lease, and if the lease expires (e.g., due to inactivity), the tool is automatically disconnected and removed from the usage list.

Configuration Example:

<swiftlet name="sys$mgmt" flush-interval="2000" admintool-connect-logging-enabled="true"/>

Internal Queue Naming

swiftmqmgmt — Default queue for CLI-based management requests and responses.

Configuration Guide

Enable Remote JMX Management

Enable JMX management to allow remote administration via JMX tools. This is useful for integrating SwiftMQ management into enterprise monitoring and automation platforms.

Set the enabled property under the jmx entity to true.
Optionally, configure groupable-objectnames and select the desired MBean server usage option.

<swiftlet name="sys$mgmt">
  <jmx enabled="true" groupable-objectnames="false">
    <mbean-server usage-option="create-named-server" server-name="MySwiftMQJMXServer"/>
  </jmx>
</swiftlet>

Restrict CLI Access Using Roles

Restrict access to sensitive parts of the management tree by defining roles with context filters and granted commands. Use this to enforce least-privilege access for different administrators.

Enable admin-roles-enabled and define one or more roles in the roles entity list.
For each role, add context-filters specifying which contexts and commands are allowed, using SQL-like predicates (with % as wildcard).

<swiftlet name="sys$mgmt" admin-roles-enabled="true">
  <roles>
    <role name="readonly">
      <context-filters>
        <context-filter name="queues" cli-context-predicate="/sys$queuemanager/queues/%" type="include" read-only="true" granted-commands="view list"/>
      </context-filters>
    </role>
  </roles>
</swiftlet>

Enable Message-Based Management Interface

Allow remote administration via JMS by enabling the message interface. This is useful for integrating management automation scripts or custom admin tools that communicate over JMS.

Set the enabled property under the message-interface entity to true.
Optionally, change the request-queue-name to a custom queue.

<swiftlet name="sys$mgmt">
  <message-interface enabled="true" request-queue-name="adminrequests"/>
</swiftlet>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$mgmt">.

`<swiftlet name="sys$mgmt">` Properties

These properties are attributes of the <swiftlet name="sys$mgmt"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`authentication-enabled`	Boolean	`false`	No	No	Enables/Disables Authentication
`admin-roles-enabled`	Boolean	`false`	No	No	Enables/Disables Administration Roles
`admintool-connect-logging-enabled`	Boolean	`true`	No	No	Enables/Disables Connect/Disconnect Logging of Admin Tools
`crfactory-class`	String	`com.swiftmq.auth.ChallengeResponseFactoryImpl`	No	No	Challenge/Response Factory Class
`password`	String	—	No	No	Authentication Password
`flush-interval`	Long	`500`	No	No	Interval in which the Event queue is flushed to the SwiftMQ Explorers (min: 500)

<swiftlet name="sys$mgmt" authentication-enabled="false" admin-roles-enabled="false" admintool-connect-logging-enabled="true" crfactory-class="com.swiftmq.auth.ChallengeResponseFactoryImpl" flush-interval="500"/>

`<jmx>` Entity

JMX Settings

This is a fixed child entity of <swiftlet name="sys$mgmt">.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`enabled`	Boolean	`false`	No	No	Enables/Disabled JMX Administration
`groupable-objectnames`	Boolean	`true`	No	No	Creates groupable Objectnames instead of flat Names

<swiftlet name="sys$mgmt">
  <jmx enabled="..." groupable-objectnames="..."/>
</swiftlet>

`<message-interface>` Entity

Message Interface Settings

This is a fixed child entity of <swiftlet name="sys$mgmt">.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`enabled`	Boolean	`false`	No	No	Enables/Disabled Administration via Message Interface
`request-queue-name`	String	`swiftmqmgmt-message-interface`	No	No	Input Queue Name for Admin Requests

<swiftlet name="sys$mgmt">
  <message-interface enabled="..." request-queue-name="..."/>
</swiftlet>

`<roles>` in `<swiftlet name="sys$mgmt">`

Administration Roles

Each <role> entry is identified by its name attribute (the Role).

<swiftlet name="sys$mgmt">
  <roles>
    <role name="..."/>
  </roles>
</swiftlet>

`<context-filters>` in `<roles>`

CLI Context Filters

Each <context-filter> entry is identified by its name attribute (the Context Filter).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`type`	String	`include`	No	No	Filter Type (choices: `include`, `exclude`)
`cli-context-predicate`	String	—	Yes	No	CLI Context Predicate (SQL Predicate)
`read-only`	Boolean	`false`	No	No	Is Read Only
`granted-commands`	String	—	No	No	Granted Commands of this CLI Context (SQL Like Predicates)

<swiftlet name="sys$mgmt">
  <roles>
    <role name="...">
      <context-filters>
        <context-filter name="..." cli-context-predicate="..."/>
      </context-filters>
    </role>
  </roles>
</swiftlet>

Changelog

13.1.2 (2025-04-15)

JMXUtil: fixed boundary condition
JMXUtil: fixed boundary condition

Management Swiftlet

Overview

Features

CLI-Based Management

Authentication and Password Protection

Role-Based Access Control

JMX Management Interface

Dynamic MBean Registration

Object Name Grouping

MBean Server Selection

Message-Based Management Interface

Command Execution via JMS

Result Formatting and Options

Event-Driven Updates and Usage Tracking

Connect/Disconnect Logging

Lease Management

Internal Queue Naming

Configuration Guide

Enable Remote JMX Management

Restrict CLI Access Using Roles

Enable Message-Based Management Interface

Configuration Reference

<swiftlet name="sys$mgmt"> Properties

<jmx> Entity

<message-interface> Entity

<roles> in <swiftlet name="sys$mgmt">

<context-filters> in <roles>

Changelog

13.1.2 (2025-04-15)

`<swiftlet name="sys$mgmt">` Properties

`<jmx>` Entity

`<message-interface>` Entity

`<roles>` in `<swiftlet name="sys$mgmt">`

`<context-filters>` in `<roles>`