Overview

A

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

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

Admin Channels

The table below lists the bus channels used for administration over SMA: 

By default, all admin channels start with 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. Note that each channel is configured with a topic level of either xvmName or adminClientId ... The xvmName topic level allows clients to listen in to a particular xvm, and the adminClientId, allows an XVM to send responses targeted to a particular adminClient. 

Request and Response Channels

When command and control is enabled, these channels allow admin clients to issue commands to an XVM. Such commands include XVM control commands such as triggering thread dumps or reloading applications and also include invocation of application-defined commands.

Requests and Response messages for command and control can be found in the com.neeve.server.mon.cnc package. At present, support for usage of command and control is reserved for the platform's admin APIs (Robin and Lumino). 

Heartbeats

XVM heartbeats are periodically emitted over the heartbeats channel when they are enabled for the XVM. 

Heartbeats are emitted using the SrvMonHeartbeatMessage type defined in the com.neeve.server.mon package. While this package contains additional lifecycle related messages types used by direct monitoring clients, only SrvMonHeartbeatMessage are emitted over the heartbeats channel. 

Trace

When enabled, SrvMonTraceRecords are emitted over the trace channel allowing admin clients to view trace output as it happens.

Tracer records are emitted using SrvMonTraceRecord message type that can be found in the com.neeve.server.mon.cnc package.

Events 

The events channel is used to emit events such as lifecycle or alert events which are defined in the com.neeve.server.mon.lifecycle and lifecycle and com.neeve.server.mon.alert.

Configuration

...

Admin Bus Configuration

To use Admin over SMA for an XVM, a bus named xvm-admin must be configured to specify the bus connection details:

...

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

XVM Messaging Configuration

...

Discovery

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

Configuring Admin Client Connectivity

Tools such as Robin, Lumino or the AdminTool must be configured to enable SMA as a transport along with the admin bus connection information. As admin clients won't always be configured via DDL, configuration is done via system/environment properties to configure connectivity to the XVMs monitoring server. 

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

Alternatively, it is possible to configure the bus descriptor in decomposed form, which can be useful in cases where configuration properties are more 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
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</bus>
          </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 Robin or Lumino during deployment, 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:

...

Configuring Admin Client Connectivity

...

...

nv.admin.transports=sma
nv.admin.sma.bus.name=xvm-admin
nv.admin.sma.bus.provider=solace
nv.admin.sma.bus.address=solhost
nv.admin.sma.bus.port=55555
nv.admin.sma.bus.properties.topic_starts_with_channel=false

It is also possible to configure the admin client's bus more compactly using a bus descriptor instead of specifying provider, address, port and properties:

nv.admin.passiveMonitoringOnly=true
nv.admin.transports=sma
nv.admin.sma.bus.name=xvm-admin
nv.admin.sma.bus.descriptor=solace://solhost:55555&topic_starts_with_channel=false

Discovery

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

Passive vs. Active Monitoring

Passive Monitoring

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.