SNMP Configuration

Use this interface to edit the community string, SNMP version, etc. for an IP address. If you make a change that would overlap with an existing snmp-config.xml, it will automatically create groups of <definition /> entries as necessary. If no <definition /> entry is created it matches the defaults.

There are different versions of the interface (see below). The following operations are supported:

GETs (reading data)

SNMP Configuration API GET functions
Parameter Description

/snmpConfig/{ipaddress}

Get the SNMP configuration for a given IP address.

/snmpConfig/{ipaddress}?location={location}

Get the SNMP configuration for a given IP address at a given location.

PUT (modifying data)

SNMP Configuration API PUT function
Parameter Description

/snmpConfig/{ipaddress}

Add or update the SNMP configuration for a given IP address.

Determine API version

To determine the version of the API running in your Horizon type http://localhost:8980/opennms/rest/snmpConfig/1.1.1.1 in your browser and look at the output:

  • Version 1: If the output only has attributes community, port, retries, timeout, and version.

  • Version 2: If there are more attributes than those listed in Version 1 (for example, max Repetitions).

API version 1

Version 1 supports only a few attributes defined in snmp-info.xsd.

<xs:schema
    xmlns:tns="http://xmlns.opennms.org/xsd/config/snmp-info"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    version="1.0"
    targetNamespace="http://xmlns.opennms.org/xsd/config/snmp-info">
  <xs:element name="snmp-info" type="tns:snmpInfo"/>
  <xs:complexType name="snmpInfo">
    <xs:sequence>
      <xs:element name="community" type="xs:string" minOccurs="0"/>
      <xs:element name="port" type="xs:int"/>
      <xs:element name="retries" type="xs:int"/>
      <xs:element name="timeout" type="xs:int"/>
      <xs:element name="version" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

The following table shows all supported attributes, optional restrictions, and the mapping between snmp-info.xsd and snmp-config.xsd. All parameters can be set regardless of the version:

Attribute snmp-info.xml Attribute snmp-config.xml Default Value Restriction

version

version

v1

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

port

port

161

Integer > 0

retries

retry

1

Integer > 0

timeout

timeout

3000

Integer > 0

community

read-community

public

Any string with a length >= 1
Example 1:
curl -v -u admin:admin -X PUT -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d "<snmp-info>
             <community>yRuSonoZ</community>
             <port>161</port>
             <retries>1</retries>
             <timeout>2000</timeout>
             <version>v2c</version>
          </snmp-info>" \
     http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Creates or updates a <definition/> entry for IP address 10.1.1.1 in snmp-config.xml.

Example 2:
curl -v -u admin:admin -X GET ://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Returns the SNMP configuration for IP address 10.1.1.1 as defined in example 1.

API version 2

Since version 2, you can set or get all attributes of a <definition /> entry defined in snmp-config.xsd (http://xmlns.opennms.org/xsd/config/snmp) can be set or get via the interface, however it is only possible to set the configuration for one IP address per request and not for a range of IP addresses at a time. This may change in the future.

The interface uses SnmpInfo objects for communication. Therefore it is possible to set, for example, v1 and v3 parameters in one request (for example, readCommunity string and privProtocol string). However, Horizon does not allow this. It lets you set only attributes that have no version restriction (for example, timeout value) or the attributes that are limited to the version (for example, readCommunity string if version is v1/v2c). The same is true for getting data from the API, even if it is possible to store v1 and v3 parameters in one definition block in the snmp-config.xml manually, the REST API will return only the parameters that match the version. If no version is defined, the default is assumed (both in PUT and GET requests).

The SnmpInfo schema is defined as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema
  elementFormDefault="qualified"
  version="1.0"
  targetNamespace="http://xmlns.opennms.org/xsd/config/snmp-info"
  xmlns:tns="http://xmlns.opennms.org/xsd/config/snmp-info"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="snmp-info" type="tns:snmpInfo"/>
  <xs:complexType name="snmpInfo">
    <xs:sequence>
      <xs:element name="authPassPhrase" type="xs:string" minOccurs="0"/>
      <xs:element name="authProtocol" type="xs:string" minOccurs="0"/>
      <xs:element name="community" type="xs:string" minOccurs="0"/>
      <xs:element name="contextEngineId" type="xs:string" minOccurs="0"/>
      <xs:element name="contextName" type="xs:string" minOccurs="0"/>
      <xs:element name="engineId" type="xs:string" minOccurs="0"/>
      <xs:element name="enterpriseId" type="xs:string" minOccurs="0"/>
      <xs:element name="maxRepetitions" type="xs:int" minOccurs="0"/>
      <xs:element name="maxRequestSize" type="xs:int" minOccurs="0"/>
      <xs:element name="maxVarsPerPdu" type="xs:int" minOccurs="0"/>
      <xs:element name="port" type="xs:int" minOccurs="0"/>
      <xs:element name="privPassPhrase" type="xs:string" minOccurs="0"/>
      <xs:element name="privProtocol" type="xs:string" minOccurs="0"/>
      <xs:element name="proxyHost" type="xs:string" minOccurs="0"/>
      <xs:element name="readCommunity" type="xs:string" minOccurs="0"/>
      <xs:element name="retries" type="xs:int" minOccurs="0"/>
      <xs:element name="securityLevel" type="xs:int" minOccurs="0"/>
      <xs:element name="securityName" type="xs:string" minOccurs="0"/>
      <xs:element name="timeout" type="xs:int" minOccurs="0"/>
      <xs:element name="version" type="xs:string" minOccurs="0"/>
      <xs:element name="writeCommunity" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

The following table shows all supported attributes and the mapping between snmp-info.xsd and snmp-config.xsd. It also shows the version limitations, default values, and the restrictions, if any:

Attribute snmp-info.xml Attribute snmp-config.xml Default Value Restricted to Version Restriction

version

version

v1

None

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

port

port

161

None

Integer > 0

retries

retry

1

None

Integer > 0

timeout

timeout

3000

None

Integer > 0

maxVarsPerPdu

max-vars-per-pdu

10

None

Integer > 0

maxRepetitions

max-repetitions

2

None

Integer > 0

maxRequestSize

max-request-size

65535

None

Integer > 0

proxyHost

proxy-host

Blank

None

None

readCommunity

read-community

public

v1, v2c

None

writeCommunity

write-community

private

v1, v2c

None

securityName

security-name

opennmsUser

v3

None

securityLevel

security-level

noAuthNoPriv

v3

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

authPassPhrase

auth-passphrase

0p3nNMSv3

v3

None

authProtocol

auth-protocol

MD5

v3

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

privPassPhrase

privacy-passphrase

0p3nNMSv3

v3

None

privProtocol

privacy-protocol

DES

v3

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

engineId

engine-id

Blank

v3

None

contextEngineId

context-engine-id

Blank

v3

None

contextName

context-name

Blank

v3

None

enterpriseId

enterprise-id

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.

Example 1:
curl -v -u admin:admin -X PUT -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d "<snmp-info>
             <readCommunity>yRuSonoZ</readCommunity>
             <port>161</port>
             <retries>1</retries>
             <timeout>2000</timeout>
             <version>v2c</version>
          </snmp-info>" \
     http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Creates or updates a <definition/> entry for IP address 10.1.1.1 in snmp-config.xml.

Example 2:
curl -v -u admin:admin -X GET http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Returns the SNMP configuration for IP address 10.1.1.1 as defined in example 1.

Example 3:
curl -v -u admin:admin -X PUT -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d "<snmp-info>
             <readCommunity>yRuSonoZ</readCommunity>
             <port>161</port>
             <retries>1</retries>
             <timeout>2000</timeout>
             <version>v1</version>
             <securityName>secret-stuff</securityName>
             <engineId>engineId</engineId>
          </snmp-info>" \
     http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Creates or updates a <definition/> entry for IP address 10.1.1.1 in snmp-config.xml, ignoring attributes securityName and engineId.

Example 4:
curl -v -u admin:admin -X PUT -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -d "<snmp-info>
             <readCommunity>yRuSonoZ</readCommunity>
             <port>161</port>
             <retries>1</retries>
             <timeout>2000</timeout>
             <version>v3</version>
             <securityName>secret-stuff</securityName>
             <engineId>engineId</engineId>
          </snmp-info>" \
     http://localhost:8980/opennms/rest/snmpConfig/10.1.1.1

Creates or updates a <definition/> entry for IP address 10.1.1.1 in snmp-config.xml, ignoring attribute readCommunity.