entry and sends in reply the agentx-Response-PDU, with res.error
set to `noError'.
7.1.9. Processing the agentx-Close-PDU
When the master agent receives an agentx-Close-PDU, it processes it
as follows:
1) An agentx-Response-PDU is created and res.sysUpTime is set to
the value of sysUpTime.0 for the default context.
2) If h.sessionID does not correspond to a currently
established session with this subagent, the agentx-Response-PDU is
sent in reply with res.error set to `notOpen'.
3) Otherwise, the master agent closes the AgentX session
as described below. No agentx-Response-PDU is sent.
- All MIB regions that have been registered during this session
are unregistered, as described in 7.1.6.
- All index values allocated during this session are freed, as
described in section 7.1.4.
- All sysORID values that were registered during this session
are removed, as described in section 7.1.8.
The master agent does not maintain state for closed sessions. If a
subagent wishes to re-establish a session after receiving an agentx-
Close-PDU, it needs to re-register MIB regions, agent capabilities,
etc.
7.1.10. Detecting Connection Loss
If a master agent is able to detect (from the underlying transport)
that a subagent cannot receive AgentX PDUs, it should close all
affected AgentX sessions as described in 7.1.9, step 3).
7.1.11. Processing the agentx-Notify-PDU
A subagent sending SNMPv1 trap information must map this into
(minimally) a value of snmpTrapOID.0, as described in 3.1.2 of RFC
1908 [8].
The master agent processes the agentx-Notify-PDU as follows:
1) If h.sessionID does not correspond to a currently
established session with this subagent, an agentx-Response-PDU
is sent in reply with res.error set to `notOpen', and
res.sysUpTime set to the value of sysUpTime.0 for the indicated
context.
2) The VarBindList is parsed. If it does not contain a value for
sysUpTime.0, the master agent supplies the current value of
sysUpTime.0 for the indicated context. If the next VarBind
(either the first or second VarBind; see section 6.2.10.1) is
not snmpTrapOID.0, the master agent ceases further processing
of the notification.
3) Notifications are sent according to the implementation-specific
configuration of the master agent.
If SNMPv1 Trap PDUs are generated, the recommended mapping is
as described in RFC2089 [9].
Except in the case of a `notOpen' error as described in (1)
above, no agentx-Response-PDU is sent to the subagent when the
master agent finishes processing the notification.
7.1.12. Processing the agentx-Ping-PDU
When the master agent receives an agentx-Ping-PDU, it processes it as
follows:
1) An agentx-Response-PDU is created and res.sysUpTime is set to
the value of sysUpTime.0 for the default context.
2) If h.sessionID does not correspond to a currently
established session with this subagent, the agentx-Response-PDU is
sent in reply with res.error set to `notOpen'.
3) If the NON_DEFAULT_CONTEXT bit is set, and the master agent
supports only a default context, the agentx-Response-PDU is
returned with res.error set to `unsupportedContext'. Otherwise:
The value of res.sysUpTime is set to the value of sysUpTime.0 for
the indicated context.
4) The agentx-Response-PDU is sent, with res.error set to
`noError'.
If a subagent does not receive a response to its pings, or if it is
able to detect (from the underlying transport) that the master agent
is not able to receive AgentX messages, then it eventually must
initiate a new AgentX session, re-register its regions, etc.
7.2. Processing Received SNMP Protocol Messages
When an SNMP GetRequest, GetNextRequest, GetBulkRequest, or
SetRequest protocol message is received by the master agent, the
master agent applies its access control policy.
In particular, for SNMPv1 or SNMPv2c PDUs, the master agent applies
the Elements of Procedure defined in section 4.1 of RFC1157 [6] that
apply to receiving entities. (For other versions of SNMP, the master
agent applies the access control policy defined in the Elements of
Procedure for those versions.)
In the SNMPv1 or v2c frameworks, the master agent uses the community
string as an index into a local repository of configuration
information that may include community profiles or more complex
context information.
If application of the access control policy results in a valid SNMP
request PDU, then an SNMP Response-PDU is constructed from
information gathered in the exchange of AgentX PDUs between the
master agent and one or more subagents. Upon receipt and initial
validation of an SNMP request PDU, a master agent uses the procedures
described below to dispatch AgentX PDUs to the proper subagents,
marshal the subagent responses, and construct an SNMP response PDU.
7.2.1. Dispatching AgentX PDUs
Upon receipt and initial validation of an SNMP request PDU, a master
agent uses the procedures described below to dispatch AgentX PDUs to
the proper subagents.
Note: In the following procedures, an object identifier is said to be
"contained" within an OID range when both of the following are true:
- The object identifier does not lexicographically precede
the range.
- The object identifier lexicographically precedes the end
of the range.
General Rules of Procedure
While processing a particular SNMP request, the master agent may send
one or more AgentX PDUs to one or more subagents. The following
rules of procedure apply in general to the AgentX master agent. PDU-
specific rules are listed in the applicable sections.
1) Honoring the registry
Because AgentX supports overlapping registrations, it is possible
for the master agent to obtain a value for a requested varbind
from within multiple registered MIB regions.
The master agent must ensure that the value (or exception)
actually returned in the SNMP response PDU is taken from the
authoritative region (as defined in section 7.1.5.1).
2) GetNext and GetBulk Processing
The master agent may choose to send agentx-Get-PDUs while
servicing an SNMP GetNextRequest-PDU. The master agent may choose
to send agentx-Get-PDUs or agentx-GetNext-PDUs while servicing an
SNMP GetBulkRequest-PDU. One possible reason for this would be if
the current iteration has targeted instance-level registrations.
The master agent may choose to "scope" the possible instances
returned by a subagent by specifying an ending OID in the
SearchRange. If such scoping is used, typically the ending OID
would be the first lexicographical successor to the target OID
range that was registered by a subagent other than the target
subagent. Regardless of this choice, rule (1) must be obeyed.
The master agent may require multiple request-response iterations
on the same subagent session, to determine the final value of all
requested variables.
All AgentX PDUs sent on the session while processing a given SNMP
request must contain identical values of transactionID. Each
different SNMP request processed by the master agent must present
a unique value of transactionID (within the limits of the 32-bit
field) to the session.
3) Number and order of variables sent per AgentX PDU
For Get/GetNext/GetBulk operations, at any stage of the possibly
iterative process, the master agent may need to dispatch several
SearchRanges to a particular subagent session. The master agent
may send one, some, or all of the SearchRanges in a single AgentX
PDU.
The master agent must ensure that the correct contents and
ordering of the VarBindList in the SNMP Response-PDU are
maintained.
The following rules govern the number of VarBinds in a given
AgentX PDU:
a) The subagent must support processing of AgentX PDUs
with multiple VarBinds.
b) When processing an SNMP Set request, the master agent
must send all of the VarBinds applicable to a particular
subagent session in a single Test/Set transaction.
c) When processing an SNMP Get, GetNext, or GetBulk request,
the master agent may send a single AgentX PDU to the
subagent with all applicable VarBinds, or multiple PDUs with
single VarBinds, or something in between those extremes. The
determination of which method to use in a particular case is
implementation-specific.
4) Timeout Values
The master agent chooses a timeout value for each MIB region being
queried, which is
a) the value specified during registration of the MIB region,
if it was non-zero
b) otherwise, the value specified during establishment of
the session in which this region was subsequently
registered, if that value was non-zero.
c) otherwise, the master agent's default value
When an AgentX PDU that references multiple MIB regions is
dispatched, the timeout value used for the PDU is the maximum
value of the timeouts so determined for each of the referenced MIB
regions.
5) Context
If the master agent has determined that a specific non-default
context is associated with the SNMP request PDU, that context is
encoded into the AgentX PDU's context field and the
NON_DEFAULT_CONTEXT bit is set in h.flags.
Otherwise, no context Octet String is added to the PDU, and the
NON_DEFAULT_CONTEXT bit is cleared.
7.2.1.1. agentx-Get-PDU
Each variable binding in the SNMP request PDU is processed as
follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for
the indicated context, locate the authoritative region that
contains the binding's name.
(2) If no such OID range exists, the variable binding is not
processed further, and its value is set to `noSuchObject'.
(3) Identify the subagent session in which this region was
registered, termed the target session.
(4) If this is the first variable binding to be dispatched over
the target session in a request-response exchange entailed in the
processing of this management request:
- Create an agentx-Get-PDU for this session, with the header
fields initialized as described above (see 6.1 AgentX PDU
Header).
(5) Add a SearchRange to the end of the target session's PDU
for this variable binding.
- The variable binding's name is encoded into the starting OID.
- The ending OID is encoded as null.
7.2.1.2. agentx-GetNext-PDU
Each variable binding in the SNMP request PDU is processed as
follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for
the indicated context, locate
a) the authoritative OID range that contains the variable
binding's name and is not a fully qualified instance, or
b) the authoritative OID range that is the first
lexicographical successor to the variable binding's name.
(2) If no such OID range exists, the variable binding is not
processed further, and its value is set to `endOfMibView'.
(3) Identify the subagent session in which this region was
registered, termed the target session.
(4) If this is the first variable binding to be dispatched over the
target session in a request-response exchange entailed in the
processing of this management request:
- Create an agentx-GetNext-PDU for the session, with
the header fields initialized as described above (see 6.1
AgentX PDU Header).
(5) Add a SearchRange to the end of the target session's
agentx-GetNext-PDU for this variable binding.
- if (1a) applies, the variable binding's name is encoded
into the starting OID, and the OID's "include" field is set to
0.
- if (1b) applies, the target OID is encoded into the starting
OID, and its "include" field is set to 1.
7.2.1.3. agentx-GetBulk-PDU
(Note: The outline of the following procedure is based closely on
section 4.2.3, "The GetBulkRequest-PDU" of RFC1905 [4]. Please
refer to it for details on the format of the SNMP GetBulkRequest-PDU
itself.)
Each variable binding in the request PDU is processed as follows:
(1) Identify the authoritative target OID range and target session,
exactly as described for the agentx-GetNext-PDU (see 7.2.1.2).
(2) If this is the first variable binding to be dispatched over the
target session in a request-response exchange entailed in the
processing of this management request:
- Create an agentx-GetBulk-PDU for the session, with
the header fields initialized as described above (see 6.1
AgentX PDU Header).
(3) Add a SearchRange to the end of the target session's
agentx-GetBulk-PDU for this variable binding, as described for
the agentx-GetNext-PDU. If the variable binding was a non-
repeater in the original request PDU, it must be a non-repeater
in the agentx-GetBulk-PDU.
The value of g.max_repetitions in the agentx-GetBulk-PDU may be less
than (but not greater than) the value in the original request PDU.
The master agent may make such alterations due to simple sanity
checking, optimizations for the current iteration based on the
registry, the maximum possible size of a potential Response-PDU,
known constraints of the AgentX transport, or any other
implementation-specific constraint.
7.2.1.4. agentx-TestSet-PDU
AgentX employs test-commit-undo-cleanup phases to achieve "as if
simultaneous" semantics of the SNMP SetRequest-PDU within the
extensible agent. The initial phase involves the agentx-TestSet-PDU.
Each variable binding in the SNMP request PDU is processed in order,
as follows:
(1) Identify the target OID range.
Within a lexicographically ordered set of OID ranges, valid for
the indicated context, locate the authoritative range that
contains the variable binding's name.
(2) If no such OID range exists, this variable binding fails with an
error of `notWritable'. Processing is complete for this request.
(3) Identify the single subagent responsible for this OID range,
termed the target subagent, and the applicable session, termed
the target session.
(4) If this is the first variable binding to be dispatched over
the target session in a request-response exchange entailed in the
processing of this management request:
- create an agentx-TestSet-PDU for the session, with the
header fields initialized as described above (see 6.1 AgentX
PDU Header).
(5) Add a VarBind to the end of the target session's PDU
for this variable binding, as described in section 5.4.
Note that all VarBinds applicable to a given session must be sent in
a single agentx-TestSet-PDU.
7.2.1.5. Dispatch
A timeout value is calculated for each PDU to be sent, which is the
maximum value of the timeouts determined for each of the PDU's
SearchRanges (as described above in 7.2.1 Dispatching AgentX PDUs,
item 4). Each pending PDU is mapped (via its h.sessionID value) to a
particular transport domain/endpoint, as described in section 8
(Transport Mappings).
7.2.2. Subagent Processing of agentx-Get, GetNext, GetBulk-PDUs
A conformant AgentX subagent must support the agentx-Get, -GetNext,
and -GetBulk PDUs, and must support multiple variables being supplied
in each PDU.
When a subagent receives an agentx-Get-, GetNext-, or GetBulk-PDU, it
performs the indicated management operations and returns an agentx-
Response-PDU.
The agentx-Response-PDU header fields are identical to the received
request PDU except that, at the start of processing, the subagent
initializes h.type to Response, res.error to `noError', res.index to
0, and the VarBindList to null.
Each SearchRange in the request PDU's SearchRangeList is processed as
described below, and a VarBind is added in the corresponding location
of the agentx-Response-PDU's VarbindList. If processing should fail
for any reason not described below, res.error is set to `genErr',
res.index to the index of the failed SearchRange, the VarBindList is
reset to null, and this agentx-Response-PDU is returned to the master
agent.
7.2.2.1. Subagent Processing of the agentx-Get-PDU
Upon the subagent's receipt of an agentx-Get-PDU, each SearchRange in
the request is processed as follows:
(1) The starting OID is copied to v.name.
(2) If the starting OID exactly matches the name of a
variable instantiated by this subagent within the indicated
context and session, v.type and v.data are encoded to represent
the variable's syntax and value, as described in section 5.4,
Value Representation.
(3) Otherwise, if the starting OID does not match the object
identifier prefix of any variable instantiated within the
indicated context and session, the VarBind is set to
`noSuchObject', in the manner described in section 5.4, Value
Representation.
(4) Otherwise, the VarBind is set to `noSuchInstance'
in the manner described in section 5.4, Value Representation.
7.2.2.2. Subagent Processing of the agentx-GetNext-PDU
Upon the subagent's receipt of an agentx-GetNext-PDU, each
SearchRange in the request is processed as follows:
(1) The subagent searches for a variable within the
lexicographically ordered list of variable names for all
variables it instantiates (without regard to registration of
regions) within the indicated context and session, for which the
following are all true:
- if the "include" field of the starting OID is 0, the
variable's name is the closest lexicographical successor to the
starting OID.
- if the "include" field of the starting OID is 1, the
variable's name is either equal to, or the closest
lexicographical successor to, the starting OID.
- If the ending OID is not null, the variable's name
lexicographically precedes the ending OID.
If all of these conditions are met, v.name is set to the located
variable's name. v.type and v.data are encoded to represent the
variable's syntax and value, as described in section 5.4, Value
Representation.
(2) If no such variable exists, v.name is set to the starting OID,
and the VarBind is set to `endOfMibView', in the manner described
in section 5.4, Value Representation.
7.2.2.3. Subagent Processing of the agentx-GetBulk-PDU
A maximum of N + (M * R) VarBinds are returned, where
N equals g.non_repeaters,
M equals g.max_repetitions, and
R is (number of SearchRanges in the GetBulk request) - N.
The first N SearchRanges are processed exactly as for the agentx-
GetNext-PDU.
If M and R are both non-zero, the remaining R SearchRanges are
processed iteratively to produce potentially many VarBinds. For each
iteration i, such that i is greater than zero and less than or equal
to M, and for each repeated SearchRange s, such that s is greater
than zero and less than or equal to R, the (N+((i-1)*R)+s)-th VarBind
is added to the agentx-Response-PDU as follows:
1) The subagent searches for a variable within the
lexicographically ordered list of variable names for all
variables it instantiates (without regard to registration of
regions) within the indicated context and session, for which
the following are all true:
- The variable's name is the (i)-th lexicographical successor
to the (N+s)-th requested OID.
(Note that if i is 0 and the "include" field is 1, the
variable's name may be equivalent to, or the first
lexicographical successor to, the (N+s)-th requested OID.)
- If the ending OID is not null, the variable's name
lexicographically precedes the ending OID.
If all of these conditions are met, v.name is set to the
located variable's name. v.type and v.data are encoded to
represent the variable's syntax and value, as described in
section 5.4, Value Representation.
2) If no such variable exists, the VarBind is set to
`endOfMibView' as described in section 5.4, Value
Representation. v.name is set to v.name of the (N+((i-
2)*R)+s)-th VarBind unless i is currently 1, in which case it
is set to the value of the starting OID in the (N+s)-th
SearchRange.
Note that further iterative processing should stop if
- For any iteration i, all s values of v.type are
`endOfMibView'.
- An AgentX transport constraint or other
implementation-specific constraint is reached.
7.2.3. Subagent Processing of agentx-TestSet, -CommitSet, -UndoSet,
-CleanupSet-PDUs
A conformant AgentX subagent must support the agentx-TestSet,
-CommitSet, -UndoSet, and -CleanupSet PDUs, and must support multiple
variables being supplied in each PDU.
These four PDUs are used to collectively perform the indicated
management operation. An agentx-Response-PDU is sent in reply to
each of the PDUs, to inform the master agent of the state of the
operation.
The agentx-Response-PDU header fields are identical to the received
request PDU except that, at the start of processing, the subagent
initializes h.type to Response, res.error to `noError', and res.index
to 0.
These Response-PDUs do not contain a VarBindList.
7.2.3.1. Subagent Processing of the agentx-TestSet-PDU
Upon the subagent's receipt of an agentx-TestSet-PDU, each VarBind in
the PDU is validated until they are all successful, or until one
fails, as described in section 4.2.5 of RFC1905 [4]. The subagent
validates variables with respect to the context and session indicated
in the testSet-PDU.
If each VarBind is successful, the subagent has a further
responsibility to ensure the availability of all resources (memory,
write access, etc.) required for successfully carrying out a
subsequent agentx-CommitSet operation. If this cannot be guaranteed,
the subagent should set res.error to `resourceUnavailable'.
As a result of this validation step, an agentx-Response-PDU is sent
in reply whose res.error field is set to one of the following (SNMPv2
SMI) values:
noError (0),
genErr (5),
noAccess (6),
wrongType (7),
wrongLength (8),
wrongEncoding (9),
wrongValue (10),
noCreation (11),
inconsistentValue (12),
resourceUnavailable (13),
notWritable (17),
inconsistentName (18)
If this value is not `noError', the res.index field must be set to
the index of the VarBind for which validation failed.
Implementation of rigorous validation code may be one of the most
demanding aspects of subagent development. Implementors are strongly
encouraged to do this right, so as to avoid if at all possible the
extensible agent's having to return `commitFailed' or `undoFailed'
during subsequent processing.
7.2.3.2. Subagent Processing of the agentx-CommitSet-PDU
The agentx-CommitSet-PDU indicates that the subagent should actually
perform (as described in the post-validation sections of 4.2.5 of RFC
1905 [4]) the management operation indicated by the previous
TestSet-PDU. After carrying out the management operation, the
subagent sends in reply an agentx-Response-PDU whose res.error field
is set to one of the following (SNMPv2 SMI) values:
noError (0),
commitFailed (14)
If this value is `commitFailed', the res.index field must be set to
the index of the VarBind for which the operation failed. Otherwise
res.index is set to 0.
7.2.3.3. Subagent Processing of the agentx-UndoSet-PDU
The agentx-UndoSet-PDU indicates that the subagent should undo the
management operation requested in a preceding CommitSet-PDU. The
undo process is as described in section 4.2.5 of RFC1905 [4].
After carrying out the undo process, the subagent sends in reply an
agentx-Response-PDU whose res.index field is set to 0, and whose
res.error field is set to one of the following (SNMPv2 SMI) values:
noError (0),
undoFailed (15)
If this value is `undoFailed', the res.index field must be set to the
index of the VarBind for which the operation failed. Otherwise
res.index is set to 0.
This PDU also signals the end of processing of the management
operation initiated by the previous TestSet-PDU. The subagent should
release resources, etc. as described in section 7.2.3.4.
7.2.3.4. Subagent Processing of the agentx-CleanupSet-PDU
The agentx-CleanupSet-PDU signals the end of processing of the
management operation requested in the previous TestSet-PDU. This is
an indication to the subagent that it may now release any resources
it may have reserved in order to carry out the management request.
No response is sent by the subagent.
7.2.4. Master Agent Processing of AgentX Responses
The master agent now marshals all subagent AgentX response PDUs and
builds an SNMP response PDU. In the next several subsections, the
initial processing of all subagent AgentX response PDUs is described,
followed by descriptions of subsequent processing for each specific
subagent Response.
7.2.4.1. Common Processing of All AgentX Response PDUs
1) If a subagent does not respond within the timeout interval for
this dispatch, it is treated as if the subagent had returned
`genErr' and processed as described below.
A timeout may be due to a variety of reasons, and does not
necessarily denote a failed or malfunctioning subagent. As such,
the master agent's response to a subagent timeout is
implementation-specific, but with the following constraint:
A subagent that times out on three consecutive requests is
considered unable to respond, and the master agent must close
the AgentX session as described in 7.1.9, step (2).
2) Otherwise, the h.packetID, h.sessionID, and h.transactionID
fields of the AgentX response PDU are used to correlate subagent
responses. If the response does not pertain to this SNMP
operation, it is ignored.
3) Otherwise, the responses are processed jointly to form the SNMP
response PDU.
7.2.4.2. Processing of Responses to agentx-Get-PDUs
After common processing of the subagent's response to an agentx-Get-
PDU (see 7.2.4.1 above), processing continues with the following
steps:
1) For any received AgentX response PDU, if res.error is not
`noError', the SNMP response PDU's error code is set to this
value, and its error index to the index of the variable binding
corresponding to the failed VarBind in the subagent's AgentX
response PDU.
All other AgentX response PDUs received due to processing this
SNMP request are ignored. Processing is complete; the SNMP
Response PDU is ready to be sent (see section 7.2.5, Sending the
SNMP Response-PDU).
2) Otherwise, the content of each VarBind in the AgentX response PDU
is used to update the corresponding variable binding in the SNMP
Response-PDU.
7.2.4.3. Processing of Responses to agentx-GetNext-PDU and
agentx-GetBulk-PDU
After common processing of the subagent's response to an agentx-
GetNext-PDU or agentx-GetBulk-PDU (see 7.2.4.1 above), processing
continues with the following steps:
1) For any received AgentX response PDU, if res.error is not
`noError', the SNMP response PDU's error code is set to this
value, and its error index to the index of the VarBind
corresponding to the failed VarBind in the subagent's AgentX
response PDU.
All other AgentX response PDUs received due to processing this
SNMP request are ignored. Processing is complete; the SNMP
response PDU is ready to be sent (see section 7.2.5, Sending the
SNMP Response PDU).
2) Otherwise, the content of each VarBind in the AgentX response
PDU is used to update the corresponding VarBind in the SNMP
response PDU.
After all expected AgentX response PDUs have been processed, if any
VarBinds still contain the value `endOfMibView' in their v.type
fields, processing must continue:
3) A new iteration of AgentX request dispatching is initiated
(as described in section 7.2.1.1), in which only those VarBinds
whose v.type is `endOfMibView' are processed.
4) For each such VarBind, a target OID range is identified
which is the lexicographical successor to the target OID range
for this VarBind on the last iteration. The target subagent is
the one that registered the target OID range. The target session
is the one in which the target OID range was registered.
If an agentx-GetNext- or GetBulk-PDU is being dispatched, the
starting OID in the SearchRanges is set to the target OID range,
and its "include" field is set to 1.
5) The value of transactionID must be identical to the value
used during the previous iteration.
6) The AgentX PDUs are sent to the subagent(s), and the responses
are received and processed according to the steps described in
section 7.2.4.
7) This process continues iteratively until a complete SNMP
Response-PDU has been built, or until there remain no target OID
range lexicographical successors.
7.2.4.4. Processing of Responses to agentx-TestSet-PDUs
After common processing of the subagent's response to an agentx-
TestSet-PDU (see 7.2.4.1 above), processing continues with the
further exchange of AgentX PDUs. The value of h.transactionID in the
agentx-CommitSet, -UndoSet, and -CleanupSet-PDUs must be identical to
the value sent in the testSet-PDU.
The state transitions and PDU sequences are depicted in section 7.3.
1) If any target subagent's response is not `noError', all other
agentx-Response-PDUs received due to processing this SNMP request
are ignored.
An agentx-CleanupSet-PDU is sent to each target subagent that has
been sent a agentx-TestSet-PDU.
Processing is complete; the SNMP response PDU is constructed as
described below in 7.2.4.6.
2) Otherwise an agentx-CommitSet-PDU is sent to each target
subagent.
7.2.4.5. Processing of Responses to agentx-CommitSet-PDUs
After common processing of the subagent's response to an agentx-
CommitSet-PDU (see 7.2.4.1 above), processing continues with the
following steps:
1) If any response is not `noError', all other
agentx-Response-PDUs received due to processing this SNMP request
are ignored.
An agentx-UndoSet-PDU is sent to each target subagent that has
been sent a agentx-CommitSet-PDU. All other subagents are sent a
agentx-CleanupSet-PDU.
2) Otherwise an agentx-CleanupSet-PDU is sent to each target
subagent. Processing is complete; the SNMP response PDU is
constructed as described below in 7.2.4.6.
7.2.4.6. Processing of Responses to agentx-UndoSet-PDUs
After common processing of the subagent's response to an agentx-
UndoSet-PDU (see 7.2.4.1 above), processing continues with the
following steps:
1) If any response is not `noError' the SNMP response
PDU's error code is set to this value, and its error index to the
index of the VarBind corresponding to the failed VarBind in the
agentx-TestSet-PDU.
Otherwise the SNMP response PDU's error code is set to `noError'
and its error index to 0.
7.2.5. Sending the SNMP Response-PDU
Once the processing described in sections 7.2.1 - 7.2.4 is complete,
there is an SNMP response PDU available. The master agent now
implements the Elements of Procedure for the applicable version of
the SNMP protocol in order to encapsulate the PDU into a message, and
transmit it to the originator of the SNMP management request. Note
that this may involve altering the PDU contents (for instance, to
replace the original VarBinds if an error condition is to be
returned).
The response PDU may also be altered in order to support the SNMP
version 1 framework. In such cases the required mapping is that
defined in RFC2089 [9]. (Note in particular that the rules for
handling Counter64 syntax may require re-sending AgentX GetBulk or
GetNext PDUs until a VarBind of suitable syntax is returned.)
7.2.6. MIB Views
AgentX subagents are not aware of MIB views, since view information
is not contained in AgentX PDUs.
As stated above, the descriptions of procedures in section 7 of this
memo are not intended to constrain the internal architecture of any
conformant implementation. In particular, the master agent
procedures described in sections 7.2.1 and 7.2.4 may be altered so as
to optimize AgentX exchanges when implementing MIB views.
Such optimizations are beyond the scope of this memo. But note that
section 7.2.3 defines subagent behavior in such a way that alteration
of SearchRanges may be used in such optimizations.
7.3. State Transitions
State diagrams are presented from the master agent's perspective for
transport connection and session establishment, and from the
subagent's perspective for Set transaction processing.
7.3.1. Set Transaction States
The following table presents, from the subagent's perspective, the
state transitions involved in Set transaction processing:
STATE
+----------------+--------------+---------+--------+--------
| A | B | C | D | E
| (Initial | TestOK | Commit | Test | Commit
| State) | | OK | Fail | Fail
| | | | |
EVENT | | | | |
---------+----------------+--------------+---------+--------+--------
| 7.2.3.1 | | | |
Receive | All varbinds | | | |
TestSet | OK? | X | X | X | X
PDU | Yes ->B | | | |
| No ->D | | | |
---------+----------------+--------------+---------+--------+--------
| | 7.2.3.2 | | |
Receive | | NoError? | | |
Commit- | X | Yes ->C | X | X | X
Set PDU | | No ->E | | |
---------+----------------+--------------+---------+--------+--------
Receive | | | 7.2.3.3 | |7.2.4.5
UndoSet | X | X | ->done | X | ->done
PDU | | | | |
---------+----------------+--------------+---------+--------+--------
Receive | | 7.2.4.4 | 7.2.3.4 |7.2.4.4 |
Cleanup- | X | ->done | ->done | ->done | X
Set PDU | | | | |
---------+----------------+--------------+---------+--------+--------
Session | | rollback | undo | |
Loss | ->done | ->done | ->done | ->done | ->done
---------+----------------+--------------+---------+--------+--------
There are three possible sequences that a subagent may follow for a
particular set transaction:
1) TestSet CommitSet CleanupSet
2) TestSet CommitSet UndoSet
3) TestSet CleanupSet
Note that a single PDU sequence may result in multiple paths through
the finite state machine (FSM). For example, the sequence
TestSet CommitSet UndoSet
may walk through either of these two state sequences:
(initial) TestOK CommitOK (done)
(initial) TestOK CommitFail (done)
7.3.2 Transport Connection States
The following table presents, from the master agent's perspective,
the state transitions involved in transport connection setup and
teardown:
STATE
+--------------+--------------
| A | B
| No transport | Transport
| | connected
| |
EVENT | |
----------------+--------------+--------------
Transport | |
connect | ->B | X
indication | |
----------------+--------------+--------------
Receive | | if duplicate
Open-PDU | | session id,
| | reject, else
| X | establish
| | session
| |
| | ->B
----------------+--------------+--------------
Receive | | if matching
Response-PDU | | session id,
| | feed to that
| X | session's FSM
| | else ignore
| |
| | ->B
----------------+--------------+--------------
Receive other | | if matching
PDUs | | session id,
| | feed to that
| X | session's FSM
| | else reject
| |
| | ->B
----------------+--------------+--------------
Transport | |notify all
disconnect | |sessions on
indication | X |this transport
| |
| | ->A
----------------+--------------+--------------
7.3.3 Session States
The following table presents, from the master agent's perspective,
the state transitions involved in session setup and teardown:
STATE
+-------------+----------------
| A | B
| No session | Session
| | established
EVENT | |
---------------+-------------+----------------
| 7.1.1 |
Receive | | X
Open PDU | ->B |
---------------+-------------+----------------
| | 7.1.9
Receive | X |
Close PDU | | ->A
---------------+-------------+----------------
Receive | | 7.1.5
Register PDU | X |
| | ->B
---------------+-------------+----------------
Receive | | 7.1.6
Unregister | X |
PDU | | ->B
---------------+-------------+----------------
Receive | |
Get PDU | |
GetNext PDU | |
GetBulk PDU | X | X
TestSet PDU | |
CommitSet PDU | |
UndoSet PDU | |
CleanupSet PDU | |
---------------+-------------+----------------
Receive | | 7.1.11
Notify PDU | X |
| | ->B
---------------+-------------+----------------
Receive Ping | | 7.1.12
PDU | X |
| | ->B
---------------+-------------+----------------
(continued next page)
---------------+-------------+----------------
Receive | | 7.1.2
IndexAllocate | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.4
IndexDeallocate| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.7
AddAgentxCaps | X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.1.8
RemoveAgentxCap| X |
PDU | | ->B
---------------+-------------+----------------
Receive | | 7.2.4
Response PDU | X |
| | ->B
---------------+-------------+----------------
Receive | |
Other PDU | X | X
---------------+-------------+----------------
8. Transport Mappings
The same AgentX PDU formats, encodings, and elements of procedure are
used regardless of the underlying transport.
8.1. AgentX over TCP
8.1.1. Well-known Values
The master agent accepts TCP connection requests for the well-known
port 705. Subagents connect to the master agent using this port
number.
8.1.2. Operation
Once a TCP connection has been established, the AgentX peers use this
connection to carry all AgentX PDUs. Multiple AgentX sessions may be
established using the same TCP connection. AgentX PDUs are sent
within an AgentX session. AgentX peers are responsible for mapping
the h.sessionID to a particular TCP connection.
All AgentX PDUs are presented individually to the TCP, to be sent as
the data portion of a TCP PDU.
8.2. AgentX over UNIX-domain Sockets
Many (BSD-derived) implementations of the UNIX operating system
support the UNIX pathname address family (AF_UNIX) for socket
communications. This provides a convenient method of sending and
receiving data between processes on the same host.
Mapping AgentX to this transport is useful for environments that
- wish to guarantee subagents are running on the same
managed node as the master agent, and where
- sockets provide better performance than TCP or UDP,
especially in the presence of heavy network I/O
8.2.1. Well-known Values
The master agent creates a well-known UNIX-domain socket endpoint
called "/var/agentx/master". (It may create other, implementation-
specific endpoints.)
This endpoint name uses the character set encoding native to the
managed node, and represents a UNIX-domain stream (SOCK_STREAM)
socket.
8.2.2. Operation
Once a connection has been established, the AgentX peers use this
connection to carry all AgentX PDUs.
Multiple AgentX sessions may be established using the same
connection. AgentX PDUs are sent within an AgentX session. AgentX
peers are responsible for mapping the h.sessionID to a particular
connection.
All AgentX PDUs are presented individually to the socket layer, to be
sent in the data stream.
9. Security Considerations
This memo defines a protocol between two processing entities, one of
which (the master agent) is assumed to perform authentication of
received SNMP requests and to control access to management
information. The master agent performs these security operations
independently of the other processing entity (the subagent).
Security considerations require three questions to be answered:
1. Is a particular subagent allowed to initiate a session with a
particular master agent?
2. During an AgentX session, is any SNMP security-related
information (for example, community names) passed from the
master agent to the subagent?
3. During an AgentX session, what part of the MIB tree is this
subagent allowed to register?
The answer to the third question is: A subagent can register any
subtree (subject to AgentX elements of procedure, section 7.1.5).
Currently there is no access control mechanism defined in AgentX. A
concern here is that a malicious subagent that registers an
unauthorized "sensitive" subtree, could see modification requests to
those objects, or by giving its own clever answer to NMS queries,
could cause the NMS to do something that leads to information
disclosure or other damage.
The answer to the second question is: No.
Now we can answer the first question. AgentX does not contain a
mechanism for authorizing/refusing session initiations. Thus,
controlling subagent access to the master agent may only be done at a
lower layer (e.g., transport).
An AgentX subagent can connect to a master agent using either a
network transport mechanism (e.g., TCP), or a "local" mechanism
(e.g., shared memory, named pipes).
In the case where a local transport mechanism is used and both
subagent and master agent are running on the same host, connection
authorization can be delegated to the operating system features. The
answer to the first security question then becomes: "If and only if
the subagent has sufficient privileges, then the operating system
will allow the connection".
If a network transport is used, currently there is no inherent
security. Transport Layer Security or SSL could be used to control
subagent connections, but that is beyond the scope of this document.
Thus it is recommended that subagents always run on the same host as
the master agent and that operating system features be used to ensure
that only properly authorized subagents can establish connections to
the master agent.
10. Acknowledgements
The initial development of this memo was heavily influenced by the
DPI 2.0 specification RFC1592 [7].
This document was produced by the IETF Agent Extensibility (AgentX)
Working Group, and benefited especially from the contributions of the
following working group members:
David Battle, Uri Blumenthal, Jeff Case, Maria Greene, Dave
Keeney, Harmen van der Linde, Bob Natale, Randy Presuhn, Aleksey
Romanov, Don Ryan, and Juergen Schoenwaelder.
The AgentX Working Group is chaired by:
Bob Natale
ACE*COMM Corporation
704 Quince Orchard Road
Gaithersburg MD 20878
Phone: +1-301-721-3000
Fax: +1-301-721-3001
EMail: bnatale@acecomm.com
11. Authors' and Editor's Addresses
Mike Daniele
Digital Equipment Corporation
110 Spit Brook Rd
Nashua, NH 03062
Phone: +1-603-881-1423
EMail: daniele@zk3.dec.com
Bert Wijnen
IBM Professional Services
Watsonweg 2
1423 ND Uithoorn
The Netherlands
Phone: +31-79-322-8316
EMail: wijnen@vnet.ibm.com
Dale Francisco (editor)
Cisco Systems
150 Castilian Dr
Goleta CA 93117
Phone: +1-805-961-3642
Fax: +1-805-961-3600
EMail: dfrancis@cisco.com
12. References
[1] Information processing systems - Open Systems Interconnection -
Specification of Abstract Syntax Notation One (ASN.1),
International Organization for Standardization. International
Standard 8824, (December, 1987).
[2] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Structure of Management Information for Version 2 of the Simple
Network Management Protocol (SNMPv2)", RFC1902, January 1996.
[3] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Textual Conventions for Version 2 of the Simple Network Management
Protocol (SNMPv2)", RFC1903, January 1996.
[4] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser,
"Protocol Operations for Version 2 of the Simple Network Management
Protocol (SNMPv2)", RFC1905, January 1996.
[5] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Management Information Base for Version 2 of the Simple Network
Management Protocol (SNMPv2)", RFC1907, January 1996.
[6] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network
Management Protocol", STD 15, RFC1157, SNMP Research, Performance
Systems International, MIT Laboratory for Computer Science, May
1990.
[7] Wijnen, B., Carpenter, G., Curran, K., Sehgal, A. and G. Waters,
"Simple Network Management Protocol: Distributed Protocol
Interface, Version 2.0", RFC1592, March 1994.
[8] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Coexistence between Version 1 and Version 2 of the Internet-
standard Network Management Framework", RFC1908, January 1996.
[9] Wijnen, B. and D. Levi, "V2ToV1: Mapping SNMPv2 onto SNMPv1
Within a Bilingual SNMP Agent", RFC2089, January 1997.
[10] Case, J., McCloghrie, K., Rose, M. and S. Waldbusser,
"Conformance Statements for Version 2 of the Simple Network
Management Protocol (SNMPv2)", RFC1904, January 1996.
[11] McCloghrie, K. and F. Kastenholz, "Evolution of the
Interfaces Group of MIB-II", RFC1573, January 1994.
[12] Case, J., "FDDI Management Information Base", RFC1285,
January 1992.
[13] Application MIB Working Group, Krupczak, C., and J. Saperia,
"Definitions of System-Level Managed Objects for Applications",
draft-ietf-applmib-sysapplmib-08.txt, 15 Apr 1997.
13. Full Copyright Statement
Copyright (C) The Internet Society (1998). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING