SNMP templates with IMC API

This post describes the behaviour of the IMC RESTful API to view and manipulate SNMP templates within IMC. These are the templates available in the Device View section of the UI which are assigned to SSH devices to provide passwords and other relevant parameters.

The reason for writing isn’t just to short cut other’s dev time but to highlight a failing of the API which will lead to misunderstandings. In particular there is a misunderstanding about the very concept of a template.

About SNMP Templates

Firstly to cover briefly what these templates are. IMC stores a range of templates that cover all the parameters you would need for connectivity with a device. They can be accessed in the UI under the system > Resource Management menu within the Web UI:

In the case of SNMP this is used by most of the automatic monitoring within IMC and in some cases for configuration tasks such as VLAN assignment to links. Once created, the parameters in this template can be used by IMC to connect to a device. They form the server side parameters and not what is configured on the device.

You can assign the template values to a large number of devices using the Batch Operation function under Resource. You can assign the values to an individual device by opening up the device details and using the menu option on the right hand side. In all cases you can manually enter SNMP details (Edit SNMP Parameters) or use a template (Select an Existing Template).

My assumption when just using the UI was that selecting a template for a device or group meant said device(s) are there after linked with that template. If you change the template you then change the values IMC uses for connecting to those device(s). This assumption is wrong.

API

The API has five URLs to deal with the templates themselves. They are referred to in a lot of other places such as API calls to edit device details.

The calls are self explanatory but I want to draw your attention to the one that provides a list of templates. When run you get all of the information from the list of templates you see in the UI when you move to the SNMP template list. When I say all info, I really mean everything including the passwords in clear text.

{
  "snmpParamTemplate": [
    {
      "id": "666",
      "version": "3",
      "name": "default",
      "type": "0",
      "paraType": "SNMPv3 Priv-Aes128 Auth-Md5",
      "roCommunity": "public",
      "rwCommunity": "private",
      "timeout": "10",
      "retries": "5",
      "contextName": "",
      "securityName": "read_only",
      "securityMode": "3",
      "authScheme": "2",
      "authPassword": "password123",
      "privScheme": "19",
      "privPassword": "password123",
      "snmpPort": "161",
      "isAutodiscoverTemp": "1",
      "creator": "admin",
      "accessType": "1",
      "operatorGroupStr": "",
      "link": {
        "@op": "GET",
        "@rel": "self",
        "@href": "https://imc.company.com/imcrs/plat/res/snmp/1"
      }
    },

A common place you’ll see SNMP templates referred to is within the details of a particular device. Using the following URL you will see all the main details for a device and how to monitor it: https://imc.company.com:443/imcrs/plat/res/device/123

For each device there is a field: snmpTmplId

At this point everything ties together. There is a template ID in the device information and each SNMP template has a unique ID. But there is a problem.

When you assign a SNMP template to a device the number you see in the snmpTmplId field under its details doesn’t change. So if you have template ID 666 and you use the UI or API to assign this to a switch, the value under snmpTmplId remains unaltered.

What is more, if you query a handful of device you’ll notice that they all have unique values for snmpTmplId and that these do not match and actual SNMP templates. At this stage you might think there are two distinct lists of SNMP templates with the same name. This isn’t quite true either.

Using the API call as follows you get the details for a particular SNMP template:

https://imc.company.com:443/imcrs/plat/res/snmp/666 

You can query the information for IDs retrieved from a particular device or from the list of SNMP templates seen above. They are all within the same database table and contain the same parameters.

However, it is not possible to assign a device one of the SNMP templates you see in the list in the UI and see that ID when you query the device details. The device will always show that is using its own unique SNMP template. However, the values within this unique template reflect the last assigned SNMP template.

So what actually happens if you assign/link SNMP template ID 666 to a device is that it will still refer to a random, uniquely ID’d snmp template but the values will match.

In other words the SNMP templates are used as a store of values which are then copied to the unique ‘snmp templates’.

Or to put it another way, the SNMP templates referred to within the device details are not, in any way, a template. They are the actual values.

Conclusion

Firstly, once this point is understood everything words as expected and values can be manipulated.

Second, it isn’t possible to query a device and derive which actual template was used to set those values. There is no way to extract the group of switches that are currently using a particular snmp template. In the database they only store their own unique values.

Finally, HPE need to understand better what the word template means and alter the field used within the unique device details.