> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/guides/developing-applications/configuring-the-runtime/administration/admin-over-sma.md).

# Admin over SMA

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

## Admin Over SMA Configuration

{% hint style="info" %}
**Since 3.10**
{% endhint %}

Admin over SMA allows administrative applications to monitor and manage containers over messaging. When enabled, containers 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:

```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 container use the same discovery descriptor and message bus, they will be able to communicate with one another.

{% hint style="warning" %}
**Warning**: When enabling Admin over SMA it is important to note that by default admin clients using SMA will attempt to connect to discovered containers. If older version containers or containers not configured for Admin over SMA are advertising themselves over the admin client's discovery address, the container will never respond and the admin client will see connection timeouts. To avoid this you may:

* Use [passive monitoring](#passive-monitoring-configuration) on the client side to avoid attempts to ping the container
* Use separate container discovery for containers that support Admin over SMA vs. those that don't
  {% endhint %}

### Discovery Configuration

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

See [Discovery Configuration](/rumi-core/guides/developing-applications/configuring-the-runtime/discovery/discovery-configuration.md) for details on configuring discovery.

### Configuring Admin Clients

Administrative tools such as the [rumi admin](/rumi-cli/commands/tools/admin.md) 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:**

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

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

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

```xml
<env>
  <nv>
    <container>
      <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>
    </container>
  </nv>
</env>
```

### Advanced Container Bus Configuration

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

**Container Admin over SMA Configuration:**

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

```xml
<containers>
  <container name="order-processing-1" template="container-template">
    <admin>
      <transports>
        <sma enabled="true">
          <busName>container-admin</busName>
        </sma>
      </transports>
    </admin>
    <heartbeats enabled="true" interval="5s"/>
  </container>
</containers>
```

**Admin Bus Configuration:**

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

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

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

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

**Subscribe:**

* **container-request channel:** container-admin/order-processing-1/request

**Publish:**

* **container-response channel:** container-admin/${adminClientId}/response (where the adminClientId is substituted with that of the sending client when a response is sent)
* **container-heartbeats channel:** container-admin/order-processing-1/heartbeat (when heartbeats are enabled)
* **container-trace channel:** container-admin/order-processing-1/trace (when trace emission is enabled)
* **container-event channel:** container-admin/order-processing-1/event

{% hint style="info" %}
**Tip**: Enabling container heartbeats isn't strictly necessary, but in most monitoring scenarios it is desirable.
{% endhint %}

### Channel Prefix Configuration

By default, all admin channels start with the *container-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:

```properties
nv.server.admin.passivemonitoringonly=true
```

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

## Related Topics

* [Admin Over SMA](/rumi-core/guides/operating-applications/administration/admin-over-sma.md) - Using Admin over SMA at runtime
* [rumi admin](/rumi-cli/commands/tools/admin.md) - Command-line administrative interface
* [Configuring Monitoring](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring.md) - Configure heartbeat and statistics emission

## Next Steps

1. Configure discovery provider for container and admin clients
2. Set up message bus for admin channels
3. Enable Admin over SMA in container configuration
4. Configure admin tools to use SMA transport
5. Test admin operations via messaging