Management Swiftlet

Overview

The Management Swiftlet provides the core management and administration infrastructure for a SwiftMQ router. It enables both CLI-based and JMX-based configuration and monitoring, as well as message-based administration via a dedicated queue. The Swiftlet supports authentication, role-based access control, and tracks connected administration tools.

Features

CLI-Based Management

The Management Swiftlet implements a hierarchical command-line interface (CLI) for managing the router configuration and runtime state. The CLI supports context navigation, command execution, and context-sensitive access control. Contexts correspond to entities in the router configuration tree, allowing fine-grained management of all aspects of the router. Commands are parsed and executed within the current context, and errors are reported back to the client. The CLI can be accessed by administration tools (such as SwiftMQ Explorer or Flow Director) and supports authentication and role-based command filtering.

Authentication

If authentication-enabled is set to true, CLI clients must authenticate using a password before executing management commands. The password is configured via the password property, and the authentication mechanism can be customized via the crfactory-class property, which specifies the Challenge/Response factory class.

Administration Roles

When admin-roles-enabled is true, CLI access is controlled by roles defined under the roles entity list. Each role specifies context filters using SQL-LIKE predicates (with % as wildcard) and can grant or restrict access to specific contexts and commands. Context filters can be marked as read-only, and a list of granted commands can be specified for each context. This allows for fine-grained, role-based access control over the router's management interface.

Connect/Disconnect Logging

When admintool-connect-logging-enabled is true, the Swiftlet logs connect and disconnect events for administration tools, including the tool name and host name.

Configuration Example:

<swiftlet name="sys$mgmt" authentication-enabled="true" admin-roles-enabled="true" admintool-connect-logging-enabled="true" password="adminsecret">
  <roles>
    <role name="readonly">
      <context-filters>
        <context-filter cli-context-predicate="/sys$queuemanager/%" type="include" read-only="true" granted-commands="view"/>
      </context-filters>
    </role>
  </roles>
</swiftlet>

JMX Management Interface

The Management Swiftlet exposes the entire router configuration and runtime state as a JMX MBean tree. Each configuration entity and property is mapped to a JMX MBean, allowing remote management and monitoring using standard JMX tools. The JMX interface supports both attribute access and invocation of management commands. The JMX subsystem can be enabled or disabled via the jmx/enabled property. Object names can be grouped or flat, controlled by jmx/groupable-objectnames. The underlying MBean server can be selected or created using the jmx/mbean-server/usage-option and server-name properties.

Dynamic MBean Registration

Entities are dynamically registered and unregistered as MBeans as the configuration tree changes. Each MBean exposes properties as attributes and management commands as operations.

Configuration Example:

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

Message-Based Management Interface

The Management Swiftlet provides a message-based management interface that allows administration via JMS messages sent to a configurable request queue (default: swiftmqmgmt-message-interface). When enabled (message-interface/enabled), the Swiftlet listens on the request queue for TextMessages containing CLI commands. The first command must be authenticate <password> if authentication is enabled. The result of the commands is sent as a TextMessage reply to the JMSReplyTo queue or to the queue specified by the JMS_SWIFTMQ_MGMT_REPLY_QUEUE property. The property JMS_SWIFTMQ_MGMT_SHOW_COMMANDS_IN_RESULT can be set to control whether the executed commands are included in the result.

Custom Request Queue

The name of the request queue is configurable via the message-interface/request-queue-name property. If the queue does not exist, it is created automatically when the interface is enabled.

Configuration Example:

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

Connected Administration Tools Tracking

The Management Swiftlet maintains a dynamic list of connected administration tools under the usage entity list. Each entry records the host name, tool name, connection time, and lease timeout. This list is updated as tools connect and disconnect, and is visible in the configuration tree for monitoring purposes.

Event Propagation and Lease Management

The Swiftlet propagates configuration and property change events to connected administration tools (such as Flow Director) using a lease-based mechanism. Each tool connection is associated with a lease, and periodic lease renewal is required to maintain the connection. The flush interval for event propagation is configurable via the flush-interval property. If a lease expires, the tool is disconnected and removed from the usage list.

Flush Interval

The flush-interval property specifies how frequently the event queue is flushed and updates are sent to connected tools. The default is 500 ms.

Configuration Example:

<swiftlet name="sys$mgmt" flush-interval="2000"/>

Internal Queue Naming

swiftmqmgmt — Internal queue for CLI and management protocol requests from administration tools.
swiftmqmgmt-message-interface — Default queue for message-based management interface requests (can be customized).

Configuration Guide

Enable Role-Based CLI Access with Read-Only Role

Use this scenario to restrict CLI access to specific parts of the configuration tree and allow only certain commands (e.g., view) for a given role. This is useful for delegating limited administrative rights to certain users.

Set admin-roles-enabled to true.
Define a role under roles with a context filter matching the desired configuration subtree (using SQL-LIKE predicates, % as wildcard).
Set the context filter's type to include, read-only to true, and specify allowed commands in granted-commands.
Assign the role name to the user (the user's name must match the role entity name).

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

Enable JMX Management with Custom MBean Server

Use this scenario to expose the router configuration and management interface via JMX, using a named MBean server. This is useful for integration with enterprise monitoring tools.

Enable JMX by setting jmx/enabled to true.
Set jmx/mbean-server/usage-option to create-named-server.
Specify the desired MBean server name in jmx/mbean-server/server-name.

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

Enable Message-Based Management Interface on Custom Queue

Use this scenario to allow administration via JMS messages sent to a custom queue. This is useful for automated scripts or remote management tools that interact via JMS.

Enable the message interface by setting message-interface/enabled to true.
Set message-interface/request-queue-name to the desired queue name.

<swiftlet name="sys$mgmt">
  <message-interface enabled="true" request-queue-name="myadminqueue"/>
</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

Administration Roles

Connect/Disconnect Logging

JMX Management Interface

Dynamic MBean Registration

Message-Based Management Interface

Custom Request Queue

Connected Administration Tools Tracking

Event Propagation and Lease Management

Flush Interval

Internal Queue Naming

Configuration Guide

Enable Role-Based CLI Access with Read-Only Role

Enable JMX Management with Custom MBean Server

Enable Message-Based Management Interface on Custom Queue

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>`