System Settings (Admin)

Get System Settings

GET /api/v1/settings/system

Returns all system settings as a flat key/value map. Admin-only.

Response: 200 OK

{
  "topology.stale_retention_hours": "168",
  "retention.events_days": "90",
  "retention.snapshots_days": "90",
  "retention.ssh_sessions_days": "90",
  "snmp.default_community": "public",
  "snmp.default_timeout_seconds": "5",
  "snmp.default_retries": "2",
  "snmp.auto_disable_threshold": "10",
  "snmp.counters_enabled": "true",
  "snmp.discovery_enabled": "true",
  "snmp.fallback_credential_profile_id": "",
  "display.device_name_mode": "hostname",
  "display.area_format": "dotted_quad",
  "ssh.allow_telnet_fallback": "false"
}

Error responses:

Update System Settings

PUT /api/v1/settings/system

Updates one or more system settings. Only known keys are accepted. Values are validated per the rules below. Returns the full updated settings map. Admin-only.

Known keys:

Key Type Range Default Description
topology.stale_retention_hours integer 1--8760 168 Hours before unreachable devices are removed
retention.events_days integer 1--365 90 Days to retain topology event history
retention.snapshots_days integer 1--365 90 Days to retain time-travel snapshots
retention.ssh_sessions_days integer 1--365 90 Days to retain SSH/telnet session recordings
retention.bgp_history_days integer 1--365 90 Days to retain closed BGP best-path / peer-session history (open intervals are always kept)
snmp.default_community string non-empty public Legacy default SNMP community string (fallback for auto-discovery)
snmp.default_credential_profile_id string (UUID) valid UUID or empty (empty) Default credential profile for auto-discovery (overrides community)
snmp.default_timeout_seconds integer 1--30 5 SNMP poll timeout in seconds
snmp.default_retries integer 0--10 2 SNMP poll retry count
snmp.auto_disable_threshold integer 1--100 10 Consecutive failures before auto-disabling SNMP target
display.device_name_mode string hostname, dns, router_id, hostname_ip hostname How devices are labeled across the application (topology, events, incidents, diagnostics, reports)
display.area_format string dotted_quad, decimal dotted_quad OSPF area ID display format. Visual only — stored values always use dotted quad notation
snmp.poller_paused boolean true, false false Pause all SNMP polling (stealth mode). Boost-on-click still works.
snmp.counters_enabled boolean true, false true Enable traffic counter collection (bytes, packets, errors per interface every poll interval)
snmp.discovery_enabled boolean true, false true Enable interface discovery and enrichment (IF-MIB walks at the configured discovery interval: names, speeds, MTU, timers)
snmp.fallback_credential_profile_id string (UUID) valid UUID or empty (empty) Fallback credential profile for automatic retry when primary credentials fail. Single failure counted regardless of fallback attempt. Logs warning when fallback succeeds suggesting credential profile update
ssh.allow_telnet_fallback boolean true, false false Allow cleartext telnet fallback when SSH connection fails in the terminal proxy
ssh.session_recording boolean true, false false Record SSH/telnet terminal device output (banner, prompts, session) to the encrypted session log. Overrides the ssh_recording config flag. Typed input is never recorded
auth.external_url string absolute http(s) URL or empty (empty) Canonical base URL for SSO redirect-URI derivation — never taken from request headers. Required before SSO works
auth.local_login string enabled, admins_only, disabled enabled Password-login policy; the restricted values gate non-admins at the API, disabled also hides the form (break-glass /?local=1)
auth.link_by_email boolean true, false false Allow JIT linking of an SSO identity to an existing local account by email claim (account-takeover risk — leave off unless the IdP verifies email)
auth.mfa.required_roles string comma-separated roles or empty (empty) Roles for which TOTP MFA is mandatory (enforced from the MFA phase)

Request body:

{
  "settings": {
    "topology.stale_retention_hours": "24",
    "retention.events_days": "60",
    "snmp.default_timeout_seconds": "10"
  }
}

Response: 200 OK

{
  "topology.stale_retention_hours": "24",
  "retention.events_days": "60",
  "retention.snapshots_days": "90",
  "retention.ssh_sessions_days": "90",
  "snmp.default_community": "public",
  "snmp.default_timeout_seconds": "10",
  "snmp.default_retries": "2",
  "snmp.auto_disable_threshold": "10",
  "snmp.counters_enabled": "true",
  "snmp.discovery_enabled": "true",
  "snmp.fallback_credential_profile_id": "",
  "display.device_name_mode": "hostname",
  "ssh.allow_telnet_fallback": "false"
}

Error responses: