The SNMP interfaces of the openUBMC community are implemented using mapping solutions that require commands to be configured in the JSON file. The interface mapping configuration file of the SNMP interface is stored in the SNMP path of the rackmount code repository.

This section describes only the configuration rules of SNMP interfaces. For the common mechanism of interface mapping configuration, see Interface Mapping Configuration.

Interface URI

A URI example is as follows:

json

"Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.1/Systems/Readwrite"

NOTE

{{SnmpOemIdentifier}} is the target field for batch field replacement. If the default configuration is used, 2011.2.235.1.1 is loaded. For details about the meaning and configuration method, see section Batch Field Replacement in the Multi-Layer Interface Customization.

The URI format is as follows:

shell

/snmp/InterfaceOID/Interface name/Interface mode

Interface OID Each interface OID must be globally unique.
Interface Name Interface names need not be globally unique.
Interface Mode
- Readwrite: supports GET and PATCH operations, meaning it is readable and writable.
- Readonly: supports only GET operations, meaning it is only readable.
- Setonly: supports only PATCH or POST operations, including write-only, import, export, and upgrade operations.

Data Type

SNMP data types are classified into common data types, common structured data types, and application data types. Currently, only the common data types and application data types are involved. The common data types are:

INTEGER: Signed integer with a range of -2,147,483,648–2,147,483,647. The corresponding attribute data type in the interface mapping configuration is integer.
OCTET STRING:Character string. The corresponding attribute data type in the interface mapping configuration is string.
OBJECT IDENTIFIER: Object identifier, typically used for alarm event OIDs. The corresponding attribute data type in the interface mapping configuration is objectId.

The application data types are:

IpAddress: IP address. The corresponding attribute data type in the interface mapping configuration is ipAddress.

SNMP interfaces are classified into simple interfaces and Table interfaces. Simple interfaces query and set single attributes, while Table interfaces query and set multiple attributes of collection resources.

Simple Interface

There is no special configuration requirements and you can refer to Interface Mapping Configuration for implementation.

Configuration Example

json

{
    "Resources": [
        {
            "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.1/Systems/Readwrite",
            "Interfaces": [
                {
                    "Type": "GET",
                    "RspBody": {
                        "Name": "${ProcessingFlow[1]/Destination/Name}"
                    },
                    "ProcessingFlow": [
                        {
                            "Type": "Property",
                            "Path": "/bmc/kepler/System",
                            "Interface": "bmc.kepler.System",
                            "Destination": {
                                "Name": "Name"
                            }
                        }
                    ]
                },
                {
                    "Type": "PATCH",
                    "ReqBody": {
                        "Type": "object",
                        "Required": true,
                        "Properties": {
                            "UserName": {
                                "Type": "string",
                                "Required": true
                            }
                        }
                    },
                    "ProcessingFlow": [
                        {
                            "Type": "Property",
                            "Path": "/bmc/kepler/System",
                            "Interface": "bmc.kepler.System",
                            "Source": {
                                "Name": "${ReqBody/Name}"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

`Table` Interface

Table interfaces query and set multiple attributes of collection resources.

Configuration Example

json

{
    "Resources": [
        {
            "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.2/Devices/Readwrite",
            "Sequence": [
                {
                    "Name": "Id",
                    "Type": "integer",
                    "Access": "Readonly",
                    "Primary": true
                },
                {
                    "Name": "Enabled",
                    "Type": "integer",
                    "Access": "Readwrite"
                }
            ],
            "Interfaces": [
                {
                    "Type": "GET",
                    "RspBody": {
                        "Devices": "${Statements/Devices()}"
                    },
                    "Statements": {
                        "Devices": {
                            "Input": "${ProcessingFlow[1]/Destination/Devices}",
                            "Steps": [
                                {
                                    "Type": "Expand",
                                    "Formula": "1"
                                }
                            ]
                        }
                    },
                    "ProcessingFlow": [
                        {
                            "Type": "List",
                            "Path": "/bmc/kepler/Devices",
                            "Destination": {
                                "Members": "Devices"
                            }
                        }
                    ]
                },
                {
                    "Type": "PATCH",
                    "ReqBody": {
                        "Type": "object",
                        "Required": true,
                        "Properties": {
                            "Id": {
                                "Type": "integer",
                                "Required": true
                            },
                            "Enabled": {
                                "Type": "integer"
                            }
                        }
                    },
                    "ProcessingFlow": [
                        {
                            "Type": "Property",
                            "Path": "/bmc/kepler/Devices/${ReqBody/Id}",
                            "Interface": "bmc.kepler.Device",
                            "Source": {
                                "Enabled": "${ReqBody/Enabled}"
                            }
                        }
                    ]
                }
            ]
        },
        {
            "Uri": "/bmc/kepler/Devices/:id",
            "Interfaces": [
                {
                    "Type": "GET",
                    "RspBody": {
                        "Id": "${Uri/id}",
                        "Enabled": "${ProcessingFlow[1]/Destination/Enabled}"
                    },
                    "ProcessingFlow": [
                        {
                            "Type": "Property",
                            "Path": "/bmc/kepler/Devices/${Uri/Id}",
                            "Interface": "bmc.kepler.Device",
                            "Destination": {
                                "Enabled": "Enabled"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

`Sequence`

The Sequence field indicates the name and data type of each interface attribute and whether it is a primary key. A Sequence must contain at least one primary key, configured using the Primary field. The value of the primary key helps distinguish different sub-resources. A configuration example is as follows:

json

"Sequence": [
    {
        "Name": "Id",
        "Type": "integer",
        "Access": "Readonly",
        "Primary": true
    },
    {
        "Name": "Enabled",
        "Type": "integer",
        "Access": "Readwrite"
    }
]

In the preceding example, the Id field indicates the primary key. If a system has four device sub-resources, the Id value returned by the SNMP interface can be 1, 2, 3, or 4 to distinguish these device sub-resources.

IMPORTANT

Ensure different primary key values are set for different sub-resources. Otherwise, unexpected results may be returned due to overwriting.

Response Body `RspBody`

Example:

json

"RspBody": {
    "Devices": "${Statements/Devices()}"
}

The RspBody contains only one attribute, whose value is a collection resource array. Each element in the array represents a sub-resource. . For example, the returned sub-resource attribute values are as follows:

json

{
    "Id": 1,
    "Enabled": 2
}

Request Body `ReqBody`

The request body must contain a primary key, which can be used to index the corresponding sub-resource in the interface mapping configuration. The attribute name and data type of the primary key must be the same as those defined in the Sequence. Other attributes in the request body can be configured on demand. Example:

json

{
    "Type": "PATCH",
    "ReqBody": {
        "Type": "object",
        "Required": true,
        "Properties": {
            "Id": {
                "Type": "integer",
                "Required": true
            },
            "Enabled": {
                "Type": "integer"
            }
        }
    },
    "ProcessingFlow": [
        {
            "Type": "Property",
            "Path": "/bmc/kepler/Devices/${ReqBody/Id}",
            "Interface": "bmc.kepler.Device",
            "Source": {
                "Enabled": "${ReqBody/Enabled}"
            }
        }
    ]
}

In the ReqBody, the Id field indicates the primary key, and its attribute name and data type are the same as those defined in Sequence.

Interface Error Code

SNMP interfaces utilize an error engine to define SNMP error codes returned upon execution failure. In the mdb_interface code repository error type definition, the SnmpStatusCode field is assigned to each error type to establish a mapping between the error engine and each SNMP error code. Currently, most error types have defined SnmpStatusCode mappings; if unspecified, the SnmpStatusCode returns 5 by default.

The following example shows definition of an error type. When a PropertyValueTypeError is thrown by the service code during SNMP interface request processing, the final SNMP error code received will be 7 as defined by the SnmpStatusCode mapping.

json

"PropertyValueTypeError": {
    "Description": "Indicates that a property was given the wrong value type, such as when a number is supplied for a property that requires a string.",
    "Message": "The value %1 for the property %2 is of a different type than the property can accept.",
    "Severity": "Warning",
    "NumberOfArgs": 2,
    "ParamTypes": [
        "string",
        "string"
    ],
    "Resolution": "Correct the value for the property in the request body and resubmit the request if the operation failed.",
    "HttpStatusCode": 400,
    "IpmiCompletionCode": "0xFF",
    "SnmpStatusCode": 7,
    "TraceDepth": 0
}

SNMP Error Code Definition

The SNMP protocol defines 18 error codes, as shown in the table below:

Macro Definition	Constant Value	Description
`SNMP_ERRORSTATUS_NOERROR`	0	No error occurs.
`SNMP_ERRORSTATUS_TOOBIG`	1	The requested SNMP operation result cannot be placed in a single SNMP message.
`SNMP_ERRORSTATUS_NOSUCHNAME`	2	The requested SNMP operation identifies an unknown variable.
`SNMP_ERRORSTATUS_BADVALUE`	3	The requested SNMP operation attempts to change the variable, but it specifies a syntax or value error.
`SNMP_ERRORSTATUS_READONLY`	4	The requested SNMP operation attempts to change a variable that cannot be changed.
`SNMP_ERRORSTATUS_GENERR`	5	An error other than the one listed here occurs during the requested SNMP operation.
`SNMP_ERRORSTATUS_NOACCESS`	6	The specified SNMP variable cannot be accessed.
`SNMP_ERRORSTATUS_WRONGTYPE`	7	The value specifies a type that is inconsistent with the type required by the variable.
`SNMP_ERRORSTATUS_WRONGLENGTH`	8	The value specifies a type that does not match the length required by the variable.
`SNMP_ERRORSTATUS_WRONGENCODING`	9	The value contains an abstract syntax notation (ASN.1) encoding that is inconsistent with the ASN.1 label of the field.
`SNMP_ERRORSTATUS_WRONGVALUE`	10	The value cannot be assigned to a variable.
`SNMP_ERRORSTATUS_NOCREATION`	11	The variable does not exist and the agent cannot create it.
`SNMP_ERRORSTATUS_INCONSISTENTVALUE`	12	The value is different from that of other managed objects.
`SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE`	13	Assigning a value to a variable requires resources that are not currently available.
`SNMP_ERRORSTATUS_COMMITFAILED`	14	No verification error occurs, but no variable is updated.
`SNMP_ERRORSTATUS_UNDOFAILED`	15	No verification error occurs. Some variables have been updated because their values cannot be undone.
`SNMP_ERRORSTATUS_AUTHORIZATIONERROR`	16	An authorization error occurs.
`SNMP_ERRORSTATUS_NOTWRITABLE`	17	The variable exists, but the agent cannot modify it.
`SNMP_ERRORSTATUS_INCONSISTENTNAME`	18	The variable does not exist; the agent cannot create it because the value of the named object instance is different from that of other managed objects.

NOTE

To add an error type to the mdb_interface code repository error type definition, add the SNMP error code definition (that is, the SnmpStatusCode field) for the new error type based on backend service requirements; otherwise, if the backend component returns an error of this type, the SNMP interface returns SNMP_ERRORSTATUS_GENERR by default.

SNMPv1 Error Code Mapping

SNMPv1 only recognizes error codes within the range of 0–5 (6 types). When SNMPv1 is used to access an SNMP interface, if the backend component returns an error code outside this range, the SNMP interface layer will convert it.

Errors caused by node values (such as invalid value, type, or length, encoding failure, and inconsistent value) are converted to SNMP_ERRORSTATUS_BADVALUE.
Errors due to access failures (such as node not created, authentication failure, unwritable attribute, or name mismatch) are converted to SNMP_ERRORSTATUS_NOSUCHNAME.
All other unclassified errors are converted to SNMP_ERRORSTATUS_GENERR.

The conversion rules are as follows:

Macro Definition of Error Codes Thrown by the Backend	Macro Definition of SNMPv1 Error Codes
SNMP_ERRORSTATUS_WRONGTYPE	SNMP_ERRORSTATUS_BADVALUE
SNMP_ERRORSTATUS_WRONGLENGTH
SNMP_ERRORSTATUS_WRONGENCODING
SNMP_ERRORSTATUS_WRONGVALUE
SNMP_ERRORSTATUS_INCONSISTENTVALUE
SNMP_ERRORSTATUS_NOACCESS	SNMP_ERRORSTATUS_NOSUCHNAME
SNMP_ERRORSTATUS_NOCREATION
SNMP_ERRORSTATUS_AUTHORIZATIONERROR
SNMP_ERRORSTATUS_NOTWRITABLE
SNMP_ERRORSTATUS_INCONSISTENTNAME
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE	SNMP_ERRORSTATUS_GENERR
SNMP_ERRORSTATUS_COMMITFAILED
SNMP_ERRORSTATUS_UNDOFAILED

Specific Fields

Some of the SNMP interface configuration rules are different from those of other northbound interfaces.

SNMPv1v2cSupported Field

This field is used to configure whether to allow SNMPv1 and SNMPv2c to access the SNMP interface. If this field is not set, the default value is true (allowing access by both SNMPv1 and SNMPv2c).

Configuration example:

json

{
    "Resources": [
        {
            "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.1/Systems/Readwrite",
            "Interfaces": [
                {
                    "Type": "PATCH",
                    "SNMPv1v2cSupported": false,
                    "ReqBody": { xxx },
                    "ProcessingFlow": [
                        { xxx }
                    ]
                }
            ]
        }
    ]
}

In the preceding example, the value of SNMPv1v2cSupported is set to false, meaning that SNMPv1 and SNMPv2c cannot access this interface.

@Instance Field

For Table interfaces, the Instance value is the same as the primary key value by default. To customize the Instance value for a Table interface, you can use the @Instance field for configuration. The @Instance field is an array type that supports SNMP interfaces with multiple Instance values. Example:

json

{
    "Resources": [
        {
            "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.7.50/fruPowerDescriptionTable/Readwrite",
            "Sequence": [
                {
                    "Name": "fruNum",
                    "Type": "integer",
                    "Access": "Readonly",
                    "Primary": true
                },
                {
                    "Name": "fruPowerControl",
                    "Type": "string",
                    "Access": "Setonly"
                }
            ],
            "Interfaces": [
                {
                    "Type": "GET",
                    "RspBody": {
                        "Sequence": [
                            {
                                "@Instance": [
                                    1
                                ],
                                "fruNum": 0,
                                "fruPowerControl": "write-only"
                            },
                            {
                                "@Instance": [
                                    5
                                ],
                                "fruNum": 4,
                                "fruPowerControl": "write-only"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

The above interface mapping configuration defines a GET interface for a Table SNMP interface with fruNum as the primary key. If you walk this SNMP interface, the corresponding GET interface will be invoked, producing the following response (assuming {{SnmpOemIdentifier}} retains its default value of 2011.2.235.1.1):

shell

iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.1.1 = INTEGER: 0
iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.1.5 = INTEGER: 4
iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.2.1 = STRING: "write-only"
iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.2.5 = STRING: "write-only"

For the instance iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.1.0 = INTEGER: 0 with primary key value 0, the Instance value is configured as 1. Without the @Instance field, the instance value would match the primary key value (0), and the resulting instance would be iso.3.6.1.4.1.2011.2.235.1.1.7.50.1.1.0 = INTEGER: 0.

Task Mechanism

When an SNMP interface that incorporates a task mechanism is accessed, backend service components initiate an asynchronous task to execute the corresponding service operations. Meanwhile, the task's progress and error details can be queried through other SNMP interfaces.

Creating a Task

For details about the configuration rules, refer to Interface Mapping Configuration.

Example

json

{
    "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.3/Upgrade/Setonly",
    "Interfaces": [
        {
            "Type": "POST",
            "SNMPv1v2cSupported": false,
            "ReqBody": {
                "Type": "object",
                "Required": true,
                "Properties": {
                    "FilePath": {
                        "Type": "string",
                        "Required": true
                    }
                }
            },
            "ProcessingFlow": [
                {
                    "Type": "Task",
                    "Path": "/bmc/kepler/System",
                    "Interface": "bmc.kepler.System",
                    "Name": "StartUpgrade",
                    "Params": [
                        "${ReqBody/FilePath}"
                    ],
                    "Destination": {
                        "TaskId": "TaskId"
                    }
                }
            ]
        }
    ]
}

Querying Task Information

Configuring the Mapping Interface to Obtain Task Information

json

{
    "Uri": "/bmc/kepler/System/TaskService/Tasks/:taskid",
    "Interfaces": [
        {
            "Type": "GET",
            "RspBody": {
                "Progress": "${ProcessingFlow[1]/Destination/Progress}"
            },
            "ProcessingFlow": [
                {
                    "Type": "Property",
                    "Path": "/bmc/kepler/System/TaskService/Tasks/${Uri/taskid}",
                    "Interface": "bmc.kepler.TaskService.Task",
                    "Destination": {
                        "Progress": "Progress"
                    }
                }
            ]
        }
    ]
}

For example, in the preceding interface configuration, the task URI is /bmc/kepler/System/TaskService/Tasks/:taskid. The prefix /bmc/kepler/System/TaskService/Tasks/ must align with the Task path prefix of the resource collaboration interface. In this example, the Task path could be /bmc/kepler/System/TaskService/Tasks/3545341234.

Configuring the Task Information Query Interface

json

{
    "Uri": "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.5/UpgradeProgress/Readonly",
    "Interfaces": [
        {
            "Type": "GET",
            "TaskReferenceUri": [
                "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.42.2/Upgrade/Setonly",
                "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.4/Reset/Setonly"
            ],
            "RspBody": {
                "Progress": "-1"
            }
        }
    ]
}

`TaskReferenceUri` Field

The TaskReferenceUri field specifies the URI that created the task being queried. Example:

json

"TaskReferenceUri": [
    "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.42.2/Upgrade/Setonly",
    "/snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.4/Reset/Setonly"
]

If this SNMP interface is accessed to query task information, it will only query tasks created by /snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.42.2/Upgrade/Setonly or /snmp/1.3.6.1.4.1.{{SnmpOemIdentifier}}.0.0.4/Reset/Setonly. If both interfaces have created a task separately, the SNMP interface will prioritize querying the more recently created task.

Default Task Information

If a user queries task information without having accessed the task creation interface, the query will return default task information. To customize the default task information, you can configure the default attribute values in the RspBody field. Example:

json

"RspBody": {
    "Progress": "-1"
}

In this example, the default value of the Progress attribute in the RspBody field is set to "-1", so the interface will return "-1" as the default task information.

Interface URI ​

Data Type ​

Simple Interface ​

Configuration Example ​

Table Interface ​

Configuration Example ​

Sequence ​

Response Body RspBody ​

Request Body ReqBody ​

Interface Error Code ​

SNMP Error Code Definition ​

SNMPv1 Error Code Mapping ​

Specific Fields ​

SNMPv1v2cSupported Field ​

@Instance Field ​

Task Mechanism ​

Creating a Task ​

Example ​

Querying Task Information ​

Configuring the Mapping Interface to Obtain Task Information ​

Configuring the Task Information Query Interface ​

TaskReferenceUri Field ​

Default Task Information ​

Interface URI

Data Type

Simple Interface

Configuration Example

`Table` Interface

Configuration Example

`Sequence`

Response Body `RspBody`

Request Body `ReqBody`

Interface Error Code

SNMP Error Code Definition

SNMPv1 Error Code Mapping

Specific Fields

SNMPv1v2cSupported Field

@Instance Field

Task Mechanism

Creating a Task

Example

Querying Task Information

Configuring the Mapping Interface to Obtain Task Information

Configuring the Task Information Query Interface

`TaskReferenceUri` Field

Default Task Information