System Settings

Overview

System Settings in NetStacks Controller provide centralized configuration for platform-wide behavior. Settings are organized by category and control everything from email delivery to feature availability and license management.

Key configuration areas include:

• Email (SMTP) — Configure outbound email for notifications, password reset links, and alert delivery from NOC agents.
• License Management — View current license tier, device count limits, seat allocation, and expiration. Apply new license keys to upgrade.
• Feature Toggles — Enable or disable platform modules such as AI Chat, NOC Agents, MCP Servers, and the Plugin System.
• Plugin Management — View installed plugins, enable or disable them, and configure plugin-specific settings.
• Authentication — Configure LDAP, OIDC, and other auth provider settings (detailed in Authentication).
• HA Settings — Configure Valkey connection, Sentinel URL, heartbeat intervals, and session sharing settings for high-availability deployments.
• Dashboard — Customize the Admin UI dashboard layout with drag-to-reorder and resizable widgets for at-a-glance monitoring of system health, active sessions, alerts, and device status.
• General — Organization name, timezone, date format, session timeout, and other platform defaults.

How It Works

Settings Storage

Settings are stored in PostgreSQL as key-value pairs with JSON values. Each setting has a key (dot-separated namespace, e.g., auth.ldap.enabled), a value (JSON), a category (derived from the key prefix), and an optional description. Settings flagged as is_secretare masked in API responses.

The settings system supports two interfaces:

• Admin API (/api/admin/settings) — Full CRUD with category grouping, used by the admin web interface.
• Terminal API (/api/settings) — Simplified GET/PUT interface that returns raw JSON values, used by the Terminal application for user preferences.

Setting Categories

Settings are automatically grouped by the first segment of their key. Common categories include:

Feature Toggles

Feature toggles allow administrators to enable or disable entire platform modules without redeploying the application. When a feature is disabled, its UI sections are hidden and its API endpoints return 403 Forbidden. Some features may require a Controller restart to fully take effect (noted in the settings interface).

License Management

NetStacks uses license keys to control feature tiers and device limits. The license key is validated against the Controller's license server and determines:

• Feature tier — Which modules are available (e.g., AI features, SSH CA, NOC agents).
• Device limit — Maximum number of managed devices.
• Seat count — Maximum number of concurrent active sessions.
• Expiration — When the license expires and requires renewal.

Step-by-Step Guide

Configuring SMTP Email

1. Navigate to Admin → Settings → Email.
2. Enter the SMTP server hostname (e.g., smtp.dc1.example.net).
3. Set the port (587 for STARTTLS, 465 for implicit TLS, 25 for unencrypted).
4. Select the TLS mode (STARTTLS recommended for port 587).
5. Enter the sender address (e.g., netstacks@dc1.example.net).
6. Enter SMTP credentials (username and password) if your mail server requires authentication.
7. Click Send Test Email to verify delivery to an admin email address.
8. Click Save to apply the configuration.

Managing Your License

1. Navigate to Admin → Settings → License.
2. View your current license details: tier (e.g., Enterprise), device limit, seat count, and expiration date.
3. To upgrade or renew, enter a new license key in the input field.
4. Click Validate to verify the key is valid and check the new entitlements.
5. Click Apply to activate the new license. Changes take effect immediately.

Use the Refresh button to re-validate your current license against the license server without entering a new key. This is useful after a license renewal to pull updated entitlements. If the refresh fails, an error message describes the issue (expired key, server unreachable, or invalid signature).

Toggling Features

1. Navigate to Admin → Settings → Features.
2. Toggle individual features on or off:
   • AI Chat — Enable the AI assistant in the terminal and web interface.
   • NOC Agents — Enable autonomous AI agents for incident triage and response.
   • MCP Servers — Enable Model Context Protocol servers for tool-use AI workflows.
   • Plugin System — Enable third-party plugin loading and execution.
3. Click Save. Some toggles take effect immediately; others display a Restart Required badge indicating the Controller service must be restarted.

Managing Plugins

1. Navigate to Admin → Settings → Plugins (requires the Plugin System feature toggle to be enabled).
2. View the list of installed plugins with their name, version, status, and description.
3. Click a plugin to view its configuration page and adjust plugin-specific settings.
4. Enable or Disable individual plugins without uninstalling them.

Code Examples

Settings endpoints are under /api/admin/settings. All operations require the admin.settings permission via a valid JWT bearer token.

Get All Settings (Grouped by Category)

curl https://netstacks.dc1.example.net/api/admin/settings \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "settings": {
    "auth": [
      {
        "key": "auth.ldap.enabled",
        "value": true,
        "category": "auth",
        "description": "Enable LDAP authentication",
        "is_secret": false
      },
      {
        "key": "auth.ldap.server_url",
        "value": "ldaps://ldap.dc1.example.net:636",
        "category": "auth",
        "description": "LDAP server URL",
        "is_secret": false
      }
    ],
    "smtp": [
      {
        "key": "smtp.host",
        "value": "smtp.dc1.example.net",
        "category": "smtp",
        "description": "SMTP server hostname",
        "is_secret": false
      },
      {
        "key": "smtp.port",
        "value": 587,
        "category": "smtp",
        "description": "SMTP server port",
        "is_secret": false
      }
    ]
  }
}

Get a Single Setting

curl https://netstacks.dc1.example.net/api/admin/settings/smtp.host \
  -H "Authorization: Bearer $TOKEN"

Update SMTP Settings

# Set SMTP host
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/smtp.host \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "smtp.dc1.example.net"}'

# Set SMTP port
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/smtp.port \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 587}'

# Set TLS mode
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/smtp.tls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

# Set sender address
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/smtp.from \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "netstacks@dc1.example.net"}'

Check License Status

curl https://netstacks.dc1.example.net/api/license \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "tier": "enterprise",
  "max_devices": 5000,
  "max_seats": 50,
  "expires_at": "2026-12-31T23:59:59Z",
  "features": {
    "ai_chat": true,
    "noc_agents": true,
    "mcp_servers": true,
    "ssh_ca": true,
    "plugins": true
  },
  "valid": true
}

Toggle a Feature

# Enable AI Chat
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/features.ai_chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

# Disable Plugin System
curl -X PUT https://netstacks.dc1.example.net/api/admin/settings/features.plugins \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": false}'

Questions & Answers

How do I configure email notifications?

Navigate to Admin → Settings → Email and configure the SMTP server hostname, port, TLS mode, sender address, and credentials. Use theSend Test Email button to verify delivery before saving. Once configured, NetStacks uses SMTP for password reset emails, alert notifications from NOC agents, and other system messages.

Where do I enter my license key?

Navigate to Admin → Settings → License. Enter the license key in the input field, click Validate to verify it, then clickApply. The new license takes effect immediately, updating your feature tier, device limit, and seat count. You can also check license status programmatically via GET /api/license.

Which settings require a restart?

Most settings take effect immediately, including SMTP configuration, feature toggles, and authentication provider settings. However, some infrastructure-level settings (such as certain plugin configurations or TLS certificate changes) may require a Controller service restart. These settings are marked with a Restart Required badge in the web interface.

How do I enable or disable AI features?

Navigate to Admin → Settings → Features and toggle theAI Chat and NOC Agents switches. Disabling AI Chat hides the AI assistant from the terminal and web interface. Disabling NOC Agents stops autonomous incident triage. These toggles take effect immediately for new sessions. Also ensure the LLM provider is configured if enabling AI features.

Can I manage plugins through the API?

Yes. Plugin settings follow the same key-value pattern as other settings. UseGET /api/admin/settings to list all settings (plugins appear in theplugins category) and PUT /api/admin/settings/{key}to update individual plugin settings. Plugin enable/disable is controlled through their respective settings keys.

What happens if my license expires?

The Controller enters read-only mode. Users can log in and view existing data, but write operations (creating devices, deploying stacks, managing users) are blocked. Apply a new license key in Admin → Settings → License to restore full functionality. Critical infrastructure monitoring continues during the grace period.

Troubleshooting

Test Email Fails to Send

• Verify the SMTP hostname resolves correctly: dig smtp.dc1.example.net
• Check port connectivity from the Controller host: nc -zv smtp.dc1.example.net 587
• Verify TLS mode matches the port (STARTTLS for 587, implicit TLS for 465).
• Check SMTP credentials are correct. Some mail servers require app-specific passwords.
• Review firewall rules — outbound SMTP (port 25, 465, or 587) may be blocked by default in cloud environments.
• Check Controller logs for specific SMTP error codes (e.g., 535 for authentication failure, 550 for rejected sender).

License Key Invalid

• Verify the license key is copy-pasted correctly without extra whitespace or line breaks.
• Check the key's expiration date — expired keys cannot be applied.
• Ensure the key matches the correct Controller instance — some licenses are bound to a specific deployment ID.
• Contact NetStacks support if the key was recently issued but fails validation.

Feature Toggle Not Taking Effect

• Check if the setting has a Restart Required badge. If so, restart the Controller service: systemctl restart netstacks-controller
• Clear browser cache and refresh — the web interface may have cached the old feature state.
• Verify the toggle was actually saved by re-reading the setting via the API: curl .../api/admin/settings/features.ai_chat
• Check that the feature is included in your license tier. Some features require a specific license level.

Plugin Will Not Start

• Verify the Plugin System feature toggle is enabled in Admin → Settings → Features.
• Check plugin logs for startup errors (available in the Controller's log output).
• Verify plugin dependencies are met — some plugins require specific versions of the Controller or other plugins.
• Try disabling and re-enabling the plugin to trigger a fresh initialization.

Setting Not Found (404)

• Settings are created on first use. If a setting has never been set, it may not exist in the database.
• The terminal API (/api/settings) uses upsert behavior — it creates the setting on first PUT, so the 404 error only occurs on GET for never-set keys.
• Check the setting key spelling and case — keys are case-sensitive.

Related Features

• User Management — Create users and manage accounts that are governed by system settings.
• Authentication (LDAP/OIDC) — Configure authentication providers through the settings system.
• LLM Configuration — Configure AI model providers when the AI Chat feature toggle is enabled.
• Audit Logs — Track all settings changes with user attribution and timestamps.
• HA Deployment — Configure multi-instance Controller deployments with Valkey and Sentinel.
• API Authentication — Understand how admin.settings permission controls access to the settings API.