Skip to main content

4. Protocol Specification

4.1. Common Constructs​

All SNMP PDUs are constructed using the ASN.1 structure defined in Section 3.

The request-id is used to distinguish among outstanding requests, and by the SNMP entity supporting command responder applications to generate the request-id field of a Response-PDU. By using the request-id, an SNMP entity supporting command generator applications can correlate incoming Response-PDUs with outstanding requests, even when multiple requests to the same SNMP entity are outstanding simultaneously. In cases where an unreliable transport service is used, the same request-id can be used for retransmissions of the same request, but this is not required. The value of request-id need not be sequential, and implementations should take care not to repeat a recently-used value for request-id, as the previous request may have been received but the response lost.

The variable-bindings component of all PDUs is a list of variable bindings. When a PDU is sent from a command generator application, this list represents the management information being requested or the commands being given. In the case of responses to both retrieval and modification operations, this list contains the management information. In the case of responses that report exceptions, the value of each variable binding in the list will contain one of the exception values: noSuchObject, noSuchInstance, or endOfMibView.

Each variable binding is a pairing of a name and a value. The name is an OBJECT IDENTIFIER which specifies a particular object instance, and the value represents the value of the object instance.

4.2. PDU Processing​

This section describes the processing of each type of PDU.

4.2.1. The GetRequest-PDU​

The GetRequest-PDU is generated by a command generator application to retrieve the value of specific object instances.

Upon receipt of a GetRequest-PDU, the receiving SNMP entity supporting command responder applications processes each variable binding in the variable-binding list to produce a Response-PDU. All fields of the Response-PDU have the same values as the corresponding fields of the received request except as indicated below.

Each variable binding is processed as follows:

  1. If the name of the variable binding matches exactly the name of a variable accessible by this request, then the value field of the variable binding is set to the value of the named variable.

  2. Otherwise, if the name of the variable binding does not have an OBJECT IDENTIFIER prefix which exactly matches the OBJECT IDENTIFIER prefix of any variable accessible by this request, then the value field of the variable binding is set to noSuchObject.

  3. Otherwise, the value field of the variable binding is set to noSuchInstance.

If processing of any variable binding fails for a reason other than those listed above, then the Response-PDU is modified to indicate an error condition. The error-status field is set to a value indicating the nature of the error. The value of the error-index field is set to the index of the variable binding for which processing failed (variable bindings are numbered starting at one). The variable-bindings field is then modified: all variable bindings other than the one which caused the error are removed, and the variable binding which caused the error is replaced with an identical variable binding except that the value field is set to NULL.

The generated Response-PDU is returned to the originator of the GetRequest-PDU.

4.2.2. The GetNextRequest-PDU​

The GetNextRequest-PDU is generated by a command generator application to retrieve the value of object instances, where the name of the object instances to be retrieved is unknown.

Upon receipt of a GetNextRequest-PDU, the receiving SNMP entity supporting command responder applications processes each variable binding in the variable-binding list to produce a Response-PDU. All fields of the Response-PDU have the same values as the corresponding fields of the received request except as indicated below.

Each variable binding is processed as follows:

  1. The name of the variable binding is located in the lexicographically ordered list of the names of all variables which are accessible by this request (the ordered list is the conceptual union of the individual ordered lists of variables maintained for all MIB views).

  2. The name of the nearest lexicographic successor to the name of the variable binding is determined. This is the name of the lexicographically next variable which is accessible by this request.

  3. If there is no lexicographic successor, the value field of the variable binding is set to endOfMibView, and the name field of the variable binding is set to the name from the request.

  4. Otherwise, the value field of the variable binding is set to the value of the named variable, and the name field of the variable binding is set to the name of that variable.

If processing of any variable binding fails for a reason other than those listed above, then the Response-PDU is modified to indicate an error condition. The error-status field is set to a value indicating the nature of the error. The value of the error-index field is set to the index of the variable binding for which processing failed. The variable-bindings field is then modified as described for GetRequest-PDU processing.

The generated Response-PDU is returned to the originator of the GetNextRequest-PDU.

4.2.2.1. Table Traversal Example​

One of the most important uses of the GetNextRequest-PDU is the traversal of conceptual tables of information within a MIB. The semantics of this PDU type make such traversals quite straightforward.

The first GetNextRequest-PDU in a traversal is issued to retrieve the first row of the table. The variable bindings in this request typically name the table entry objects, but may also name any preceding object name. The semantics of the GetNextRequest-PDU dictate that the variable bindings returned will be those of the first row of the table.

Subsequent GetNextRequest-PDUs are issued in order to obtain subsequent rows of the table. Each of these PDUs specifies in its variable bindings the name of the variable returned in the previous Response-PDU. Because these names are lexicographically ordered, and because the semantics of the GetNextRequest-PDU dictate that the names returned are the lexicographic successors of those in the request, the rows of the table are returned in lexicographic order.

The traversal process is complete when the name of a variable returned in a Response-PDU does not have the name of the table entry object as a prefix. This occurs either because the agent has no further instances in that table, or because the lexicographically next object instance is an instance of a different object type (because the lexicographically next object type is not a columnar object of that table, or is a columnar object of a different table).

This example demonstrates table traversal using the GetNextRequest-PDU. It uses the fictional table "fooTable", which contains three objects:

fooIndex    OBJECT-TYPE
    SYNTAX      INTEGER
    MAX-ACCESS  not-accessible
    STATUS      current
    ::= { fooEntry 1 }

fooDescr    OBJECT-TYPE
    SYNTAX      DisplayString
    MAX-ACCESS  read-only
    STATUS      current
    ::= { fooEntry 2 }

fooValue    OBJECT-TYPE
    SYNTAX      INTEGER
    MAX-ACCESS  read-write
    STATUS      current
    ::= { fooEntry 3 }

Assume the following instances exist:

fooIndex.1 = 1
fooDescr.1 = "alpha"
fooValue.1 = 10
fooIndex.2 = 2
fooDescr.2 = "beta"
fooValue.2 = 20

The command generator application issues a GetNextRequest-PDU with the following variable bindings:

fooIndex
fooDescr
fooValue

The agent responds with a Response-PDU containing:

fooIndex.1 = 1
fooDescr.1 = "alpha"
fooValue.1 = 10

The command generator application issues another GetNextRequest-PDU with:

fooIndex.1
fooDescr.1
fooValue.1

The agent responds with:

fooIndex.2 = 2
fooDescr.2 = "beta"
fooValue.2 = 20

The command generator application issues another GetNextRequest-PDU with:

fooIndex.2
fooDescr.2
fooValue.2

If there are no more rows in the table, the agent might respond with variable bindings for objects that are not in fooTable, indicating that the end of the table has been reached.

4.2.3. The GetBulkRequest-PDU​

The GetBulkRequest-PDU is generated by a command generator application to efficiently retrieve large amounts of data, such as multiple rows in a table.

Upon receipt of a GetBulkRequest-PDU, the receiving SNMP entity supporting command responder applications processes the request as follows:

The non-repeaters field specifies the number of variable bindings in the variable-binding list for which a single lexicographic successor is to be returned.

The max-repetitions field specifies the maximum number of lexicographic successors to be returned for the remaining variable bindings (those after the first non-repeaters bindings) in the variable-binding list.

The receiving SNMP entity produces a Response-PDU according to the following rules:

  1. The request-id field of the Response-PDU is set to the value of the request-id field of the received GetBulkRequest-PDU.

  2. The error-status field of the Response-PDU is set to noError, and the error-index field is set to zero.

  3. The variable-bindings list of the Response-PDU is filled according to the following procedure:

    a. Let N be the number of variable bindings in the variable-bindings list of the GetBulkRequest-PDU.

    b. Let M be the value of the max-repetitions field of the GetBulkRequest-PDU.

    c. Let R be the value of the non-repeaters field of the GetBulkRequest-PDU.

    d. For the first R variable bindings in the variable-bindings list of the GetBulkRequest-PDU, perform the GetNext operation for each, and place the results in the variable-bindings list of the Response-PDU.

    e. For each of the remaining (N - R) variable bindings in the variable-bindings list of the GetBulkRequest-PDU, the following steps are performed M times, or until there are no more lexicographic successors:

    i. Perform the GetNext operation for the variable binding.

    ii. Place the result in the variable-bindings list of the Response-PDU.

    iii. Use the result as the basis for the next iteration (if any) of this step.

  4. If the size of the generated Response-PDU exceeds a local constraint or the maximum message size of the originator of the request, then the response is generated with an alternative variable-bindings list, using a smaller value for max-repetitions or fewer variable bindings, such that the size constraints are satisfied. Note that in this case, if a smaller value for max-repetitions is used, the value of the max-repetitions field in the Response-PDU will still be set to the value from the GetBulkRequest-PDU (i.e., it is not decremented to reflect the smaller value actually used).

If processing of any variable binding fails for a reason other than those listed above, then the Response-PDU is modified to indicate an error condition. The error-status field is set to a value indicating the nature of the error. The value of the error-index field is set to the index of the variable binding in the GetBulkRequest-PDU for which processing failed. The variable-bindings field is then modified as described for GetRequest-PDU processing.

The generated Response-PDU is returned to the originator of the GetBulkRequest-PDU.

4.2.3.1. Another Table Traversal Example​

This example demonstrates using the GetBulkRequest-PDU to retrieve multiple rows from a table. Consider the same "fooTable" from the previous example.

The command generator application wishes to retrieve up to two rows from fooTable. It issues a GetBulkRequest-PDU with:

  • non-repeaters = 0
  • max-repetitions = 2
  • variable bindings: 
    fooIndex
    fooDescr
    fooValue

The agent responds with a Response-PDU containing up to 2 × 3 = 6 variable bindings:

fooIndex.1 = 1
fooDescr.1 = "alpha"
fooValue.1 = 10
fooIndex.2 = 2
fooDescr.2 = "beta"
fooValue.2 = 20

If there were more rows in the table, the command generator application could continue by issuing another GetBulkRequest-PDU using the last returned object names as the starting point.

The advantage of the GetBulkRequest-PDU is that it reduces the number of protocol exchanges required to retrieve a large table, by allowing multiple rows to be retrieved in a single operation.

4.2.4. The Response-PDU​

The Response-PDU is generated by an SNMP entity supporting command responder applications in response to GetRequest-PDU, GetNextRequest-PDU, GetBulkRequest-PDU, SetRequest-PDU, or InformRequest-PDU, as indicated by the procedures specified in Sections 4.2.1, 4.2.2, 4.2.3, 4.2.5, and 4.2.7, respectively.

Upon receipt of a Response-PDU, the receiving SNMP entity supporting command generator or notification receiver applications processes it according to the procedures of the application.

The request-id field of the Response-PDU is used by the receiving entity to correlate the response with the original request.

The error-status field of the Response-PDU may be set to one of the following values:

  • noError: Indicates that no error occurred during processing of the request.

  • tooBig: Indicates that the agent could not generate a Response-PDU whose size was within local constraints or within the maximum message size of the originator of the request.

  • noSuchName: Used for proxy compatibility. This error should not be generated by an SNMPv2 entity.

  • badValue: Used for proxy compatibility. This error should not be generated by an SNMPv2 entity.

  • readOnly: Used for proxy compatibility. This error should not be generated by an SNMPv2 entity.

  • genErr: Indicates that an error occurred during processing other than one of the errors listed above.

  • noAccess: Indicates that access to the object was denied for security reasons.

  • wrongType: Indicates that the value field of the variable binding has the wrong type for the specified object.

  • wrongLength: Indicates that the value field of the variable binding has the wrong length for the specified object.

  • wrongEncoding: Indicates that the value field of the variable binding has the wrong encoding for the specified object.

  • wrongValue: Indicates that the value field of the variable binding has a value that is not a valid value for the specified object.

  • noCreation: Indicates that the specified object instance may not be created.

  • inconsistentValue: Indicates that the value field of the variable binding is inconsistent with the values of other objects.

  • resourceUnavailable: Indicates that the necessary resources are not available to perform the requested operation.

  • commitFailed: Indicates that the attempt to commit the values failed.

  • undoFailed: Indicates that the attempt to undo the previous set of values failed.

  • authorizationError: Indicates that access to the specified object is not authorized.

  • notWritable: Indicates that the specified object is not writable.

  • inconsistentName: Indicates that the name of the specified object instance is inconsistent with the values of other objects.

The error-index field is set to zero in a Response-PDU generated in response to a GetRequest-PDU, GetNextRequest-PDU, or GetBulkRequest-PDU that did not result in an error. Otherwise, it is set to the index of the variable binding that caused the error.

4.2.5. The SetRequest-PDU​

The SetRequest-PDU is generated by a command generator application to request that the values of one or more object instances be modified.

Upon receipt of a SetRequest-PDU, the receiving SNMP entity supporting command responder applications attempts to set the values of the object instances named in the variable-bindings list to the specified values.

The processing of the SetRequest-PDU is performed in two phases:

Phase one:

In the first phase, the request is validated. If all validations succeed, then the second phase is initiated. If any validation fails, then the entire operation fails, and a Response-PDU is generated with the error-status field set to indicate the nature of the error, and the error-index field set to the index of the variable binding that caused the error.

The following validations are performed in the first phase:

  1. The object named by each variable binding is validated to ensure that:

    • The name is a valid OBJECT IDENTIFIER
    • The object exists and is accessible
    • The object is writable

  2. The value of each variable binding is validated to ensure that:

    • The syntax is correct
    • The length is appropriate
    • The value is in the acceptable range
    • The value is consistent with the values of related objects

Phase two:

If the first phase completes successfully, the second phase begins. In this phase, the values of the object instances are set.

If the second phase fails for any reason, an attempt is made to undo all changes made during this phase (a "rollback"). If the rollback succeeds, a Response-PDU is generated with error-status set to commitFailed. If the rollback fails, a Response-PDU is generated with error-status set to undoFailed.

If the second phase completes successfully, a Response-PDU is generated with:

  • error-status set to noError
  • error-index set to zero
  • variable-bindings list containing the names and values of all object instances that were successfully set

The generated Response-PDU is returned to the originator of the SetRequest-PDU.

Atomicity:

The SetRequest-PDU is atomic - either all variables are updated, or none are. This ensures that the managed system is never left in an inconsistent intermediate state.

4.2.6. The SNMPv2-Trap-PDU​

The SNMPv2-Trap-PDU is generated by an SNMP entity supporting notification originator applications on behalf of a notification generator application. It is used to provide unsolicited notification of events to an SNMP entity supporting notification receiver applications.

The first two variable bindings in the variable-bindings list of an SNMPv2-Trap-PDU are sysUpTime.0 [RFC3418] and snmpTrapOID.0 [RFC3418], respectively. The sysUpTime.0 variable binding represents the time elapsed between the last initialization of the SNMP entity and the generation of the trap. The snmpTrapOID.0 variable binding identifies the type of trap being sent.

If the NOTIFICATION-TYPE macro invocation corresponding to the value of snmpTrapOID.0 includes OBJECTS clauses, then the variable-bindings list also includes variable bindings for the objects specified in those clauses. Additional variable bindings may be included in the variable-bindings list at the discretion of the notification originator application.

Upon receipt of an SNMPv2-Trap-PDU, the receiving SNMP entity supporting notification receiver applications processes the trap according to the procedures of the receiving application. No response is generated to an SNMPv2-Trap-PDU.

4.2.7. The InformRequest-PDU​

The InformRequest-PDU is generated by an SNMP entity supporting notification originator applications on behalf of a notification generator application. It is used to provide notification of events to an SNMP entity supporting notification receiver applications, with acknowledgment of receipt.

The first two variable bindings in the variable-bindings list of an InformRequest-PDU are sysUpTime.0 and snmpTrapOID.0, respectively, as described for SNMPv2-Trap-PDU.

Upon receipt of an InformRequest-PDU, the receiving SNMP entity supporting notification receiver applications processes the inform according to the procedures of the receiving application, and generates a Response-PDU. The Response-PDU has the same value in its request-id field as the received InformRequest-PDU, an error-status of noError, and an error-index of zero. The variable-bindings field of the Response-PDU is identical to that of the received InformRequest-PDU.

The generated Response-PDU is returned to the originator of the InformRequest-PDU. This provides confirmation that the notification was received.

Last updated on