SNMP Configuration

Horizon has been updated to move SNMP Configuration into the database. Please see SNMP Configuration (Legacy) for the legacy REST API. Generally speaking you should avoid that legacy API and use the new API instead, but if you have a use case that requires the legacy API, that page describes how to use it.

This is the new REST API for SNMP configuration. It is used by the SNMP Configuration UI in the OpenNMS web interface, but it can also be used by external applications to manage SNMP configuration in OpenNMS directly.

You can use this API to manage SNMP configuration for individual IP addresses, for example to edit the community string, SNMP version, etc. for an IP address or range. If you make a change that would overlap with any existing configurations, the system will automatically create groups of definition entries as necessary. If a configuration matches the defaults, then no definition entry is created.

The following operations are supported.

The base URL for the API is http://localhost:8980/opennms/api/v2 (substitute your protocol, OpenNMS host and port as necessary).

GETs (reading data)

SNMP Configuration API GET functions
Parameter Description

/snmp-config

Get the entire SNMP configuration in JSON format.

/snmp-config/lookup?ipAddress={ipaddress}&location={location}

Get the SNMP configuration for a given IP address at a given monitoring location. If location is omitted, the system will use the Default location.

Example: http://localhost:8980/opennms/api/v2/snmp-config/lookup?ipAddress=10.0.0.1&location=datacenter1

/snmp-config/download?format={format}

Download the entire SNMP configuration in JSON or XML format as a file. format can be either json or xml, or omitted for json.

Example: http://localhost:8980/opennms/api/v2/snmp-config/download?format=xml

PUT (modifying data)

SNMP Configuration API PUT functions
Parameter Description

/snmp-config/definition

Add or update an SNMP configuration definition, in JSON format. See below for the SNMP Definition schema. This can be used to apply configurations to individual IP addresses or ranges, or use IPLIKE expressions. The system will automatically reconfigure SNMP configuration as necessary, and create groups of definition entries if there are overlapping configurations.

POST (modifying data)

SNMP Configuration API POST functions
Parameter Description

/snmp-config/defaults

Save SNMP default override configuration, in JSON format. See below for the SNMP Configuration schema. For each configuration item, the system has some default values. However, you can use this API to override those defaults with your own values. For example, if you want to change the default SNMP read community string from public to something else, you can use this API to do that.

/snmp-config/profile

Add or update an SNMP configuration profile, in JSON format. See below for the SNMP Profile schema.

/snmp-config/upload

Upload an entire SNMP configuration, in JSON format. See below for the schema.

/snmp-config/upload/xml

Upload an entire SNMP configuration, in XML format. See below for the schema.

DELETE (removing data)

SNMP Configuration API DELETE functions
Parameter Description

/snmp-config/definition?specifics={specifics}&ranges={ranges}&ipmatches={ipLike}&location={location}

Remove an SNMP configuration definition. This in effect resets the SNMP configuration for the specified IP address(es) and/or range(s) and/or IPLIKE expression(s) at the specified monitoring location back to the defaults.

You can supply any combination of the following parameters to specify which definition(s) to remove.

You can use commas to separate individual values for each parameter.

Example: http://localhost:8980/opennms/api/v2/snmp-config/definition?specifics=10.0.0.1&location=datacenter1

would remove the definition for IP address 10.0.0.1.

Example: http://localhost:8980/opennms/api/v2/snmp-config/definition?ranges=10.0.0.1-10.0.0.10,10.2.0.0-10.2.3.10&location=datacenter1

would remove both ranges.

The system will automatically reconfigure SNMP configuration as necessary.

/snmp-config/profile?label={label}

Remove an SNMP configuration profile with the given label.

API Schema

While the older XML configuration format is still supported, we recommend using the new JSON format for SNMP configuration, as it is more flexible and easier to work with.

The following table shows all supported attributes for SNMP Configuration. It also shows the version limitations, default values, and the restrictions, if any:

Attribute Default Value Restricted to SNMP Version Restrictions

version

v1

None

v1, v2c, or v3 are valid arguments. If an invalid or empty argument is provided, v1 is used.

port

161

None

Integer > 0

retries

1

None

Integer > 0

timeout

3000

None

Integer > 0

maxVarsPerPdu

10

None

Integer > 0

maxRepetitions

2

None

Integer > 0

maxRequestSize

65535

None

Integer > 0. Must be at least 484.

ttl

Blank

None

Integer > 0. Time to live in milliseconds.

proxyHost

Blank

None

None

readCommunity

public

v1, v2c

None

writeCommunity

private

v1, v2c

None

securityName

opennmsUser

v3

None

securityLevel

noAuthNoPriv

v3

Integer value, which can be null, 1, 2, or 3. See note below table for an explanation of these values.

authPassPhrase

0p3nNMSv3

v3

None

authProtocol

MD5

v3

Only MD5, SHA, SHA-224, SHA-256, SHA-512 are valid arguments.

privPassPhrase

0p3nNMSv3

v3

None

privProtocol

DES

v3

Only DES, AES, AES192, or AES256 are valid arguments.

engineId

Blank

v3

None

contextEngineId

Blank

v3

None

contextName

Blank

v3

None

enterpriseId

Blank

v3

None
Note on the securityLevel field

Possible values for this field:

  • 1 means noAuthNoPriv.

  • 2 means authNoPriv.

  • 3 means authPriv.

If you do not set the security level manually it is determined automatically:

  • If no authPassPhrase set, the securityLevel is 1.

  • If authPassPhrase is set but no privPassPhrase is set, the securityLevel is 2.

  • If both a authPassPhrase and a privPassPhrase are set, the securityLevel is 3.

In the JSON examples below, the commented sections are explanatory only and are not part of the actual JSON body that you would send in a request.
Example: Full JSON Configuration for GET, Upload and Download
{
  "maxRepetitions": 2, (1)
  "maxRequestSize": 65535,
  "readCommunity": "public123",
  "definition": [
    {
      "range": [
        {
          "begin": "10.0.0.0",
          "end": "10.0.0.9"
        }
      ],
      "readCommunity": "myReadCommunityFor10Net" (2)
    },
    {
      "specific": [
        "10.9.9.9", "10.11.12.13"
      ]
      (2)
    },
    {
      "ipMatch": [
        "10.0.0.*", "192.168.*.*"
      ]
      (2)
    }
  ],
  "profiles": {
    "profile": [
      {
        "label": "datacenter1",
        "filter": "filter expression 1"
        (3)
      },
      {
        "label": "datacenter2",
        "filter": "filter expression 2"
        (3)
      }
    ]
  }
}
1 Any fields from the table above can go here, these are the default overrides, if any. They can be omitted or null to use the system defaults
2 Any fields from the table above can go here, to override the defaults for this definition, specific or ipMatch.
3 Any fields from the table above can go here, to override the defaults for this profile.

When updating a Definition or Profile, use the JSON body that’s inside the definition or profile array, respectively.

Example: PUT Definition, JSON Configuration
{
  "maxRepetitions": 2, (1)
  "maxRequestSize": 65535,
  "readCommunity": "public123",
  "range": [
    {
      "begin": "10.0.0.0",
      "end": "10.0.0.9"
    }
  ]
}
1 Any fields from the table above can go here, these are the overrides for this definition.
Example: POST Profile, JSON Configuration
{
  "maxRepetitions": 2, (1)
  "maxRequestSize": 65535,
  "readCommunity": "public123",
  "label": "myProfileLabel",
  "filter": "myFilterExpression"
}
1 Any fields from the table above can go here, these are the overrides for this profile.

curl Examples

Example: Add a Definition
curl -v -u admin:admin -X PUT -H "Content-Type: application/json" \
     -d @./your-data-file.json \
     http://localhost:8980/opennms/api/v2/snmp-config/definition

Creates or updates a definition entry, with configuration in the given local JSON file.

Example: Add a Definition (inline)
curl -v -u admin:admin -X PUT \
   -H "Content-Type: application/json" \
   -d \
'{
  "readCommunity": "public-123",
  "timeout": 2000,
  "range": [
    {
      "begin": "10.0.0.0",
      "end": "10.0.0.9"
    }
  ],
  "ipMatch": ["10.9.9.9"]
}' \
 'http://localhost:8980/opennms/api/v2/snmp-config/definition'

Creates or updates a definition entry, with configuration inline.

Example: Get entire SNMP Configuration in JSON Format
curl -v -u admin:admin http://localhost:8980/opennms/api/v2/snmp-config
Example: Download entire SNMP Configuration in JSON Format
curl -v -u admin:admin http://localhost:8980/opennms/api/v2/snmp-config/download
Example: Download entire SNMP Configuration in XML Format
curl -v -u admin:admin http://localhost:8980/opennms/api/v2/snmp-config/download?format=xml
Example: Look up configuration for IP address
curl -v -u admin:admin \
 'http://localhost:8980/opennms/api/v2/snmp-config/lookup?ipAddress=10.0.0.2&location=Default'