[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Updated GETCOLs
HI,
Below is an updated version of the GETCOLS proposal.
Internet Draft David T. Perkins
Document: draft-perkins-eos-gc-00.txt SNMPinfo
Expires: March 2003 September 2002
SNMP Get Columns Operation
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 [1].
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Abstract
This document describes a new operation for the SNMP protocol between
a command generator and a command responder. It is used to
efficiently retrieve specified columns from one or more tables. The
values are returned grouped by rows. The operation returns the rows
in lexigraphical order to allow multiple operations to be used when
all data cannot be returned in a single response. The operation also
supports a simple filtering operation that allows the command
responder to eliminate data unwanted by the command generator.
Table of Contents
1. Introduction...................................................2
2. New PDU Definitions............................................3
SNMP Get Columns Operation September 2002
3. Examples.......................................................5
4. Fields of the GETCOLS Request.................................10
4.1 Field request-id..........................................10
4.2 Field max-rows............................................10
4.3 Field inst................................................10
4.4 Field row-filter..........................................11
4.5 Field request-cols........................................12
5. Fields of a GETCOLS Response..................................12
5.1 Field request-id..........................................12
5.2 Field error-status........................................13
5.3 Field error-index.........................................13
5.4 Field requested-values....................................13
6. Issues and Concerns...........................................13
Security Considerations..........................................14
References.......................................................14
Acknowledgments..................................................14
Author's Addresses...............................................14
Full Copyright...................................................15
1. Introduction
The SNMPv1 protocol has GET and GETNEXT operations to retrieve data.
Version 2 of the SNMP protocol operations has GET and GETNEXT
operations, and in addition has the GETBULK operation. For tables
containing a few number of rows, these operations allow for efficient
retrieval all rows of a table. However, for tables with more than 50
to 100 rows, these operations do not provide the needed efficiency.
The result is management applications that are sluggish or so slow
that they become unusable. The GETCOLS operation described in this
document is much more efficient than these existing operations. Also
it works well when the maximum message size is increased from 1000 to
32000 octets, which typically occurs when changing from a UDP to a
TCP transport connection. The SNMPv3 protocol allows new operations
to be added without any changes to the protocol definition any many
components of a manager or agent. Thus, this new operation has no
affect on any existing SNMPv3 specification.
This "simple" operation can most likely be easily added to existing
SNMPv3 implementations without affecting the existing code that an
SNMP engine uses to access management information in a managed
system. And, with some information from a MIB module, it should be
easy for a proxy to be created that supports proxy access to
management targets that support access only through the SNMPv1 or
SNMPv2c protocols.
When used in an SNMPv3 command responder, this new operation will
provide the following benefits over exiting operations:
1.
efficiency in retrieval of a "large" number of rows
SNMP Get Columns Operation September 2002
2.
enhanced organization the returned values into "rows" even when
there are holes in the accessed table.
3.
elimination of overshoot of the bulking operation (That is, only
the desired data is returned, and not the values after the
desired data that are provided to "fill out" the last response.)
4.
elimination of rows that contain data unneeded by the command
generator.
2. New PDU Definitions
The definitions that follow are written in the ASN.1 notation like
that found for version 2 of the SNMP PDUs. However, at this time, no
verification has been taken to ensure that the ASN.1 is absolutely
correct according to the 1988 version of ASN.1 (which is also used to
define version 2 of the SNMP PDUs). The definitions are provided as
guidance to the functionality provided by the operation and to show
the operands. As the operation is further refined and/or
implementation experience is obtained, it is expected that the
definitions will be made both correct and complete.
GC-SNMP-PDU DEFINITIONS ::= BEGIN
IMPORTS
ObjectName, ObjectSyntax, Integer32
FROM SNMPv2-SMI;
--
-- GETCOLS Request
--
GetColsRequest-PDU ::=
[XXX] -- 9?
SEQUENCE {
request-id
Integer32,
max-rows -- 0 = all
Integer32,
inst
CHOICE {
beginning [1]NULL, -- start at beginning
ge-named -- start instance greater
-- or equal value
-- OID { 0 0 <encoded index value> }
[2]OBJECT IDENTIFIER,
gt-named -- start instance greater
-- than value
-- OID { 0 0 <encoded index value> }
SNMP Get Columns Operation September 2002
[3]OBJECT IDENTIFIER }
row-filter Filter-spec,
request-cols
SEQUENCE (0..max-bindings) OF Col-name
}
Col-name ::= OBJECT IDENTIFIER -- ID (name) of column
Filter-spec ::= SEQUENCE OF Filter-item
Filter-item ::= CHOICE {
-- operands
val-int [0] INTEGER, -- Integer value
val-str [1] OCTET STRING, -- Octet string value
val-oid [2] OBJECT IDENTIFIER, -- OID value
val-index[7] INTEGER(1..max-indices),-- index number (1 based)
val-var [8] OBJECT IDENTFIER, -- SNMP variable
val-col [9] OBJECT IDENTIFIER, -- SNMP column with same
-- instance as row
-- operations:
op-eq [20] NULL, -- Equals (2 operands)
op-neq [21] NULL, -- Not Equals (2 operands)
op-and [22] INTEGER(2..max-ands), -- AND (n operands)
op-or [23] INTEGER(2..max-ors), -- OR (n operands)
op-gt [24] NULL, -- GT (2 operands)
op-ge [25] NULL, -- GE (2 operands)
op-lt [26] NULL, -- LT (2 operands)
op-le [27] NULL, -- LE (2 operands)
op-not [28] NULL, -- NOT (1 operand)
op-regex [29] NULL, -- REGEX match(2 operands (val, regex))
op-exist-col [30] OBJECT IDENTIFIER -- SNMP column with same
-- instance as row exists
-- and is accessible
}
GetColsResponse-PDU ::=
[XXX] -- 10?
SEQUENCE {
request-id
Integer32,
error-status -- 0 = noError
Integer32,
error-index -- 0 = none
SNMP Get Columns Operation September 2002
Integer32,
requested-values
RowList
}
RowList ::= SEQUENCE (0..max-bindings) OF RowValues
RowValues ::= SEQUENCE {
row-inst OBJECT-IDENTIFIER, -- values is { 0 0 <encoded-index> }
col-values SEQUENCE OF Object-Syntax
}
}
3. Examples
Here are some example requests and paired response. In each case, the
curly braces indicate a sequence of some kind or an OID value.
Example 1: retrieve the admin and oper status of the row with ifIndex
equal to 3. Note that there are three ways to do this. The first two
are "efficient" and the third way is a gross waste of agent
resources.
Requests that result in same response:
a) GetColsRequestPDU { -- an efficient approach
request-id ::= 143
max-rows ::= 1
inst ::= { [2] {0 0 3} } -- instance GE 3
row-filter ::= { } -- empty (none)
request-cols ::= {
{1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
{1 3 6 1 2 1 2 2 1 8}} -- ifOperStatus
}
b) GetColsRequestPDU { -- a less efficient approach
request-id ::= 1
max-rows ::= 1
inst ::= { [3] {0 0 2} } -- instance GT 2 (that is 3)
row-filter ::= { } -- empty (none)
request-cols ::= {
{1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
{1 3 6 1 2 1 2 2 1 8}} -- ifOperStatus
}
c) GetColsRequestPDU { -- a grossly inefficient approach
-- compared with a) and b)
SNMP Get Columns Operation September 2002
request-id ::= 1
max-rows ::= 1
inst ::= { [1] } -- start scanning at beginning
row-filter ::= {
op-eq,
val-int 3, -- value of index
val-index 1} -- ifIndex
request-cols ::= {
{1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
{1 3 6 1 2 1 2 2 1 8}} -- ifOperStatus
}
Response:
GetColsResponsePDU {
request-id ::= 143
error-status ::= 0
error-index ::= 0
requested-values ::= {
{ { 0 0 3}, -- instance
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
}
}
Example 2: Retrieve the values for ifAdminStatus and ifOperStatus for
all rows in the IF table (3 rows at a time). Note the IF table has
five rows with instances 1 through 5.
first request:
GetColsRequestPDU {
request-id ::= 11032
max-rows ::= 3
inst ::= { [1] } -- start at the beginning
row-filter ::= { } -- empty (none)
request-cols ::= {
{1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
{1 3 6 1 2 1 2 2 1 8}} -- ifOperStatus
}
first response:
GetColsResponsePDU {
request-id ::= 11032
error-status ::= 0
error-index ::= 0
requested-values ::= {
{ { 0 0 1}, -- instance
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
},
{ { 0 0 2}, -- instance
SNMP Get Columns Operation September 2002
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
},
{ { 0 0 3}, -- instance
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
}
}
second (and last) request:
GetColsRequestPDU {
request-id ::= 11033
max-rows ::= 3
inst ::= { [3] { 0 0 3} } -- start GT instance 3
row-filter ::= { } -- empty (none)
request-cols ::= {
{1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
{1 3 6 1 2 1 2 2 1 8}} -- ifOperStatus
}
second (and last) response:
GetColsResponsePDU {
request-id ::= 11033
error-status ::= 0
error-index ::= 0
requested-values ::= {
{ { 0 0 4}, -- instance
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
},
{ { 0 0 5}, -- instance
{ 1, -- ifAdminStatus is up(1)
1 } } -- ifOperStatus is up(1)
}
}
Example 3: Retrieve every entry in the IF table where the admin
status is 'up(1)', the oper status is 'down(2)', and the value of
last change is greater than 23056. (Note that this has the behavior
similar to TimeFilters found in RMON.) The response shows that
interfaces with index of 4 and 8 match the filter.
Request (there are many ways to write a filter expression.
The following shows how the AND operation can be
used differently to produce the same result):
a) shown with AND taking 2 operands
GetColsRequestPDU {
request-id ::= 13789
max-rows ::= 50
SNMP Get Columns Operation September 2002
inst ::= { [1] } -- start at beginning
row-filter ::= {
op-and 2,
op-and 2,
op-eq,
val-int 1, -- 'up(1)'
val-col {1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
op-eq,
val-int 2, -- 'down(2)'
val-col {1 3 6 1 2 1 2 2 1 8}, -- ifOperStatus
op-gt,
val-col {1 3 6 1 2 1 2 2 1 9}, -- ifLastChange
val-int 23056
}
request-cols ::= {
{1 3 6 1 2 1 2 2 1 9} -- ifLastChange
}
}
Note: the filter expression tree (turned sideways) is:
and--- and--- eq(int 1, col ifAdminStatus)
\ \
| -- eq(int 2, col ifOperStatus)
|
-- gt(col ifLastChange, int 23056)
b) shown with AND taking 3 operands, which is flatter filter tree
GetColsRequestPDU {
request-id ::= 13789
max-rows ::= 50
inst ::= { [1] } -- start at beginning
row-filter ::= {
op-and 3,
op-eq,
val-int 1, -- 'up(1)'
val-col {1 3 6 1 2 1 2 2 1 7}, -- ifAdminStatus
op-eq,
val-int 2, -- 'down(2)'
val-col {1 3 6 1 2 1 2 2 1 8}, -- ifOperStatus
op-gt,
val-col {1 3 6 1 2 1 2 2 1 9}, -- ifLastChange
val-int 23056
}
request-cols ::= {
{1 3 6 1 2 1 2 2 1 9} -- ifLastChange
}
}
Note: the filter expression tree (turned sideways) is:
SNMP Get Columns Operation September 2002
and--- eq(int 1, col ifAdminStatus)
\
|- eq(int 2, col ifOperStatus)
|
-- gt(col ifLastChange, int 23056)
response (the same for both requests):
GetColsResponsePDU {
request-id ::= 13789
error-status ::= 0
error-index ::= 0
requested-values ::= {
{ {0 0 4} -- instance 4
{ 23056 } }, -- value of ifLastChange
{ {0 0 8} -- instance 8
{ 23089 } } -- value of ifLastChange
}
}
Example 4: Retrieve status of every entry in TCP connection table
with a specific IP address pair (10.0.0.19 and 10.0.0.21). The
response shows that there is one connection that matches.
Request (Since the indices are columns in the table, there are
two ways to specify the filter. Both are shown.):
a) using columns in the filter spec:
GetColsRequestPDU {
request-id ::= 78123
max-rows ::= 50
inst ::= { [1] } -- start at beginning
row-filter ::= {
op-and,
op-eq,
val-str '0a000013'h, -- IP address 10.0.0.19
val-col { 1 3 6 1 2 1 6 13 1 2 }, -- tcpConnLocalAddress
op-eq,
val-str '0a000015'h, -- IP address 10.0.0.21
val-col { 1 3 6 1 2 1 6 13 1 2 } -- tcpConnRemAddress
}
request-cols ::= {
{1 3 6 1 2 1 6 13 1 1} -- tcpConnState
}
}
b) using indices in the filter spec:
GetColsRequestPDU {
request-id ::= 78123
SNMP Get Columns Operation September 2002
max-rows ::= 50
inst ::= { [1] } -- start at beginning
row-filter ::= {
op-and,
op-eq,
val-str '0a000013'h, -- IP address 10.0.0.19
val-index 1, -- tcpConnLocalAddress
op-eq,
val-str '0a000015'h, -- IP address 10.0.0.21
val-index 3 -- tcpConnRemAddress
}
request-cols ::= {
{1 3 6 1 2 1 6 13 1 1} -- tcpConnState
}
}
response:
GetColsResponsePDU {
request-id ::= 78123
error-status ::= 0
error-index ::= 0
requested-values ::= {
{ { 0 0 10 0 0 19 2045 10 0 0 21 3299} -- instance
{ 5 } } -- tcpConnState is established(5)
}
}
Example 5: <add an example showing columns from different tables,
such as augmented tables>
4. Fields of the GETCOLS Request
4.1 Field request-id
The "request-id" field contains a value that is used by a command
responder to pair up a response to a request and has the same use and
semantics as the field in version 2 of the SNMP PDU definitions.
4.2 Field max-rows
The "max-rows" field contains the value 0 to indicate an unlimited
number of rows, or the maximum number of rows to return in a
response.
4.3 Field inst
SNMP Get Columns Operation September 2002
The "inst" field specifies the starting instance to be used in
searching for the first row to be returned. The field is a choice
with three cases, which are:
1.
beginning, start at the beginning of the table
2.
ge-named, start at the first instance whose value is
lexigraphically greater than or equal to the specified value.
3.
gt-name, start at the first instance whose value is
lexigraphically greater than the specified value.
In the second and third cases, the instance is encoded following the
rules specified in section 7.7 of version 2 of the SNMP SMI after two
leading sub-identifier values of 0. (Note that ASN.1/BER have
restrictions on the values of the first two sub-identifiers, and the
instance value is "padded on the left" with the two zeros so that the
instance value is not restricted.)
4.4 Field row-filter
The "row-filter" field specifies zero, one, or more filter
specifications for each candidate row. It is yet to be determined the
minimal number of filter specifications and the types of filter
specifications that are needed to be supported to claim conformance.
New types of filter specifications will be allowed and administrated
through IANA. THERE IS NO NEED NOR MECHANISM PROVIDED FOR "VENDOR
DEFINED" FILTER SPECIFIFICATIONS. A filter specification is an
operation and its associated operands. A row-filter is a flattened
version of an expression tree. Conceptually, it is evaluated by
recursively calling an expression evaluation function with a
candidate row and a pointer to the expression to be evaluated. A
malformed "row-filter" value will result in the return of an error. A
validly specified row-filter will either match or not match a
candidate row. If there is not a match, then the row is skipped (not
returned). Otherwise, the row is added to the response if there is
room (as determined by the associated max message size for the
response).
The following are filter operations:
1.
op-eq, check if the two operands are equal in value, and, if so,
return a match. Both operands must be of the same base type
(which is either integer, octet string, or object identifier),
and, if not, a "malformed filter" error is returned.
2.
op-neq, check if the two operands are not equal in value, and,
if so, return a match. Both operands must be of the same base
type (which is either integer, octet string, or object
identifier), and, if not, a "malformed filter" error is
returned.
3.
op-and, check the specified number of sub-expressions for a
match condition. Only if all have a match condition is the
result of the operation a match.
SNMP Get Columns Operation September 2002
4.
op-or, check the specified number of sub-expressions for a match
condition. If any have a match condition, then the result of the
operation is a match.
5.
op-gt, op-ge, op-lt, op-le, check that the two operands for the
comparison are the same type and satisfy the comparison
operation. If so, then match is returned. If the operands are
different types, then a "malformed filter" error is returned.
6.
op-not, check that the sub expression has not returned a match,
and, if so, the result is a match condition.
7.
op-regex, check that the first operand is an octet string whose
value matches the regular expression (regex) specified by the
second value. On a regex match the result of the operation is a
match condition. If either operand is not an octet string value,
then a "malformed filter" error is returned.
8.
op-exist-col, test to see if the associated columnar object
exists and is accessible. If so, the result of the operation is
the match condition.
The following are filter operands:
1.
val-int, a signed integer value
2.
val-str, an octet string value
3.
val-oid, an OID value
4.
val-index, the value of the identified index for the row.
Indices are identified starting at 1. If the identification for
an index is greater then the number of indices for a row, then a
"malformed filter" error is returned.
5.
val-var, the value of the specified SNMP variable. If the OID
does not name an accessible object instance, then a "malformed
filter" error is returned. The type of the value that is
retrieved is one of integer, octet string, and OID.
6.
val-col, a variable is constructed using the OID of a column and
the OID fragment that identifies the instance of the row. The
value is that of the resulting SNMP variable. If the OID does
not name an accessible object instance, then a "malformed
filter" error is returned. The type of the value that is
retrieved is one of integer, octet string, and OID.
4.5 Field request-cols
The "request-cols" field is a sequence of zero, one, or more OID
values that name columns in one or more tables that have the same
indexing.
5. Fields of a GETCOLS Response
5.1 Field request-id
The "request-id" field has the value from the "request-id" of the
GETCOLS request.
SNMP Get Columns Operation September 2002
5.2 Field error-status
The "error-status" field contains zero to indicate no error, or one
of the following values:
<values to be specified later>
5.3 Field error-index
The "error-index" field is either zero, or a value that is associated
with the error-status field. <more description later>
5.4 Field requested-values
The "requested-values" field contains a sequence of rows that match
the conditions specified by the GETCOLS request. Each element in the
sequence is a sequence of fields:
1.
row-inst, an OID value that is the instance that identifies the
row and is encoded as specified in section 7.7 of version 2 of
the SNMP SMI ater two leading sub-identifier values of 0.
2.
col-values, a sequence of values of the columns specified in
field request-cols of the request. Note that this may be empty.
6. Issues and Concerns
The GETCOLS operation has been designed so that it provides great
benefit to management applications with little added cost to existing
agent code. In particular, it is desirable that the changes needed in
an agent be localized to the engine and do not extend to the access
routines of management information. To support the operation,
additional information may be needed from the MIB modules to describe
the indexing of tables. Until coding changes are attempted (on the
leading agent code bases), it will not be known if the filtering on
the index values, and separation of the index value from the
variables is possible without modification of existing management
information access code. (Reality check here. There are several
orders of magnitude of existing management information access code
compared to the amount of code in all of the SNMP agent engines. Any
approach that requires a massive amount of changes to the access code
is economically infeasible.)
A big concern with this operation (and should be a concern with
GETBULK) is the variation in the time for the operation to complete.
Since SNMP over UDP can result in packet loss, a manager must set a
timer on each request. If a response is not received in a configured
amount of time, then the request is retried. The timeout must be
chosen as short as reasonably possible to reduce the elapsed time to
complete a series of requests in spite of packet loss. If the timeout
is too short, then the agent is burdened with performing redundant
SNMP Get Columns Operation September 2002
operations which can result in cascaded packet timeouts. (What this
means is that resent requests when there is no actual packet loss can
result in delayed processing of a new request, which results in
additional assumed packet loss and request retries.) The timeout used
by a manager must be greater than the network round trip time and the
operation processing time of the agent. Since the processing time for
a GETCOLS operation may have a huge variation that depends on
complexity of filters, the number of rows in a table, the number of
rows to be returned, the access time, etc. an appropriate value for
processing time can not easily be determined. The SNMP protocol does
not provide a mechanism for an SNMP agent to determine that a
received request is a duplicate of one previously received and to
discard duplicates of a request that are queued or being processed,
or to resend the response of an already processed request. Adding
such a mechanism would solve this problem. Or if SNMP is run over a
connection oriented transport such as TCP, a manager will never retry
a request except on the termination of the transport connection.
Security Considerations
Stuff here
References
References here
Acknowledgments
<Add any acknowledgements>
Author's Addresses
David T. Perkins
SNMPinfo
3600 Benton Street #24
Santa Clara, CA 95051
Phone: 408 394-8702
Email: dperkins@snmpinfo.com
SNMP Get Columns Operation September 2002
Full Copyright
Copyright (C) The Internet Society (2002). 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
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.