RFC2263 - SNMPv3 Applications

Network Working Group D. Levi
Request for Comments: 2263 SNMP Research, Inc.
Category: Standards Track P. Meyer
Secure Computing Corporation
B. Stewart
Cisco Systems
January 1998
SNMPv3 Applications
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
Abstract
This memo describes five types of SNMP applications which make use of
an SNMP engine as described in [RFC2261]. The types of application
described are Command Generators, Command Responders, Notification
Originators, Notification Receivers, and Proxy Forwarders.
This memo also defines MIB modules for specifying targets of
management operations, for notification filtering, and for proxy
forwarding.
Table of Contents
1 Overview ..................................................... 2
1.1 Command Generator Applications ............................. 3
1.2 Command Responder Applications ............................. 3
1.3 Notification Originator Applications ....................... 3
1.4 Notification Receiver Applications ......................... 3
1.5 Proxy Forwarder Applications ............................... 3
2 Management Targets ........................................... 5
3 Elements Of Procedure ........................................ 6
3.1 Command Generator Applications ............................. 6
3.2 Command Responder Applications ............................. 8
3.3 Notification Originator Applications ....................... 13
3.4 Notification Receiver Applications ......................... 16
3.5 Proxy Forwarder Applications ............................... 18
3.5.1 Request Forwarding ....................................... 19
3.5.1.1 Processing an Incoming Request ......................... 19
3.5.1.2 Processing an Incoming Response ........................ 22
3.5.1.3 Processing an Incoming Report Indication ............... 23
3.5.2 Notification Forwarding .................................. 24
4 The StrUCture of the MIB Modules ............................. 27
4.1 The Management Target MIB Module ........................... 27
4.1.1 Tag Lists ................................................ 28
4.1.2 Definitions .............................................. 28
4.2 The Notification MIB Module ................................ 41
4.2.1 Definitions .............................................. 42
4.3 The Proxy MIB Module ....................................... 53
4.3.1 Definitions .............................................. 53
5 Identification of Management Targets in Notification
Originators ............................................... 59
6 Notification Filtering ....................................... 60
7 Management Target Translation in Proxy Forwarder
Applications .............................................. 61
7.1 Management Target Translation for Request Forwarding ....... 61
7.2 Management Target Translation for Notification Forwarding
........................................................... 62
8 Intellectual Property ........................................ 63
9 Acknowledgments .............................................. 64
10 Security Considerations ..................................... 65
11 References .................................................. 65
12 Editors" Address ............................................ 67
A. Trap Configuration Example .................................. 68
B. Full Copyright Statement .................................... 70
1. Overview
This document describes five types of SNMP applications:
- Applications which initiate SNMP Get, GetNext, GetBulk, and/or
Set requests, called "command generators."
- Applications which respond to SNMP Get, GetNext, GetBulk,
and/or Set requests, called "command responders."
- Applications which generate notifications, called
"notification originators."
- Applications which receive notifications, called "notification
receivers."
- Applications which forward SNMP Get, GetNext, GetBulk, and/or
Set requests or notifications, called "proxy forwarder."
Note that there are no restrictions on which types of applications
may be associated with a particular SNMP engine. For example, a
single SNMP engine may, in fact, be associated with both command
generator and command responder applications.
1.1. Command Generator Applications
A command generator application initiates SNMP Get, GetNext, GetBulk,
and/or Set requests, as well as processing the response to a request
which it generated.
1.2. Command Responder Applications
A command responder application receives SNMP Get, GetNext, GetBulk,
and/or Set requests destined for the local system as indicated by the
fact that the contextEngineID in the received request is equal to
that of the local engine through which the request was received. The
command responder application will perform the appropriate protocol
operation, using Access control, and will generate a response message
to be sent to the request"s originator.
1.3. Notification Originator Applications
A notification originator application conceptually monitors a system
for particular events or conditions, and generates Trap and/or Inform
messages based on these events or conditions. A notification
originator must have a mechanism for determining where to send
messages, and what SNMP version and security parameters to use when
sending messages. A mechanism and MIB module for this purpose is
provided in this document.
1.4. Notification Receiver Applications
A notification receiver application listens for notification
messages, and generates response messages when a message containing
an Inform PDU is received.
1.5. Proxy Forwarder Applications
A proxy forwarder application forwards SNMP messages. Note that
implementation of a proxy forwarder application is optional. The
sections describing proxy (4.5, 5.3, and 8) may be skipped for
implementations that do not include a proxy forwarder application.
The term "proxy" has historically been used very loosely, with
multiple different meanings. These different meanings include (among
others):
(1) the forwarding of SNMP requests to other SNMP entities without
regard for what managed object types are being accessed; for
example, in order to forward an SNMP request from one transport
domain to another, or to translate SNMP requests of one version
into SNMP requests of another version;
(2) the translation of SNMP requests into operations of some non-SNMP
management protocol; and
(3) support for aggregated managed objects where the value of one
managed object instance depends upon the values of multiple other
(remote) items of management information.
Each of these scenarios can be advantageous; for example, support for
aggregation of management information can significantly reduce the
bandwidth requirements of large-scale management activities.
However, using a single term to cover multiple different scenarios
causes confusion.
To avoid such confusion, this document uses the term "proxy" with a
much more tightly defined meaning. The term "proxy" is used in this
document to refer to a proxy forwarder application which forwards
either SNMP requests, notifications, and responses without regard for
what managed objects are contained within requests or notifications.
This definition is most closely related to the first definition
above. Note, however, that in the SNMP architecture [RFC2261], a
proxy forwarder is actually an application, and need not be
associated with what is traditionally thought of as an SNMP agent.
Specifically, the distinction between a traditional SNMP agent and a
proxy forwarder application is simple:
- a proxy forwarder application forwards requests and/or
notifications to other SNMP engines according to the context,
and irrespective of the specific managed object types being
accessed, and forwards the response to such previously
forwarded messages back to the SNMP engine from which the
original message was received;
- in contrast, the command responder application that is part of
what is traditionally thought of as an SNMP agent, and which
processes SNMP requests according to the (names of the)
individual managed object types and instances being accessed,
is NOT a proxy forwarder application from the perspective of
this document.
Thus, when a proxy forwarder application forwards a request or
notification for a particular contextEngineID / contextName pair, not
only is the information on how to forward the request specifically
associated with that context, but the proxy forwarder application has
no need of a detailed definition of a MIB view (since the proxy
forwarder application forwards the request irrespective of the
managed object types).
In contrast, a command responder application must have the detailed
definition of the MIB view, and even if it needs to issue requests to
other entities, via SNMP or otherwise, that need is dependent on the
individual managed object instances being accessed (i.e., not only on
the context).
Note that it is a design goal of a proxy forwarder application to act
as an intermediary between the endpoints of a transaction. In
particular, when forwarding Inform requests, the associated response
is forwarded when it is received from the target to which the Inform
request was forwarded, rather than generating a response immediately
when an Inform request is received.
2. Management Targets
Some types of applications (notification generators and proxy
forwarders in particular) require a mechanism for determining where
and how to send generated messages. This document provides a
mechanism and MIB module for this purpose. The set of information
that describes where and how to send a message is called a
"Management Target", and consists of two kinds of information:
- Destination information, consisting of a transport domain and
a transport address. This is also termed a transport
endpoint.
- SNMP parameters, consisting of message processing model,
security model, security level, and security name information.
The SNMP-TARGET-MIB module described later in this document contains
one table for each of these types of information. There can be a
many-to-many relationship in the MIB between these two types of
information. That is, there may be multiple transport endpoints
associated with a particular set of SNMP parameters, or a particular
transport endpoint may be associated with several sets of SNMP
parameters.
3. Elements Of Procedure
The following sections describe the procedures followed by each type
of application when generating messages for transmission or when
processing received messages. Applications communicate with the
Dispatcher using the abstract service interfaces defined in [RFC2261].
3.1. Command Generator Applications
A command generator initiates an SNMP request by calling the
Dispatcher using the following abstract service interface:
statusInformation = -- sendPduHandle if success
-- errorIndication if failure
sendPdu(
IN transportDomain -- transport domain to be used
IN transportAddress -- destination network address
IN messageProcessingModel -- typically, SNMP version
IN securityModel -- Security Model to use
IN securityName -- on behalf of this principal
IN securityLevel -- Level of Security requested
IN contextEngineID -- data from/at this entity
IN contextName -- data from/in this context
IN pduVersion -- the version of the PDU
IN PDU -- SNMP Protocol Data Unit
IN eXPectResponse -- TRUE or FALSE
)
Where:
- The transportDomain is that of the destination of the message.
- The transportAddress is that of the destination of the
message.
- The messageProcessingModel indicates which Message Processing
Model the application wishes to use.
- The securityModel is the security model that the application
wishes to use.
- The securityName is the security model independent name for
the principal on whose behalf the application wishes the
message is to be generated.
- The securityLevel is the security level that the application
wishes to use.
- The contextEngineID is provided by the command generator if it
wishes to explicitly specify the location of the management
information it is requesting.
- The contextName is provided by the command generator if it
wishes to explicitly specify the local context name for the
management information it is requesting.
- The pduVersion indicates the version of the PDU to be sent.
- The PDU is a value constructed by the command generator
containing the management operation that the command generator
wishes to perform.
- The expectResponse argument indicates that a response is
expected.
The result of the sendPdu interface indicates whether the PDU was
successfully sent. If it was successfully sent, the returned value
will be a sendPduHandle. The command generator should store the
sendPduHandle so that it can correlate a response to the original
request.
The Dispatcher is responsible for delivering the response to a
particular request to the correct command generator application. The
abstract service interface used is:
processResponsePdu( -- process Response PDU
IN messageProcessingModel -- typically, SNMP version
IN securityModel -- Security Model in use
IN securityName -- on behalf of this principal
IN securityLevel -- Level of Security
IN contextEngineID -- data from/at this SNMP entity
IN contextName -- data from/in this context
IN pduVersion -- the version of the PDU
IN PDU -- SNMP Protocol Data Unit
IN statusInformation -- success or errorIndication
IN sendPduHandle -- handle from sendPDU
)
Where:
- The messageProcessingModel is the value from the received
response.
- The securityModel is the value from the received response.
- The securityName is the value from the received response.
- The securityLevel is the value from the received response.
- The contextEngineID is the value from the received response.
- The contextName is the value from the received response.
- The pduVersion indicates the version of the PDU in the
received response.
- The PDU is the value from the received response.
- The statusInformation indicates success or failure in
receiving the response.
- The sendPduHandle is the value returned by the sendPdu call
which generated the original request to which this is a
response.
The procedure when a command generator receives a message is as
follows:
(1) If the received values of messageProcessingModel, securityModel,
securityName, contextEngineID, contextName, and pduVersion are not
all equal to the values used in the original request, the response
is discarded.
(2) The operation type, request-id, error-status, error-index, and
variable-bindings are extracted from the PDU and saved. If the
request-id is not equal to the value used in the original request,
the response is discarded.
(3) At this point, it is up to the application to take an appropriate
action. The specific action is implementation dependent. If the
statusInformation indicates that the request failed, an appropriate
action might be to attempt to transmit the request again, or to
notify the person operating the application that a failure
occurred.
3.2. Command Responder Applications
Before a command responder application can process messages, it must
first associate itself with an SNMP engine. The abstract service
interface used for this purpose is:
statusInformation = -- success or errorIndication
registerContextEngineID(
IN contextEngineID -- take responsibility for this one
IN pduType -- the pduType(s) to be registered
)
Where:
- The statusInformation indicates success or failure of the
registration attempt.
- The contextEngineID is equal to the snmpEngineID of the SNMP
engine with which the command responder is registering.
- The pduType indicates a Get, GetNext, GetBulk, or Set pdu.
Note that if another command responder application is already
registered with an SNMP engine, any further attempts to register with
the same contextEngineID and pduType will be denied. This implies
that separate command responder applications could register
separately for the various pdu types. However, in practice this is
undesirable, and only a single command responder application should
be registered with an SNMP engine at any given time.
A command responder application can disassociate with an SNMP engine
using the following abstract service interface:
unregisterContextEngineID(
IN contextEngineID -- give up responsibility for this one
IN pduType -- the pduType(s) to be unregistered
)
Where:
- The contextEngineID is equal to the snmpEngineID of the SNMP
engine with which the command responder is cancelling the
registration.
- The pduType indicates a Get, GetNext, GetBulk, or Set pdu.
Once the command responder has registered with the SNMP engine, it
waits to receive SNMP messages. The abstract service interface used
for receiving messages is:
processPdu( -- process Request/Notification PDU
IN messageProcessingModel -- typically, SNMP version
IN securityModel -- Security Model in use
IN securityName -- on behalf of this principal
IN securityLevel -- Level of Security
IN contextEngineID -- data from/at this SNMP entity
IN contextName -- data from/in this context
IN pduVersion -- the version of the PDU
IN PDU -- SNMP Protocol Data Unit
IN maxSizeResponseScopedPDU -- maximum size of the Response PDU
IN stateReference -- reference to state information
) -- needed when sending a response
Where:
- The messageProcessingModel indicates which Message Processing
Model received and processed the message.
- The securityModel is the value from the received message.
- The securityName is the value from the received message.
- The securityLevel is the value from the received message.
- The contextEngineID is the value from the received message.
- The contextName is the value from the received message.
- The pduVersion indicates the version of the PDU in the
received message.
- The PDU is the value from the received message.
- The maxSizeResponseScopedPDU is the maximum allowable size of
a ScopedPDU containing a Response PDU (based on the maximum
message size that the originator of the message can accept).
- The stateReference is a value which references cached
information about each received request message. This value
must be returned to the Dispatcher in order to generate a
response.
The procedure when a message is received is as follows.
(1) The operation type is determined from the ASN.1 tag value
associated with the PDU parameter. The operation type should
always be one of the types previously registered by the
application.
(2) The request-id is extracted from the PDU and saved.
(3) If the SNMPv2 operation type is GetBulk, the non-repeaters and
max-repetitions values are extracted from the PDU and saved.
(4) The variable-bindings are extracted from the PDU and saved.
(5) The management operation represented by the SNMPv2 operation type
is performed with respect to the relevant MIB view within the
context named by the contextName, according to the procedures set
forth in [RFC1905]. The relevant MIB view is determined by the
securityLevel, securityModel, contextName, securityName, and SNMPv2
operation type. To determine whether a particular object instance
is within the relevant MIB view, the following abstract service
interface is called:
statusInformation = -- success or errorIndication
isAccessAllowed(
IN securityModel -- Security Model in use
IN securityName -- principal who wants to access
IN securityLevel -- Level of Security
IN viewType -- read, write, or notify view
IN contextName -- context containing variableName
IN variableName -- OID for the managed object
)
Where:
- The securityModel is the value from the received message.
- The securityName is the value from the received message.
- The securityLevel is the value from the received message.
- The viewType indicates whether the PDU type is a read or write
operation.
- The contextName is the value from the received message.
- The variableName is the object instance of the variable for
which access rights are to be checked.
Normally, the result of the management operation will be a new PDU
value, and processing will continue in step (6) below. However, at
any time during the processing of the management operation:
- If the isAccessAllowed ASI returns a noSuchView,
noAccessEntry, or noGroupName error, processing of the
management operation is halted, a PDU value is contructed
using the values from the originally received PDU, but
replacing the error_status with an authorizationError code,
and error_index value of 0, and control is passed to step (6)
below.
- If the isAccessAllowed ASI returns an otherError, processing
of the management operation is halted, a different PDU value
is contructed using the values from the originally received
PDU, but replacing the error_status with a genError code, and
control is passed to step (6) below.
- If the isAccessAllowed ASI returns a noSuchContext error,
processing of the management operation is halted, no result
PDU is generated, the snmpUnknownContexts counter is
incremented, and control is passed to step (6) below.
- If the context named by the contextName parameter is
unavailable, processing of the management operation is halted,
no result PDU is generated, the snmpUnavailableContexts
counter is incremented, and control is passed to step (6)
below.
(6) The Dispatcher is called to generate a response or report message.
The abstract service interface is:
returnResponsePdu(
IN messageProcessingModel -- typically, SNMP version
IN securityModel -- Security Model in use
IN securityName -- on behalf of this principal
IN securityLevel -- same as on incoming request
IN contextEngineID -- data from/at this SNMP entity
IN contextName -- data from/in this context
IN pduVersion -- the version of the PDU
IN PDU -- SNMP Protocol Data Unit
IN maxSizeResponseScopedPDU -- maximum size of the Response PDU
IN stateReference -- reference to state information
-- as presented with the request
IN statusInformation -- success or errorIndication
) -- error counter OID/value if error
Where:
- The messageProcessingModel is the value from the processPdu
call.
- The securityModel is the value from the processPdu call.
- The securityName is the value from the processPdu call.
- The securityLevel is the value from the processPdu call.
- The contextEngineID is the value from the processPdu call.
- The contextName is the value from the processPdu call.
- The pduVersion indicates the version of the PDU to be
returned. If no result PDU was generated, the pduVersion is
an undefined value.
- The PDU is the result generated in step (5) above. If no
result PDU was generated, the PDU is an undefined value.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the value from the processPdu call.
- The statusInformation either contains an indication that no
error occurred and that a response should be generated, or
contains an indication that an error occurred along with the
OID and counter value of the appropriate error counter object.
Note that a command responder application should always call the
returnResponsePdu abstract service interface, even in the event of an
error such as a resource allocation error. In the event of such an
error, the PDU value passed to returnResponsePdu should contain
appropriate values for errorStatus and errorIndex.
3.3. Notification Originator Applications
A notification originator application generates SNMP notification
messages. A notification message may, for example, contain an
SNMPv2-Trap PDU or an Inform PDU. However, a particular
implementation is not required to be capable of generating both types
of messages.
Notification originator applications require a mechanism for
identifying the management targets to which notifications should be
sent. The particular mechanism used is implementation dependent.
However, if an implementation makes the configuration of management
targets SNMP manageable, it MUST use the SNMP-TARGET-MIB module
described in this document.
When a notification originator wishes to generate a notification, it
must first determine in which context the information to be conveyed
in the notification exists, i.e., it must determine the
contextEngineID and contextName. It must then determine the set of
management targets to which the notification should be sent. The
application must also determine, for each management target, whether
the notification message should contain an SNMPv2-Trap PDU or Inform
PDU, and if it is to contain an Inform PDU, the number of retries and
retransmission algorithm.
The mechanism by which a notification originator determines this
information is implementation dependent. Once the application has
determined this information, the following procedure is performed for
each management target:
(1) Any appropriate filtering mechanisms are applied to determine
whether the notification should be sent to the management target.
If such filtering mechanisms determine that the notification should
not be sent, processing continues with the next management target.
Otherwise,
(2) The appropriate set of variable-bindings is retrieved from local
MIB instrumentation within the relevant MIB view. The relevant MIB
view is determined by the securityLevel, securityModel,
contextName, and securityName of the management target. To
determine whether a particular object instance is within the
relevant MIB view, the isAccessAllowed abstract service interface
is used, in the same manner as described in the preceding section.
If the statusInformation returned by isAccessAllowed does not
indicate accessAllowed, the notification is not sent to the
management target.
(3) A PDU is constructed using a locally unique request-id value, an
operation type of SNMPv2-Trap or Inform, an error-status and
error-index value of 0, and the variable-bindings supplied
previously in step (2).
(4) If the notification contains an SNMPv2-Trap PDU, the Dispatcher is
called using the following abstract service interface:
statusInformation = -- sendPduHandle if success
-- errorIndication if failure
sendPdu(
IN transportDomain -- transport domain to be used
IN transportAddress -- destination network address
IN messageProcessingModel -- typically, SNMP version
IN securityModel -- Security Model to use
IN securityName -- on behalf of this principal
IN securityLevel -- Level of Security requested
IN contextEngineID -- data from/at this entity
IN contextName -- data from/in this context
IN pduVersion -- the version of the PDU
IN PDU -- SNMP Protocol Data Unit
IN expectResponse -- TRUE or FALSE
)
Where:
- The transportDomain is that of the management target.
- The transportAddress is that of the management target.
- The messageProcessingModel is that of the management target.
- The securityModel is that of the management target.
- The securityName is that of the management target.
- The securityLevel is that of the management target.
- The contextEngineID is the value originally determined for the
notification.
- The contextName is the value originally determined for the
notification.
- The pduVersion is the version of the PDU to be sent.
- The PDU is the value constructed in step (3) above.
- The expectResponse argument indicates that no response is
expected.
Otherwise,
(5) If the notification contains an Inform PDU, then:
a) The Dispatcher is called using the sendPdu abstract service
interface as described in step (4) above, except that the
expectResponse argument indicates that a response is expected.
b) The application caches information about the management
target.
c) If a response is received within an appropriate time interval
from the transport endpoint of the management target, the
notification is considered acknowledged and the cached
information is deleted. Otherwise,
d) If a response is not received within an appropriate time
period, or if a report indication is received, information
about the management target is retrieved from the cache, and
steps a) through d) are repeated. The number of times these
steps are repeated is equal to the previously determined retry
count. If this retry count is exceeded, the acknowledgement
of the notification is considered to have failed, and
processing of the notification for this management target is
halted.
Responses to Inform PDU notifications will be received via the
processResponsePDU abstract service interface.
3.4. Notification Receiver Applications
Notification receiver applications receive SNMP Notification messages
from the Dispatcher. Before any messages can be received, the
notification receiver must register with the Dispatcher using the
registerContextEngineID abstract service interface. The parameters
used are:
- The contextEngineID is an undefined "wildcard" value.
Notifications are delivered to a registered notification
receiver regardless of the contextEngineID contained in the
notification message.
- The pduType indicates the type of notifications that the
application wishes to receive (for example, SNMPv2-Trap PDUs
or Inform PDUs).
Once the notification receiver has registered with the Dispatcher,
messages are received using the processPdu abstract service
interface. Parameters are:
- The messageProcessingModel indicates which Message Processing
Model received and processed the message.
- The securityModel is the value from the received message.
- The securityName is the value from the received message.
- The securityLevel is the value from the received message.
- The contextEngineID is the value from the received message.
- The contextName is the value from the received message.
- The pduVersion indicates the version of the PDU in the
received message.
- The PDU is the value from the received message.
- The maxSizeResponseScopedPDU is the maximum allowable size of
a ScopedPDU containing a Response PDU (based on the maximum
message size that the originator of the message can accept).
- If the message contains an SNMPv2-Trap PDU, the stateReference
is undefined and unused. Otherwise, the stateReference is a
value which references cached information about the
notification. This value must be returned to the Dispatcher
in order to generate a response.
When an SNMPv2-Trap PDU is delivered to a notification receiver
application, it first extracts the SNMP operation type, request-id,
error-status, error-index, and variable-bindings from the PDU. After
this, processing depends on the particular implementation.
When an Inform PDU is received, the notification receiver application
follows the following procedure:
(1) The SNMPv2 operation type, request-id, error-status, error-index,
and variable-bindings are extracted from the PDU.
(2) A Response PDU is constructed using the extracted request-id and
variable-bindings, and with error-status and error-index both set
to 0.
(3) The Dispatcher is called to generate a response message using the
returnResponsePdu abstract service interface. Parameters are:
- The messageProcessingModel is the value from the processPdu
call.
- The securityModel is the value from the processPdu call.
- The securityName is the value from the processPdu call.
- The securityLevel is the value from the processPdu call.
- The contextEngineID is the value from the processPdu call.
- The contextName is the value from the processPdu call.
- The pduVersion indicates the version of the PDU to be
returned.
- The PDU is the result generated in step (2) above.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the value from the processPdu call.
- The statusInformation indicates that no error occurred and
that a response should be generated.
3.5. Proxy Forwarder Applications
A proxy forwarder application deals with forwarding SNMP messages.
There are four basic types of messages which a proxy forwarder
application may need to forward. These are grouped according to the
PDU type contained in a message, or according to whether a report
indication is contained in the message. The four basic types of
messages are:
- Those containing PDU types which were generated by a command
generator application (for example, Get, GetNext, GetBulk, and
Set PDU types). These deal with requesting or modifying
information located within a particular context.
- Those containing PDU types which were generated by a
notification originator application (for example, SNMPv2-Trap
and Inform PDU types). These deal with notifications
concerning information located within a particular context.
- Those containing a Response PDU type. Forwarding of Response
PDUs always occurs as a result of receiving a response to a
previously forwarded message.
- Those containing a report indication. Forwarding of report
indications always occurs as a result of receiving a report
indication for a previously forwarded message.
For the first type, the proxy forwarder"s role is to deliver a
request for management information to an SNMP engine which is
"closer" or "downstream in the path" to the SNMP engine which has
access to that information, and to deliver the response containing
the information back to the SNMP engine from which the request was
received. The context information in a request is used to determine
which SNMP engine has access to the requested information, and this
is used to determine where and how to forward the request.
For the second type, the proxy forwarder"s role is to determine which
SNMP engines should receive notifications about management
information from a particular location. The context information in a
notification message determines the location to which the information
contained in the notification applies. This is used to determine
which SNMP engines should receive notification about this
information.
For the third type, the proxy forwarder"s role is to determine which
previously forwarded request or notification (if any) the response
matches, and to forward the response back to the initiator of the
request or notification.
For the fourth type, the proxy forwarder"s role is to determine which
previously forwarded request or notification (if any) the report
indication matches, and to forward the report indication back to the
initiator of the request or notification.
When forwarding messages, a proxy forwarder application must perform
a translation of incoming management target information into outgoing
management target information. How this translation is performed is
implementation specific. In many cases, this will be driven by a
preconfigured translation table. If a proxy forwarder application
makes the contents of this table SNMP manageable, it MUST use the
SNMP-PROXY-MIB module defined in this document.
3.5.1. Request Forwarding
There are two phases for request forwarding. First, the incoming
request needs to be passed through the proxy application. Then, the
resulting response needs to be passed back. These phases are
described in the following two sections.
3.5.1.1. Processing an Incoming Request
A proxy forwarder application that wishes to forward request messages
must first register with the Dispatcher using the
registerContextEngineID abstract service interface. The proxy
forwarder must register each contextEngineID for which it wishes to
forward messages, as well as for each pduType. Note that as the
configuration of a proxy forwarder is changed, the particular
contextEngineID values for which it is forwarding may change. The
proxy forwarder should call the registerContextEngineID and
unregisterContextEngineID abstract service interfaces as needed to
reflect its current configuration.
A proxy forwarder application should never attempt to register a
value of contextEngineID which is equal to the snmpEngineID of the
SNMP engine to which the proxy forwarder is associated.
Once the proxy forwarder has registered for the appropriate
contextEngineId values, it can start processing messages. The
following procedure is used:
(1) A message is received using the processPdu abstract service
interface. The incoming management target information received
from the processPdu interface is translated into outgoing
management target information. Note that this translation may vary
for different values of contextEngineID and/or contextName. The
translation should result in a single management target.
(2) If appropriate outgoing management target information cannot be
found, the proxy forwarder increments the snmpProxyDrops counter
[RFC1907], and then calls the Dispatcher using the
returnResponsePdu abstract service interface. Parameters are:
- The messageProcessingModel is the value from the processPdu
call.
- The securityModel is the value from the processPdu call.
- The securityName is the value from the processPdu call.
- The securityLevel is the value from the processPdu call.
- The contextEngineID is the value from the processPdu call.
- The contextName is the value from the processPdu call.
- The pduVersion is the value from the processPdu call.
- The PDU is an undefined value.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the value from the processPdu call.
- The statusInformation indicates that an error occurred and
includes the OID and value of the snmpProxyDrops object.
Processing of the message stops at this point. Otherwise,
(3) A new PDU is constructed. A unique value of request-id should be
used in the new PDU (this value will enable a subsequent response
message to be correlated with this request). The remainder of the
new PDU is identical to the received PDU, unless the incoming SNMP
version is SNMPv2 or SNMPv3 and the outgoing SNMP version is
SNMPv1, in which case the proxy forwarder must apply the
translation rules as documented in [RFC1908].
(4) The proxy forwarder calls the Dispatcher to generate the forwarded
message, using the sendPdu abstract service interface. The
parameters are:
- The transportDomain is that of the outgoing management target.
- The transportAddress is that of the outgoing management
target.
- The messageProcessingModel is that of the outgoing management
target.
- The securityModel is that of the outgoing management target.
- The securityName is that of the outgoing management target.
- The securityLevel is that of the outgoing management target.
- The contextEngineID is the value originally received.
- The contextName is the value originally received.
- The pduVersion is the version of the PDU to be sent.
- The PDU is the value constructed in step (3) above.
- The expectResponse argument indicates that a response is
expected. If the sendPdu call is unsuccessful, the proxy
forwarder performs the steps described in (2) above.
Otherwise:
(5) The proxy forwarder caches the following information in order to
match an incoming response to the forwarded request:
- The sendPduHandle returned from the call to sendPdu,
- The request-id from the received PDU.
- the contextEngineID,
- the contextName,
- the stateReference,
- the incoming management target information,
- the outgoing management information,
- any other information needed to match an incoming response to
the forwarded request.
If this information cannot be cached (possibly due to a lack of
resources), the proxy forwarder performs the steps described in (2)
above. Otherwise:
(6) Processing of the request stops until a response to the forwarded
request is received, or until an appropriate time interval has
expired. If this time interval expires before a response has been
received, the cached information about this request is removed.
3.5.1.2. Processing an Incoming Response
A proxy forwarder follows the following procedure when an incoming
response is received:
(1) The incoming response is received using the processResponsePdu
interface. The proxy forwarder uses the received parameters to
locate an entry in its cache of pending forwarded requests. This
is done by matching the received parameters with the cached values
of sendPduHandle, contextEngineID, contextName, outgoing management
target information, and the request-id contained in the received
PDU (the proxy forwarder must extract the request-id for this
purpose). If an appropriate cache entry cannot be found,
processing of the response is halted. Otherwise:
(2) The cache information is extracted, and removed from the cache.
(3) A new Response PDU is constructed, using the request-id value from
the original forwarded request (as extracted from the cache). All
other values are identical to those in the received Response PDU.
(4) If the incoming SNMP version is SNMPv1 and the outgoing SNMP
version is SNMPv2 or SNMPv3, the proxy forwarder must apply the
translation rules documented in [RFC1908].
(5) The proxy forwarder calls the Dispatcher using the
returnResponsePdu abstract service interface. Parameters are:
- The messageProcessingModel indicates the Message Processing
Model by which the original incoming message was processed.
- The securityModel is that of the original incoming management
target extracted from the cache.
- The securityName is that of the original incoming management
target extracted from the cache.
- The securityLevel is that of the original incoming management
target extracted from the cache.
- The contextEngineID is the value extracted from the cache.
- The contextName is the value extracted from the cache.
- The pduVersion indicates the version of the PDU to be
returned.
- The PDU is the (possibly translated) Response PDU.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the value extracted from the cache.
- The statusInformation indicates that no error occurred and
that a Response PDU message should be generated.
3.5.1.3. Processing an Incoming Report Indication
A proxy forwarder follows the following procedure when an incoming
report indication is received:
(1) The incoming report indication is received using the
processResponsePdu interface. The proxy forwarder uses the
received parameters to locate an entry in its cache of pending
forwarded requests. This is done by matching the received
parameters with the cached values of sendPduHandle. If an
appropriate cache entry cannot be found, processing of the report
indication is halted. Otherwise:
(2) The cache information is extracted, and removed from the cache.
(3) If the original incoming management target information indicates
SNMPv1, processing of the report indication is halted.
(4) The proxy forwarder calls the Dispatcher using the
returnResponsePdu abstract service interface. Parameters are:
- The messageProcessingModel indicates the Message Processing
Model by which the original incoming message was processed.
- The securityModel is that of the original incoming management
target extracted from the cache.
- The securityName is that of the original incoming management
target extracted from the cache.
- The securityLevel is that of the original incoming management
target extracted from the cache.
- The contextEngineID is the value extracted from the cache.
- The contextName is the value extracted from the cache.
- The pduVersion indicates the version of the PDU to be
returned.
- The PDU is unused.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the value extracted from the cache.
- The statusInformation contain the contextEngineID,
contextName, counter OID, and counter value received in the
report indication.
3.5.2. Notification Forwarding
A proxy forwarder receives notifications in the same manner as a
notification receiver application, using the processPdu abstract
service interface. The following procedure is used when a
notification is received:
(1) The incoming management target information received from the
processPdu interface is translated into outgoing management target
information. Note that this translation may vary for different
values of contextEngineId and/or contextName. The translation may
result in multiple management targets.
(2) If appropriate outgoing management target information cannot be
found and the notification was a Trap, processing of the
notification is halted. If appropriate outgoing management target
information cannot be found and the notification was an Inform, the
proxy forwarder increments the snmpProxyDrops object, and calls the
Dispatcher using the returnResponsePdu abstract service interface.
The parameters are:
- The messageProcessingModel is the received value.
- The securityModel is the received value.
- The securityName is the received value.
- The securityLevel is the received value.
- The contextEngineID is the received value.
- The contextName is the received value.
- The pduVersion is the received value.
- The PDU is an undefined and unused value.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the received value.
- The statusInformation indicates that an error occurred and
that a Report message should be generated.
Processing of the message stops at this point. Otherwise,
(3) The proxy forwarder generates a notification using the procedures
described in the preceding section on Notification Originators,
with the following exceptions:
- The contextEngineID and contextName values from the original
received notification are used.
- The outgoing management targets previously determined are
used.
- No filtering mechanisms are applied.
- The variable-bindings from the original received notification
are used, rather than retrieving variable-bindings from local
MIB instrumentation. In particular, no access-control is
applied to these variable-bindings.
- If for any of the outgoing management targets, the incoming
SNMP version is SNMPv1 and the outgoing SNMP version is SNMPv2
or SNMPv3, the proxy forwarder must apply the translation
rules as documented in [RFC1908].
- If for any of the outgoing management targets, the incoming
SNMP version is SNMPv2 or SNMPv3, and the outgoing SNMP
version is SNMPv1, this outgoing management target is not used
when generating the forwarded notifications.
(4) If the original received notification contains an SNMPv2-Trap PDU,
processing of the notification is now completed. Otherwise, the
original received notification must contain an Inform PDU, and
processing continues.
(5) If the forwarded notifications included any Inform PDUs, processing
continues when the procedures described in the section for
Notification Originators determine that either:
- None of the generated notifications containing Inform PDUs
have been successfully acknowledged within the longest of the
time intervals, in which case processing of the original
notification is halted, or,
- At least one of the generated notifications containing Inform
PDUs is successfully acknowledged, in which case a response to
the original received notification containing an Inform PDU is
generated as described in the following steps.
(6) A Response PDU is constructed, using the values of request-id and
variable-bindings from the original received Inform PDU, and
error-status and error-index values of 0.
(7) The Dispatcher is called using the returnResponsePdu abstract
service interface. Parameters are:
- The messageProcessingModel is the originally received value.
- The securityModel is the originally received value.
- The securityName is the originally received value.
- The securityLevel is the originally received value.
- The contextEngineID is the originally received value.
- The contextName is the originally received value.
- The pduVersion indicates the version of the PDU constructed in
step (6) above.
- The PDU is the value constructed in step (6) above.
- The maxSizeResponseScopedPDU is a local value indicating the
maximum size of a ScopedPDU that the application can accept.
- The stateReference is the originally received value.
- The statusInformation indicates that no error occurred and
that a Response PDU message should be generated.
4. The Structure of the MIB Modules
There are three separate MIB modules described in this document, the
management target MIB, the notification MIB, and the proxy MIB. The
following sections describe the structure of these three MIB modules.
The use of these MIBs by particular types of applications is
described later in this document:
- The use of the management target MIB and the notification MIB
in notification originator applications is described in
section 6.
- The use of the notification MIB for filtering notifications in
notification originator applications is described in section
7.
- The use of the management target MIB and the proxy MIB in
proxy forwarding applications is described in section 8.
4.1. The Management Target MIB Module
The SNMP-TARGET-MIB module contains objects for defining management
targets. It consists of two tables and conformance/compliance
statements.
The first table, the snmpTargetAddrTable, contains information about
transport domains and addresses. It also contains an object,
snmpTargetAddrTagList, which provides a mechanism for grouping
entries.
The second table, the snmpTargetParamsTable, contains information
about SNMP version and security information to be used when sending
messages to particular transport domains and addresses.
4.1.1. Tag Lists
The snmpTargetAddrTagList object is used for grouping entries in the
snmpTargetAddrTable. The value of this object contains a list of tag
values which are used to select target addresses to be used for a
particular operation.
A tag value, which may also be used in MIB objects other than
snmpTargetAddrTagList, is an arbitrary string of octets, but may not
contain a delimiter character. Delimiter characters are defined to
be one of the following characters:
- An ASCII space character (0x20).
- An ASCII TAB character (0x09).
- An ASCII carriage return (CR) character (0x0D).
- An ASCII line feed (LF) character (0x0B).
In addition, a tag value may not have a zero length. Generally, a
particular MIB object may contain either
- a single tag value, in which case the value of the MIB object
may not contain a delimiter character, or:
- a MIB object may contain a list of tag values, separated by
single delimiter characters.
For a list of tag values, these constraints imply certain
restrictions on the value of a MIB object:
- There cannot be a leading or trailing delimiter character.
- There cannot be multiple adjacent delimiter charaters.
4.1.2. Definitions
SNMP-TARGET-MIB DEFINITIONS ::= BEGIN
IMPORTS
TEXTUAL-CONVENTION,
MODULE-IDENTITY,
OBJECT-TYPE,
snmpModules,
Integer32
FROM SNMPv2-SMI
TDomain,
TAddress,
TimeInterval,
RowStatus,
StorageType,
TestAndIncr
FROM SNMPv2-TC
SnmpSecurityModel,
SnmpMessageProcessingModel,
SnmpSecurityLevel,
SnmpAdminString
FROM SNMP-FRAMEWORK-MIB
OBJECT-GROUP
FROM SNMPv2-CONF;
snmpTargetMIB MODULE-IDENTITY
LAST-UPDATED "9711210000Z"
ORGANIZATION "IETF SNMPv3 Working Group"
CONTACT-INFO
"WG-email: snmpv3@tis.com
Subscribe: majordomo@tis.com
In message body: subscribe snmpv3
Chair: Russ Mundy
Trusted Information Systems
Postal: 3060 Washington Rd
Glenwood MD 21738
USA
Email: mundy@tis.com
Phone: +1-301-854-6889
Co-editor: David B. Levi
SNMP Research, Inc.
Postal: 3001 Kimberlin Heights Road
Knoxville, TN 37920-9716
E-mail: levi@snmp.com
Phone: +1 423 573 1434
Co-editor: Paul Meyer
Secure Computing Corporation
Postal: 2675 Long Lake Road
Roseville, MN 55113
E-mail: paul_meyer@securecomputing.com
Phone: +1 612 628 1592
Co-editor: Bob Stewart
Cisco Systems, Inc.
Postal: 170 West Tasman Drive
San Jose, CA 95134-1706
E-mail: bstewart@cisco.com
Phone: +1 603 654 6923"
DESCRIPTION
"This MIB module defines MIB objects which provide
mechanisms to remotely configure the parameters used
by an SNMP entity for the generation of SNMP messages."
REVISION "9707140000Z"
DESCRIPTION
"The initial revision."
::= { snmpModules 7 }
snmpTargetObjects OBJECT IDENTIFIER ::= { snmpTargetMIB 1 }
snmpTargetConformance OBJECT IDENTIFIER ::= { snmpTargetMIB 3 }
SnmpTagValue ::= TEXTUAL-CONVENTION
DISPLAY-HINT "255a"
STATUS current
DESCRIPTION
"An octet string containing a tag value.
Tag values are preferably in human-readable form.
To facilitate internationalization, this information
is represented using the ISO/IEC IS 10646-1 character
set, encoded as an octet string using the UTF-8
character encoding scheme described in RFC2044.
Since additional code points are added by amendments
to the 10646 standard from time to time,
implementations must be prepared to encounter any code
point from 0x00000000 to 0x7fffffff.
The use of control codes should be avoided, and certain
control codes are not allowed as described below.
For code points not directly supported by user
interface hardware or software, an alternative means
of entry and display, such as hexadecimal, may be
provided.
For information encoded in 7-bit US-ASCII, the UTF-8
representation is identical to the US-ASCII encoding.
Note that when this TC is used for an object that
is used or envisioned to be used as an index, then a
SIZE restriction must be specified so that the number
sub-identifiers for any object instance do not exceed
the limit of 128, as defined by [RFC1905].
An object of this type contains a single tag value
which is used to select a set of entries in a table.
A tag value is an arbitrary string of octets, but
may not contain a delimiter character. Delimiter
characters are defined to be one of the following:
- An ASCII space character (0x20).
- An ASCII TAB character (0x09).
- An ASCII carriage return (CR) character (0x0D).
- An ASCII line feed (LF) character (0x0B).
Delimiter characters are used to separate tag values
in a tag list. An object of this type may only
contain a single tag value, and so delimiter
characters are not allowed in a value of this type.
Some examples of valid tag values are:
- "acme"
- "router"
- "host"
The use of a tag value to select table entries is
application and MIB specific."
SYNTAX OCTET STRING (SIZE (0..255))
SnmpTagList ::= TEXTUAL-CONVENTION
DISPLAY-HINT "255a"
STATUS current
DESCRIPTION
"An octet string containing a list of tag values.
Tag values are preferably in human-readable form.
To facilitate internationalization, this information
is represented using the ISO/IEC IS 10646-1 character
set, encoded as an octet string using the UTF-8
character encoding scheme described in RFC2044.
Since additional code points are added by amendments
to the 10646 standard from time to time,
implementations must be prepared to encounter any code
point from 0x00000000 to 0x7fffffff.
The use of control codes should be avoided, except as
described below.
For code points not directly supported by user
interface hardware or software, an alternative means
of entry and display, such as hexadecimal, may be
provided.
For information encoded in 7-bit US-ASCII, the UTF-8
representation is identical to the US-ASCII encoding.
An object of this type contains a list of tag values
which are used to select a set of entries in a table.
A tag value is an arbitrary string of octets, but
may not contain a delimiter character. Delimiter
characters are defined to be one of the following:
- An ASCII space character (0x20).
- An ASCII TAB character (0x09).
- An ASCII carriage return (CR) character (0x0D).
- An ASCII line feed (LF) character (0x0B).
Delimiter characters are used to separate tag values
in a tag list. Only a single delimiter character may
occur between two tag values. A tag value may not
have a zero length. These constraints imply certain
restrictions on the contents of this object:
- There cannot be a leading or trailing delimiter
character.
- There cannot be multiple adjacent delimiter
characters.
Some examples of valid tag lists are:
- An empty string
- "acme router"
- "host managerStation"
Note that although a tag value may not have a length of
zero, an empty string is still valid. This indicates
an empty list (i.e. there are no tag values in the list).
The use of the tag list to select table entries is
application and MIB specific. Typically, an application
will provide one or more tag values, and any entry
which contains some combination of these tag values
will be selected."
SYNTAX OCTET STRING (SIZE (0..255))
--
--
-- The snmpTargetObjects group
--
--
snmpTargetSpinLock OBJECT-TYPE
SYNTAX TestAndIncr
MAX-ACCESS read-write
STATUS current
DESCRIPTION
"This object is used to facilitate modification of table
entries in the SNMP-TARGET-MIB module by multiple
managers. In particular, it is useful when modifying
the value of the snmpTargetAddrTagList object.
The procedure for modifying the snmpTargetAddrTagList
object is as follows:
1. Retrieve the value of snmpTargetSpinLock and
of snmpTargetAddrTagList.
2. Generate a new value for snmpTargetAddrTagList.
3. Set the value of snmpTargetSpinLock to the
retrieved value, and the value of
snmpTargetAddrTagList to the new value. If
the set fails for the snmpTargetSpinLock
object, go back to step 1."
::= { snmpTargetObjects 1 }
snmpTargetAddrTable OBJECT-TYPE
SYNTAX SEQUENCE OF SnmpTargetAddrEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A table of transport addresses to be used in the generation
of SNMP messages."
::= { snmpTargetObjects 2 }
snmpTargetAddrEntry OBJECT-TYPE
SYNTAX SnmpTargetAddrEntry
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"A transport address to be used in the generation
of SNMP operations.
Entries in the snmpTargetAddrTable are created and
deleted using the snmpTargetAddrRowStatus object."
INDEX { IMPLIED snmpTargetAddrName }
::= { snmpTargetAddrTable 1 }
SnmpTargetAddrEntry ::= SEQUENCE {
snmpTargetAddrName SnmpAdminString,
snmpTargetAddrTDomain TDomain,
snmpTargetAddrTAddress TAddress,
snmpTargetAddrTimeout TimeInterval,
snmpTargetAddrRetryCount Integer32,
snmpTargetAddrTagList SnmpTagList,
snmpTargetAddrParams SnmpAdminString,
snmpTargetAddrStorageType StorageType,
snmpTargetAddrRowStatus RowStatus
}
snmpTargetAddrName OBJECT-TYPE
SYNTAX SnmpAdminString (SIZE(1..32))
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"T