SnmpConfig

Manage Horizon's SNMP configuration (snmp-config.xml: defaults + profiles + definitions) declaratively, and read it back with snmp export / snmp lookup. Targets /api/v2/snmp-config.

YAML

SnmpConfig is a singleton: metadata.name is fixed to default.

Secrets are write-only. Communities and v3 passphrases are rejected inline; reference an external secret (the same shape as IAM's passwordRef). They're excluded from the idempotency comparison, so a secret-only rotation isn't auto-detected; re-apply deliberately. snmp export emits placeholders, never cleartext.

Trap daemon requires a Horizon build with the Trapd REST API

The trap daemon is configured via optional spec.trapd, reconciled against /api/v2/trapd/config in the same apply. It is additive: omit it and the trap daemon is untouched. This requires a Horizon build with the Trapd REST API (NMS-19128, the 37.x/develop line); against older servers the trapd half fails with a clear version message while the snmp-config half still applies.

Apply

Apply reconciles by whole-config replace: pull the deployed config, compare ignoring secret values, and re-upload only when it differs.

onmsctl apply -f examples/snmp-config.yaml --dry-run --diff
onmsctl apply -f examples/snmp-config.yaml

Order: SnmpConfig applies before Requisition, so a co-located directory configures SNMP before importing nodes. An SNMP change does not auto-rescan already-imported nodes; follow with requisition import <fs> --rescan-existing.

Inspect and delete

onmsctl snmp export -O snmp-config.yaml          # deployed config → YAML (secrets as refs)
onmsctl snmp lookup 192.168.8.8
onmsctl snmp lookup 192.168.8.8 --location labmonkeys-hq --show-secrets

Community strings and v3 passphrases are write-only: masked on lookup, placeholders on export.

Example

examples/snmp-config.yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/no42-org/onmsctl/main/schemas/snmp-config.schema.json
#
# kind: SnmpConfig — the whole-server SNMP configuration as one declarative
# document (OpenSpec add-snmp-config-capability). It is a SINGLETON: there is
# one snmp-config per Horizon, so metadata.name is always `default`.
# `onmsctl apply -f` reconciles it by whole-config replace against
# /api/v2/snmp-config:
#
#   onmsctl apply -f examples/snmp-config.yaml --dry-run --diff
#
apiVersion: snmp.opennms.org/v1
kind: SnmpConfig
metadata:
  name: default
spec:
  # Fallback parameters applied to any agent no definition matches.
  defaults:
    version: v2c
    port: 161
    timeout: 1800
    retries: 1
    # Secrets are NEVER inline — a literal string is rejected at parse time.
    # Reference exactly one source: fromEnv / fromFile / fromKeyring. They are
    # write-only: resolved at apply, never read back, and `snmp export` emits
    # them as reference placeholders, never cleartext.
    readCommunity: { fromEnv: ONMS_SNMP_READ_COMMUNITY }

  # Named, reusable parameter templates. A definition adopts one by label.
  profiles:
    - label: core-v3
      version: v3
      securityName: monitor
      securityLevel: authPriv          # noAuthNoPriv | authNoPriv | authPriv
      authProtocol: SHA
      authPassphrase: { fromKeyring: { service: onmsctl, account: snmp-auth } }
      privacyProtocol: AES
      privacyPassphrase: { fromFile: /run/secrets/snmp-priv }
      # Optional OpenNMS filter expression (evaluated server-side).
      filterExpression: "categoryName == 'Routers'"

  # Per-target overrides. Each definition needs at least one selector:
  # `specifics` (exact IPs), `ranges` (begin/end), or `ipMatches` (IPLIKE) —
  # and `ipMatches` cannot be combined with `specifics`/`ranges` in the same
  # definition.
  definitions:
    - location: labmonkeys-hq
      specifics: [192.168.8.8]
      ranges:
        - { begin: 10.0.0.1, end: 10.0.0.254 }
      # Adopt a profile by its label (must name a declared spec.profiles[].label).
      profileLabel: core-v3
    - location: nyc-dc
      ipMatches: ["10.12.*.*"]
      version: v2c
      readCommunity: { fromEnv: ONMS_SNMP_NYC_COMMUNITY }

  # OPTIONAL: the SNMP trap daemon (Trapd) configuration, reconciled against
  # /api/v2/trapd/config in the SAME apply. It is additive — omit this block and
  # apply/export never touch the Trapd endpoint (so older Horizon is unaffected).
  #
  # REQUIRES a Horizon build with the Trapd REST API (NMS-19128; the 37.x /
  # develop line). Against an older server a present `trapd` block fails the
  # trap-daemon half with a clear version message while the snmp-config half
  # still applies. `snmpTrapPort` and `newSuspectOnTrap` are required.
  trapd:
    snmpTrapAddress: "*"          # listen address; * = all interfaces
    snmpTrapPort: 162
    newSuspectOnTrap: false
    includeRawMessage: false
    useAddressFromVarbind: false
    # Optional tuning — omit to keep the server defaults.
    # threads: 0
    # queueSize: 10000
    # batchSize: 1000
    # batchInterval: 500
    # SNMPv3 trap users (full-replace list: omitting a user removes it).
    snmpv3Users:
      - securityName: trap-monitor
        securityLevel: authPriv     # noAuthNoPriv | authNoPriv | authPriv
        authProtocol: SHA
        authPassphrase: { fromEnv: ONMS_TRAPD_AUTH_PASSPHRASE }
        privacyProtocol: AES
        privacyPassphrase: { fromKeyring: { service: onmsctl, account: trapd-priv } }