Trapd REST API (v2)

You can view and update trapd configuration over REST. These endpoints are useful for automation and external configuration tooling.

The Trapd REST API base path is /api/v2/trapd.

Endpoint overview

Method Path Content type Description

GET

/api/v2/trapd/config

application/json

Get the current trapd configuration.

PUT

/api/v2/trapd/config

application/json

Replace trapd configuration using JSON payload.

POST

/api/v2/trapd/upload

multipart/form-data

Upload trapd configuration as a JSON file.

POST

/api/v2/trapd/upload/xml

multipart/form-data

Upload trapd-configuration.xml content as XML.

GET

/api/v2/trapd/download

application/json or application/xml

Download the current trapd configuration as a file.

Get configuration

curl -u admin:admin "http://localhost:8980/opennms/api/v2/trapd/config"
Example response
{
  "snmpTrapAddress": "*",
  "snmpTrapPort": 1162,
  "newSuspectOnTrap": false,
  "includeRawMessage": false,
  "threads": 0,
  "queueSize": 10000,
  "batchSize": 1000,
  "batchInterval": 500,
  "useAddressFromVarbind": true,
  "snmpv3User": [
    {
      "engineId": "0x8000000001020304",
      "securityName": "opennms",
      "securityLevel": 3,
      "authProtocol": "SHA",
      "authPassphrase": "******",
      "privacyProtocol": "AES",
      "privacyPassphrase": "******"
    }
  ]
}

SNMPv3 passphrases are masked as ****** in GET /api/v2/trapd/config responses. SCV metadata expressions (${scv:<alias>:<attribute>}) are returned as written.

Update configuration with JSON

curl -u admin:admin \
  -H "Content-Type: application/json" \
  -X PUT "http://localhost:8980/opennms/api/v2/trapd/config" \
  -d '{
    "snmpTrapAddress": "*",
    "snmpTrapPort": 1162,
    "newSuspectOnTrap": false,
    "includeRawMessage": true,
    "threads": 4,
    "queueSize": 10000,
    "batchSize": 1000,
    "batchInterval": 500,
    "useAddressFromVarbind": true,
    "snmpv3User": [
      {
        "securityName": "opennms",
        "securityLevel": 3,
        "authProtocol": "SHA",
        "authPassphrase": "my-auth-secret",
        "privacyProtocol": "AES",
        "privacyPassphrase": "my-privacy-secret"
      }
    ]
  }'

Upload trapd configuration as a file

The upload endpoints accept a multipart/form-data request. The form field name must be upload. The endpoint path selects the parser, not the file’s content type: /upload expects JSON, /upload/xml expects XML.

JSON upload

The file uses the same JSON structure as PUT /api/v2/trapd/config.

curl -u admin:admin \
  -X POST "http://localhost:8980/opennms/api/v2/trapd/upload" \
  -F "upload=@/tmp/trapd-config.json;type=application/json"

XML upload

Sample trapd-configuration.xml for upload
<trapd-configuration xmlns="http://xmlns.opennms.org/xsd/config/trapd"
    snmp-trap-address="*"
    snmp-trap-port="1162"
    new-suspect-on-trap="false"
    include-raw-message="true"
    queue-size="10000"
    batch-size="1000"
    batch-interval="500"
    use-address-from-varbind="true">
  <snmpv3-user security-name="opennms"
      security-level="3"
      auth-protocol="SHA"
      auth-passphrase="${scv:trapd-v3-user:authPassphrase}"
      privacy-protocol="AES"
      privacy-passphrase="${scv:trapd-v3-user:privacyPassphrase}"/>
</trapd-configuration>

You can use SCV metadata expressions for passphrases in uploaded XML (${scv:<alias>:<attribute>}).

curl -u admin:admin \
  -X POST "http://localhost:8980/opennms/api/v2/trapd/upload/xml" \
  -F "upload=@/opt/opennms/etc/trapd-configuration.xml;type=application/xml"

Download configuration

The format query parameter selects json (default) or xml. The response is served as an attachment named trapd-config.json or trapd-config.xml, which the matching upload endpoint accepts back.

curl -u admin:admin -O -J \
  "http://localhost:8980/opennms/api/v2/trapd/download?format=xml"
Downloaded files contain SNMPv3 passphrases in cleartext.

Validation rules

The API validates both top-level trapd fields and SNMPv3 user definitions.

PUT pre-validation (service layer)

  • snmpTrapAddress is required for PUT /api/v2/trapd/config.

  • snmpTrapPort is required and must be between 1 and 65535.

  • newSuspectOnTrap is required.

  • threads, queueSize, batchSize, and batchInterval must be >= 0 when provided.

Additional schema validation (DAO layer, applies on persist)

  • queueSize must be >= 1.

  • batchSize must be >= 1.

  • In XML uploads, snmp-trap-address is optional and defaults to * when omitted.

SNMPv3 user fields

  • securityName is required.

  • securityLevel is required and must be 1, 2, or 3.

  • Supported authProtocol: MD5, SHA, SHA-224, SHA-256, SHA-512.

  • Supported privacyProtocol: DES, AES, AES192, AES256.

  • authProtocol and authPassphrase must be provided together.

  • privacyProtocol and privacyPassphrase must be provided together.

  • securityLevel=1: no auth or privacy credentials allowed.

  • securityLevel=2: auth credentials required, privacy credentials not allowed.

  • securityLevel=3: both auth and privacy credentials are required.

Response codes

Endpoint Success Error responses

GET /api/v2/trapd/config

200 OK

404 Not Found (Trapd configuration not found.), 500 Internal Server Error (Failed to retrieve trapd configuration.)

PUT /api/v2/trapd/config

200 OK

400 Bad Request (validation errors), 500 Internal Server Error (Failed to persist trapd configuration.)

POST /api/v2/trapd/upload

200 OK

400 Bad Request (missing upload, invalid JSON, validation errors), 403 Forbidden, 500 Internal Server Error (Failed to persist Trapd configuration.)

POST /api/v2/trapd/upload/xml

200 OK

400 Bad Request (missing upload, invalid XML, validation errors), 403 Forbidden, 500 Internal Server Error (Failed to persist Trapd configuration.)

GET /api/v2/trapd/download

200 OK

400 Bad Request (format is neither json nor xml), 403 Forbidden, 404 Not Found (Trapd configuration not found.), 500 Internal Server Error (Error retrieving Trapd config.)

Validation errors are returned as the response body text.