Admin over SMA

This page covers configuration for Admin over SMA (Simple Messaging API), which allows monitoring and management of XVMs over messaging.

Admin Over SMA Configuration

Since 3.10

Admin over SMA allows administrative applications to monitor and manage XVMs over messaging. When enabled, XVMs emit heartbeat, trace, and lifecycle events over defined messaging channels for consumption by listening clients.

Basic Configuration

At a high level, enabling Admin over SMA requires setting the following properties:

nv.discovery.descriptor=<discovery-provider>
nv.server.admin.transports=sma
nv.server.admin.bus.descriptor=<bus-connection-descriptor>

As long as both the admin client and the XVM use the same discovery descriptor and message bus, they will be able to communicate with one another.

Warning: When enabling Admin over SMA it is important to note that by default admin clients using SMA will attempt to connect to discovered XVMs. If older version XVMs or XVMs not configured for Admin over SMA are advertising themselves over the admin client's discovery address, the XVM will never respond and the admin client will see connection timeouts. To avoid this you may:

• Use passive monitoring on the client side to avoid attempts to ping the XVM

• Use separate XVM discovery for XVMs that support Admin over SMA vs. those that don't

Discovery Configuration

Admin clients should not attempt to issue commands until an XVM has been discovered via the discovery provider. When an admin client detects that an XVM is no longer discoverable, it should stop issuing commands over SMA.

See Discovery Configuration for details on configuring discovery.

Configuring Admin Clients

Administrative tools such as the Admin Tool must be configured to enable SMA as a transport along with the admin bus connection information. Since admin clients won't always be configured via DDL, configuration is done via system/environment properties.

Properties-Based Configuration with Bus Descriptor:

nv.server.admin.transports=sma
nv.server.admin.sma.bus.descriptor=solace://solhost:55555&topic_starts_with_channel=false&SESSION_VPN_NAME=default&use_default_queue_name=false&use_default_queue_name_as_default_client_id=true&topic_starts_with_channel=false&usejni=true&single_session=true

Properties-Based Configuration with Decomposed Properties:

Alternatively, it is possible to configure the bus descriptor in decomposed form, which can be useful when configuration properties are overridden across environments:

nv.server.admin.transports=sma
nv.server.admin.sma.bus.provider=solace
nv.server.admin.sma.bus.address=solhost
nv.server.admin.sma.bus.port=55555
nv.server.admin.sma.bus.properties.SESSION_VPN_NAME=default
nv.server.admin.sma.bus.properties.use_default_queue_name=false
nv.server.admin.sma.bus.properties.use_default_queue_name_as_default_client_id=true
nv.server.admin.sma.bus.properties.topic_starts_with_channel=false
nv.server.admin.sma.bus.properties.usejni=true
nv.server.admin.sma.bus.properties.single_session=true

Configuring XVMs

XVMs can be configured using the same environment properties as clients by setting the properties in the DDL environment section:

<env>
  <nv>
    <server>
      <admin>
        <transports>sma</transports>
        <sma>
          <bus>
            <descriptor>solace://solhost:55555&topic_starts_with_channel=false&SESSION_VPN_NAME=default&use_default_queue_name=false&use_default_queue_name_as_default_client_id=true&topic_starts_with_channel=false&usejni=true&single_session=true</descriptor>
          </bus>
        </sma>
      </admin>
    </server>
  </nv>
</env>

Advanced XVM Bus Configuration

Using environment-based configuration is the simplest way of configuring Admin over SMA for an XVM. In cases where bus configuration is not being injected by deployment tools, it is possible to use the <xvm> <admin> element in DDL to enable admin over SMA and reference a DDL-defined bus definition.

XVM Admin over SMA Configuration:

To configure an XVM to use a bus named 'xvm-admin', the XVM's <admin> <sma> element can be used:

<xvms>
  <xvm name="order-processing-1" template="xvm-template">
    <admin>
      <transports>
        <sma enabled="true">
          <busName>xvm-admin</busName>
        </sma>
      </transports>
    </admin>
    <heartbeats enabled="true" interval="5s"/>
  </xvm>
</xvms>

Admin Bus Configuration:

The following bus definition can then be configured for use by the XVM:

<buses>
  <bus name="xvm-admin">
    <provider>solace</provider>
    <address>solhost</address>
    <port>55555</port>
  </bus>
</buses>

Admin channels (xvm-request, xvm-response, xvm-heartbeat, xvm-event, and xvm-trace) should not be configured for the bus; they are automatically created by the XVM when it is started.

With the above configuration, the order-processing-1 XVM will create a connection to solace://solhost:55555 with a username of order-processing-1. It will use the following topics:

Subscribe:

• xvm-request channel: xvm-admin/order-processing-1/request

Publish:

• xvm-response channel: xvm-admin/${adminClientId}/response (where the adminClientId is substituted with that of the sending client when a response is sent)

• xvm-heartbeats channel: xvm-admin/order-processing-1/heartbeat (when heartbeats are enabled)

• xvm-trace channel: xvm-admin/order-processing-1/trace (when trace emission is enabled)

• xvm-event channel: xvm-admin/order-processing-1/event

Tip: Enabling XVM heartbeats isn't strictly necessary, but in most monitoring scenarios it is desirable.

Channel Prefix Configuration

By default, all admin channels start with the xvm-admin channel prefix. This prefix can be changed by setting the environment property nv.admin.sma.channelKeyPrefix, which can be useful for cases where it is desirable to more granularly partition admin traffic.

Passive Monitoring Configuration

It is possible to use Admin over SMA in a purely passive monitoring capacity by setting the property:

nv.server.admin.passivemonitoringonly=true

With the above configuration setting, clients will throw an exception if an attempt is made to send commands to an XVM, and XVMs will not issue subscriptions on the xvm-request channel.

Related Topics

• Admin Over SMA - Using Admin over SMA at runtime

• Admin Tool - Command-line administrative interface

• Configuring Monitoring - Configure heartbeat and statistics emission

Next Steps

1. Configure discovery provider for XVM and admin clients

2. Set up message bus for admin channels

3. Enable Admin over SMA in XVM configuration

4. Configure admin tools to use SMA transport

5. Test admin operations via messaging