
= SNMP Configuration (Legacy / Deprecated API)

NOTE: {page-component-title} has been updated to move SNMP Configuration into the database.
Please see xref:development:rest/snmp_configuration.adoc[SNMP Configuration] for the new REST API (`api/v2/snmp-config`).
The legacy API (`rest/snmpConfig`) has been deprecated and will be removed in a future release, and generally speaking you should avoid it and use the new API instead, but if you have a use case that requires the legacy API, this page describes how to use it.

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)

[caption=]
.SNMP Configuration API GET functions
[options="autowidth"]
|===
| 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)

[caption=]
.SNMP Configuration API PUT function
[options="autowidth"]
|===
| 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 {page-component-title} 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`.

[source, xml]
----
<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:

[cols="1,1,1,2"]
|===
| 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:
[source, bash]
----
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:
[source, bash]
----
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.

== 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, {page-component-title} 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:

[source, xml]
----
<?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:

[cols="1,1,1,1,2"]
|===
| 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:
[source, bash]
----
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:
[source, bash]
----
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:
[source, bash]
----
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:
[source, bash]
----
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`.
