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

# Administration

## Overview

Administration configuration enables remote monitoring and management of your Rumi containers via messaging infrastructure. By configuring administrative capabilities during development, you enable operators to manage microservices at runtime without requiring direct access to the containers.

This section covers development-time configuration for administration features. For information about using admin tools at runtime, see [Administration](/rumi-core/guides/operating-applications/administration.md).

## What You Can Configure

Administrative configuration includes:

### Admin over SMA

Configure remote administration via the Simple Messaging API:

* Enable/disable admin message processing
* Configure admin message channels
* Set administrative command permissions
* Define admin message routing

See [Admin over SMA](/rumi-core/guides/developing-applications/configuring-the-runtime/administration/admin-over-sma.md) for complete configuration reference.

### Administrative Features (Future)

Additional administration topics will be added:

* Custom administrative commands
* Administrative event subscriptions
* Admin security and authentication

*Note: Additional administration topics will be added as the documentation expands.*

## Configuration Hierarchy

Administration settings are configured in your DDL:

```xml
<service name="my-service" mainClass="com.example.MyApp">
  <admin enabled="true">
    <adminOverSMA enabled="true">
      <adminChannelName>admin-commands</adminChannelName>
      <adminResponseChannelName>admin-responses</adminResponseChannelName>
    </adminOverSMA>
  </admin>
</service>
```

## How Administration Works

Rumi's administration framework allows remote management without SSH or direct container access:

### Admin Command Flow

1. **Operator sends command**: Admin tool sends command message to admin channel
2. **Container receives**: Container listening on admin channel receives command
3. **Command executes**: Container processes administrative command (stats, config, shutdown, etc.)
4. **Response returned**: Result sent back on admin response channel
5. **Operator sees result**: Admin tool displays command output

### Security Considerations

Admin channels should be secured:

* Use private messaging infrastructure
* Implement channel access controls
* Consider message encryption for sensitive commands
* Audit administrative actions via trace logging

## Common Configuration Patterns

### Development Environment

Enable full admin access for local development:

```xml
<service name="dev-service">
  <admin enabled="true">
    <adminOverSMA enabled="true">
      <adminChannelName>dev-admin</adminChannelName>
      <adminResponseChannelName>dev-admin-response</adminResponseChannelName>
    </adminOverSMA>
  </admin>
</service>
```

### Production Environment

Configure secure admin channels:

```xml
<service name="prod-service">
  <admin enabled="true">
    <adminOverSMA enabled="true">
      <adminChannelName>prod-admin-secure</adminChannelName>
      <adminResponseChannelName>prod-admin-response-secure</adminResponseChannelName>
    </adminOverSMA>
  </admin>
</service>
```

Use separate admin message bus with restricted access.

### Disabled Administration

For maximum security in locked-down environments:

```xml
<service name="locked-service">
  <admin enabled="false"/>
</service>
```

## Available Administrative Commands

Once configured, operators can use these administrative commands:

### Statistics Commands

* `stats` - Display current statistics
* `stats reset` - Reset statistics counters
* `stats dump` - Write statistics to file

### Configuration Commands

* `config show` - Display current configuration
* `config get <property>` - Get specific property value
* `config set <property> <value>` - Update runtime property

### Lifecycle Commands

* `status` - Show microservice status
* `shutdown` - Graceful shutdown
* `shutdown force` - Immediate shutdown

### Discovery Commands

* `discovery show` - Show discovered entities
* `discovery refresh` - Refresh discovery cache

See [rumi admin](/rumi-cli/commands/tools/admin.md) for complete command reference.

## Monitoring Administrative Activity

Track administrative operations via:

### Trace Logging

Enable admin trace to log all administrative commands:

```bash
-Dnv.admin.tracelevel=INFO
```

### Statistics

Monitor admin activity with statistics:

* `AdminCommandsReceived` - Number of admin commands processed
* `AdminCommandsRejected` - Number of rejected commands
* `AdminResponsesSent` - Number of responses sent

### Audit Logging

Implement custom audit logging for sensitive operations:

```java
@AdminCommandHandler("shutdown")
public void onShutdown(ShutdownCommand cmd) {
    auditLog.warn("Shutdown command received from: " + cmd.getSource());
    // ... perform shutdown
}
```

## Best Practices

1. **Enable admin for all environments**: Admin over SMA is essential for operational visibility
2. **Use separate admin channels per environment**: Don't mix dev/test/prod admin traffic
3. **Secure admin channels**: Implement access controls on admin message topics
4. **Monitor admin activity**: Log all administrative commands for audit trail
5. **Test admin commands**: Verify admin commands work before production deployment
6. **Document admin procedures**: Create runbooks for common administrative tasks

## Related Topics

### Administration Concepts

* [Operating Model](/rumi-core/concepts/operating-model.md) - Administration architecture and patterns

### Runtime Administration

* [Administration](/rumi-core/guides/operating-applications/administration.md) - Using admin tools at runtime
* [rumi admin](/rumi-cli/commands/tools/admin.md) - Command-line interface
* [Admin Over SMA](/rumi-core/guides/operating-applications/administration/admin-over-sma.md) - Remote administration concepts

### Developer Guidance

* [Implementing Command Handlers](/rumi-core/guides/developing-applications/authoring-user-code/command-and-control/implementing-command-handlers.md) - Custom admin commands

### Configuration Reference

* [Configuration](/rumi-core/reference/configuration.md) - Complete DDL reference for admin settings

## See Also

* [Monitoring](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring.md) - Configure statistics and heartbeats
* [Threading](/rumi-core/guides/developing-applications/configuring-the-runtime/threading.md) - Configure threads including admin thread
* [Discovery](/rumi-core/guides/developing-applications/configuring-the-runtime/discovery.md) - Configure discovery for admin channel resolution