[Search] [pdf|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01                                                         
IPSP Working Group                                           W. Hardaker
INTERNET-DRAFT                           Network Associates Laboratories
draft-hardaker-eos-oops-01.txt                            September 2002


                     Object Oriented PDUs for SNMP
                     draft-hardaker-eos-oops-01.txt


Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.  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.

Copyright Notice

    Copyright (C) The Internet Society (2002).  All Rights Reserved.


1.  Introduction

    This draft specifies some new PDU operations intended to optimize
    SNMP requests for performance.

    This draft is not a complete specification, but merely is intended
    to illustrate concepts which can then be discussed within the EoS
    working group.  A complete specification will be completed after the
    agreed features and packet structure is fairly well solidified so
    the author doesn't have to rewrite large portions of stuff ;-).
    There are no error handling codes or elements of procedures defined
    yet.  The concepts, however, have been thought out about a lot.
    Feedback on what you see within would be greatly appreciated at this
    point.




Wes Hardaker                                                    [Page 1]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    Terminology in this draft is frequently inconsistent.  Forgive the
    use of the old-school terminology (e.g., "agent") intermixed with
    new terminology (e.g., "command responder").  The other common error
    is the usage of the word "column" instead of "sub-identifier" or
    whatever the next draft for SMIv3 is going to call it (I forget and
    think it may be changing in the next draft anyway hence I didn't try
    to get it right in this document).  This too will be fixed if a
    standardized specification on this work goes forward.

    Some of the stuff in this draft has yet to undergo debate.
    Particularly the Write operation is not solidified in my mind and
    will certainly be subject to debate as to whether they go to far
    into solving the problems that many people have pointed out with
    existing transactions.  Please read the draft all the way through,
    including the section on "Design Considerations and Questions"
    before asking questions of the author or the working group.

    Finally, this is very much a working document.  The descriptions
    described here-in may not even exactly match the author's thoughts,
    as the document hasn't been extensively proof-read yet.

1.1.  Related work with the SMIng working group.

    In revamping this document and the contained PDUs, the direct
    correlations to the SMIng working group have since been dropped.
    They'll be reinstated shortly, but for now just know that all the
    PDUs contained within this document can be used with the new
    hierarchal structure of a newer SMIv3 MIB structure.

    To think about it, everywhere you see the word "BER" in a PDU
    definition, think "BER or recursive".  IE, sub-elements within a
    SMIng working group will be encoded into a BER field in the same way
    that the containing request needed it.

1.2.  Table of Contents

    1.         Introduction                                        1
    1.1.       Related work with the SMIng working group.          2
    1.2.       Table of Contents                                   2
    2.         Background and Motivations                          3
    2.1.       GET-NEXT complexity                                 3
    2.2.       OID compression                                     4
    2.3.       Row operations                                      4
    2.4.       Complex object relationships                        4
    2.5.       Retrieving of more data than is desired.            5
    2.6.       Row hole traversal and object grouping              5
    2.7.       Index parsing and OID length restrictions.          6
    2.8.       Transactions                                        6



Wes Hardaker                                                    [Page 2]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    2.9.       Easy conversion to and from popular data formats    6
    2.10.      Human readable error strings                        6
    3.         Transport Protocol Considerations                   7
    4.         New PDU definitions                                 7
    4.1.       The Get-Object-PDU                                  7
    4.2.       The Get-Object-Response PDU                        13
    4.3.       The Write-Object-PDU                               15
    4.3.1.     Write-Object-PDU transaction semantics             18
    4.4.       The Write-Object-Response-PDU                      19
    5.         ASN.1 definitions for the PDUs                     21
    6.         Examples                                           22
    6.1.       Retrieve a specific row from the ifTable           22
    6.2.       A multiple-packet example with a double filter.    23
    7.         Elements of Procedure.                             26
    8.         Design Considerations and Questions                26
    8.1.       Return-field ranges                                26
    8.2.       Write-Object-PDU complexity                        26
    8.3.       Get-Object/Write-Object commonality.               27
    8.4.       Concrete packet formats vs optional field formats. 27
    8.5.       Push Button Functionality.                         28
    9.         Author's Addresses:                                29
    10.        References                                         29
    11.        Full Copyright Statement                           29


2.  Background and Motivations

    Many recognized problems exist within the SNMP protocol [OPREQ,...].
    Many of the known problems are addressed by the new protocol
    operations defined within this draft.  The general problems trying
    to be solved are described in this section.

2.1.  GET-NEXT complexity

    A large number of problems result from a devices inability to access
    it's data in a way that can be efficiently traversed when searching
    for the next object in a series of GET-NEXT or GET-BULK SNMP
    requests.  Internally, many implementations differ and thus it would
    be impossible in many cases to define a MIB which would be efficient
    when implemented on every architecture.

    The operations defined in this document do not suffer from these
    problems, as the data can be returned in any order that the agent
    feels is appropriate.  It MUST, however, return data in a consistent
    manner such that if the same data is requested twice the agent will
    return the data in the same order.  The exact order in which objects
    are returned is implementation specific.




Wes Hardaker                                                    [Page 3]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    It's the author's belief that every agent will benefit from this,
    and that most managers don't care in the first place.  Manager's are
    likely to either need the data unsorted in the first place (e.g. may
    only care about the values each row and not the relationships
    between the rows) or the data will need to be sorted in a different
    fashion than the MIB indexing defines in the first place.  If the
    manager does need the data sorted, it's more likely it'll have the
    power to more easily do sorting via utilization of database
    technologies that are not realistically available on many agent
    platforms.

2.2.  OID compression

    SNMPv2 PDU consist of a sequence of varbinds and in many cases, when
    multiple objects are requested from the agent, the OIDs contained
    within have common prefixes.  It is widely recognized as a waste of
    resources to duplicate this prefix repeatedly.

    The PDUs defined in this document only rely on a base OID (e.g., an
    object identifier pointing to a SNMP Table) once, and the sub-
    objects (e.g., a row in a SNMP Table) underneath it are defined as
    references from the base OID.  Each index set which defines the
    proper reference for the remainder of the data components in a given
    "row" or "sub-object" is only included once as well.  This allows
    large groups of data to be transmitted while only requiring a single
    OID to identify the top most grouping object (e.g., a table).

2.3.  Row operations

    The ability to manipulate an entire row within a SNMP Table at once
    has long been a frustration of programmers implementing the
    protocol.

    The PDUs defined in this document are able to operate on entire
    groups of objects at once, where one of these groupings types is a
    row within a normal SNMP Table.

2.4.  Complex object relationships

    Many people do not properly understand the interrelationships
    between SNMP Tables and have desired the ability to express their
    data in a more hierarchal fashion, such that SNMP tables can contain
    other SNMP tables.  Although it is not possible to enable nested
    datatypes within SMIv2 today, the SMIng working group is trying to
    solve these problems and create the ability to define more complex
    relationships in SMIv3.

    The way object groupings are referenced within the PDUs defined in



Wes Hardaker                                                    [Page 4]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    this document allows hierarchal object data to be transmitted
    efficiently and as a single group, thus allowing groups defined
    within SMIv3 to be efficiently transmitted within the PDUs defined
    in this document, new SMIv3-style objects be deployed.

    XXX: mention the intention to make the object definitions a bit
    extensible, so that new types requiring new parameters can be easily
    handled in the future without replacing the PDUs themselves.

2.5.  Retrieving of more data than is desired.

    Extracting only the data needed from a SNMP Table has traditionally
    required pulling the entire table of data to the management station
    in many cases, when the indexes and their ordering was not
    sufficient for requesting subsets of the data desired.

    The request PDUs defined in this document allow more careful
    selection of indexing data and allow simple search criteria to be
    fulfilled.  A delicate balance is required to ensure that the
    devices being polled for data are not taxed with expensive search
    requests, so the criteria imposed within these documents is limited
    to a limited set of operators which may or may not be supported by
    the command responder implementation.  The intention is not to shift
    all the complex decision processing burden from the management
    station to the command responder, but to increase efficiency on the
    wire where possible.

    XXX: the agent will actually have the ability to gain improvements
    from this optimization since the manager will perform fewer requests
    as a whole.

2.6.  Row hole traversal and object grouping

    When requests to GET, GET-NEXT, and GET-BULK data come back in a
    SNMP RESPONSE PDU, the data can be hard to organize back into a
    logical structure again.  Holes of data (a row that contains no data
    for a particular column) within SNMP Tables make processing of the
    data collected more tedious.  Additionally, GET-BULK responses
    interleave it's data, possibly with END-OF-MIB exceptions, which
    only adds further complexity to the data processing.

    Since the PDUs defined in this document deal directly with MIB
    objects as a whole, the data relationships within an object is
    preserved.  This makes transferring large amounts of data efficient
    on both the sending and receiving side, as neither side needs to
    sort VarBinds properly.  The data groupings are now appropriately
    marked within the packet itself.




Wes Hardaker                                                    [Page 5]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


2.7.  Index parsing and OID length restrictions.

    Although the encoding and decoding of Table indexes into and out out
    OIDs is algorithmic, many SNMP software packages and toolkits make
    mistakes in implementing the algorithm.  Additionally, since the
    maximum length of an OID is limited to 128 sub-identifiers, it
    limits the size of the index data that can be contained within an
    OID.  This limitation results in poorly designed and broken MIBs and
    MIBs with less-than-ideal table indexes.

    The indexes within the PDUs defined in this document are encoded
    directly into the packet as opposed to being encoded into the OID
    first (which is then encoded into the packet).  This simplifies both
    management and agent code and reduces the chances of one side
    incorrectly encoding or decoding the indexes.  Additionally, it
    provides the ability to use a set of indexes which is larger than
    the OID-encoded imposed length of 255 sub-identifies.

2.8.  Transactions

    The limited set of SNMP transactions have been difficult to cope
    with when large sets of data must be pushed around, since all the
    objects within a SNMP SET PDU must be set as if simultaneously.  In
    actuality, configuration data often contains independent segments of
    data.  Typically, independent sets of data must be pushed inside
    individual PDUS when configuring an agent, which is inefficient.

    The PDUs defined in this document define a less restrictive and more
    flexible transaction model that lets large quantities of data be
    pushed efficiently across the network and will still allow
    individual groupings to specify whether they are inter-related and
    must be treated as a single transaction or not and whether or not
    ordering is important

2.9.  Easy conversion to and from popular data formats

    A desire has been shown by network operators for SNMP objects to be
    easily accessible and convertable to and from more human friendly
    expression languages and storage systems, like XML or SQL Databases.
    The objects within the PDUs contained in this document are designed
    for such a purpose.  It should be, for example, trivial to convert
    them to and from a hierarchial XML schema set describing the objects
    in question.  For the example XML case, the BER hierarchal packet
    format can be quickly converted to XML by replacing the sequence
    tags with XML ascii delimiter tags.

2.10.  Human readable error strings




Wes Hardaker                                                    [Page 6]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    Integer error codes are extremely useful for machine parsibility and
    interoperability, but it's frequently nice to have an extra error
    string that may be passed to an operator to assist in extra
    debugging of problems.  The response PDUs defined in this document
    contain an "error string" for exactly this purpose.


3.  Transport Protocol Considerations

    The PDUs defined in this document allow the transmission of large
    data sets in a more compressed form than previous SNMP PDUs, it is
    still recommended that large requests and responses be transmitted
    over a SNMP transmission domain which provides for guaranteed
    network packet delivery (e.g., TCP).  Large responses, containing
    many objects, carried over transmission domains (e.g., UDP) which
    can not guarantee delivery are still likely to be problematic.  It
    is well beyond the scope of this document to re-implement reliable
    transmission mechanisms.

4.  New PDU definitions

    This section defines the new PDUs.

    Right now, these PDUs are not in a ASN.1 standard format simply for
    clarity to the reader.  Proper ASN.1 definitions will be published
    as the format of the PDUs are more stabilized (probably late 2002)
    and more widely accepted.  ASN.1 is designed for machine
    readability, and this draft is currently still intended for
    primarily human consumption.

    In the mean time, here is a non-ASN.1 PDU breakdown.  Any {} pairs
    below are essentially a BER sequence.  At least the larger sequences
    are expected to be implemented using the non-deterministic sequence
    type (a beginning and ending sequence tag, rather than a single tag
    and a length) to ease the burden on encoders.  [] means a sequence
    list (array), ie multiple objects.  The author would like to delay
    the argument over coding semantics until after the PDU structure
    itself has been defined.  Note that some of the fields below might
    be implemented using the OPTIONAL ASN.1 field tag as well.  Again,
    this will be a discussion for later.


4.1.  The Get-Object-PDU

    Here's the breakdown of a Get-Object-PDU (GOP), which can be thought
    of as a replacement for GET, GETNEXT and GETBULK.
        Get-Object-PDU ::= {
           request-id           Integer32,



Wes Hardaker                                                    [Page 7]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


           option-field         {}          -- a sequence
                                               reserved for future use

           request-objects[] ::= {
             {
               max-return-objects         Integer32,
               skip-objects               Integer32,
               max-depth                  Integer32,
               cursor                     OCTET STRING,
               flags                      BITS { restartOnInvalidCursor(0),
                                                 returnAllDataOnUnsupportedMatch(1),
                                                 dontReturnObjectNumbers(2),
                                                 reserved(3) },
               option-field               {}          -- a sequence
                                                         reserved for future use
               request-base-OID,                      -- (eg, OID for a table)

               index-request-list[] ::= { INDEX1, INDEX2, ... },
               column-request-list[] ::= { COLNUM1, COLNUM2, ... },

               index-search-objects[] ::= {
                   { index-number         Integer32,
                     match-type           MATCH-TYPE,
                     index-search-value   BER },
                   ...
               },

               column-search-objects[] ::= {
                   { column-number        Integer32,
                     match-type           MATCH-TYPE,
                     column-search-value  BER },
                   ...
               }
             }
             ...  -- possibly more request-objects
           }

    In the above, the following pieces need explaining (and this is not an
    exact elements of procedure, but should give a feel for how PDU
    processing will eventually be described):

       request-id:              The standard request-id concept that exists
                                in previous PDUs defined by the previous
                                versions of SNMP

       max-return-objects:      The maximum number of objects to return in one
                                response message.  A value of 0 indicates "all".




Wes Hardaker                                                    [Page 8]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


       skip-objects:            Don't return the first skip-objects objects,
                                but rather return objects numebering from
                                (skip-objects + 1) to (max-return-objects +
                                skip-objects + 1).  A value of 0 indicates
                                start returning with the first object.

       max-depth:               The maximum depth of a SMIv3 structure to
                                return.  This will be explained in greater
                                detail in a later draft.

       cursor:                  An OCTET STRING defining the starting point
                                for collecting data.  This MUST be a zero
                                length string for the first request, and
                                SHOULD contain the value in the response
                                for chained requests which are expected to
                                return future data.  The value of the
                                cursor is implementation dependent at the
                                command responder.  The manager MUST treat
                                it as generic data and should use it when
                                possible to obtain the next set of
                                information in a series of requests.
                                Command responders MUST refer to the value
                                of the skip-objects field if the cursor
                                field is a zero length string.
                                Command responders MUST ignore  the value
                                of the skip-objects field if the cursor
                                field is a non-zero length string and is
                                deemed to be a valid cursor.

                                If this object is specified, the skip-objects
                                is ignored by the command responder.

                                Cursors SHOULD be defined by the command
                                responder in such a way as to avoid
                                referencing an existing object in such a
                                way that if the existing object disappears
                                the cursor will become invalid.  I.E.,
                                where possible, cursors should be data
                                independent where possible and should be a
                                reference into the appropriate place in
                                the storage mechanism and not a reference
                                to a data piece itself within the storage
                                mechanism.

                                If a cursor is deemed invalid by the
                                command responder and it is impossible for
                                it to determine where to start collecting
                                data from, the command responder must do



Wes Hardaker                                                    [Page 9]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                one of two things:

                                  a) if the restartOnInvalidCursor flag is
                                     set, the search operation should be
                                     restarted from the beginning of all
                                     possible data.

                                  b) if the restartOnInvalidCursor flag is
                                     not set, the search operation should
                                     start at the point indicated by the
                                     skip-objects field.

                                As an example cursor, an agent which was
                                merely performing internal Get-Object-PDU
                                translations to a GETNEXT translations
                                might return a cursor containing the BER
                                encoding of the last OID returned within
                                the response.  The next request could
                                merely continue processing using the
                                encoded OID just as if a real GETNEXT had
                                come in.

       flags:                   A flag list indicating particular features
                                to be used when processing the PDU.  The
                                flag values are described elsewhere in
                                this document.

       option-field:            A sequence reserved for future use.
                                Command responders which encounter unknown
                                option types specified in this sequence
                                MUST ignore the data and proceed as if the
                                field itself didn't exist in the request.
                                Future protocol extensions MUST define
                                extensions to be implemented within this
                                sequence in such a way that the option can
                                be safely ignored by implementations which
                                fail to understand it.

                                This field exists in multiple places in
                                the PDU definitions contained within this
                                document.  In all cases, the sequences
                                MUST contain only an OPTION-ized list of
                                parameters to be defined in future
                                documents.  The option index numbers for
                                the sequence will be assigned and
                                administered by IANA.

                                Note: all option-field names in this



Wes Hardaker                                                   [Page 10]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                document are identical, which is purely
                                due to laziness.  They should be different
                                in each occasion within each new PDU type.

       request-base-OID:        The base OID for a given object ot request
                                information from.  For SMIv2 objects, this is
                                either the OID pointing to a table or a
                                particular scalar.

       index-request-list &     These two sequences contain a list of
       column-request-list:     subcomponents to be returned in the
                                response.  IE, what particular data
                                elements should be returned.  If both
                                elements are empty (2 zero-length
                                sequences) then all data for the given
                                object MUST be returned.  Managers SHOULD
                                request accessible indexes elements in the
                                column-request-list if the indexes are
                                accessible and not in the
                                index-request-list.

       index-search-objects &   These two sequences contain a list of
       column-search-objects:   search criteria for the data being
                                requested.  If the object data to be
                                returned does not match the criteria
                                imposed by these restrictions in the
                                request, then it shouldn't be returned.

       index-number:            The index number or column-number of a
       column-number:           given index or column object within a
                                table.  Indexes should count from 1 in the
                                index list for the given object.  The
                                column number should be the assigned
                                number underneath the request-base-OID
                                object.

                                If the dontReturnObjectNumbers is set in
                                the request, the command responder MAY
                                NOT include these fields in the
                                Get-Object-Response-PDU, but the command
                                responder MUST set the bit according to
                                what it actually did.  The command
                                responder MUST include these fields if the
                                request did not have the
                                dontReturnObjectNumbers bit set.

                                Implementations SHOULD use column matching
                                in preference to index matching, and thus



Wes Hardaker                                                   [Page 11]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                index matching SHOULD ONLY be used for
                                external index values which don't have a
                                column number assignment within the
                                object.

       match-type:              Specifies the criteria to be imposed for a
                                given search value.  The criteria types
                                are listed below:

                                  MATCH-TYPE ::= Integer32 {

                                    -- any datatypes:
                                    equals(0),
                                    not-equals(1),

                                    -- numerical only:
                                    lessThan(10),
                                    lessThanOrEqual(11),
                                    greaterThan(12),
                                    greaterThanOrEqual(13),

                                    -- binary comparisons:
                                    regexp(20),
                                    not-regexp(21),

                                    -- ... IANA assigned up to 255
                                    -- enterprise specific:
                                    --    256*EnterpriseID to
                                    --    256*EnterpriseID + 255
                                  }

                                match-type's are intended for simple
                                expressions to help reduce the data sent
                                over the wire.  They are not intended for
                                complex querying which might impose a
                                large burden on the end device who's
                                resources are likely needed for their
                                primary functionality (routing, ...).
                                Multiple match-types within a request are
                                always logically ANDed together.

                                If the returnAllDataOnSearchFailure bit is
                                set, then if a search operation fails due
                                to a condition like an unsupported
                                match-type, all data will be returned as
                                if the search-type operator had always
                                returned "true".  If the
                                returnAllDataOnSearchFailure bit is not



Wes Hardaker                                                   [Page 12]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                set, an unSupportedSearchOperation error
                                condition will be returned in the
                                error-status field of the
                                Get-Object-Response-PDU and the error-index
                                field will be set to the N if this is the
                                Nth search criteria contained within the
                                original Get-Object-PDU.


4.2.  The Get-Object-Response PDU

    This PDU is sent in response to a Get-Object-PDU.

        Get-Object-Response-PDU ::= {
           request-id           Integer32,

           response-objects[] ::= {
             {
               error-status               Integer32,
               error-index                Integer32,
               error-string               OCTET STRING,
               cursor                     OCTET STRING,
               flags                      BITS { restartOnInvalidCursor(0),
                                                 returnAllDataOnSearchFailure(1),
                                                 dontReturnObjectNumbers(2),
                                                 containedLastDataObject(3) },
               option-field               {}          -- a sequence
                                                         reserved for future use

               request-base-OID,                      -- (eg, OID for a table)

               data-list[] ::= {
                 index-data-list[] ::= {
                     { index-number         Integer32,          -- ** see below
                       index-value          BER },
                     ...
                 },

                 column-data-list[] ::= {
                     { column-number        Integer32,          -- ** see below
                       column-value         BER },
                     ...
                 }
               }
             }
             ...  -- possibly more response-objects
           }
        }



Wes Hardaker                                                   [Page 13]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    In the above, the following pieces need explaining.  Items in the
    above definition not listed here have been previously described.

       error-status             An error status for the entire request
                                operation, if an error occurred which
                                affected the entire operation.  Agent's
                                SHOULD strive to put exceptions in the
                                data field where possible instead.

       error-index              An index into "something", where
                                "something" is defined by what the
                                error-status field contains (as an
                                example, the unSupportedSearchRange error
                                indicates it's an index into the search
                                objects in the original request).

       error-string             A string describing the particular error.
                                This SHOULD be set to a human readable
                                string describing the problem in greater
                                detail than the error-status field alone
                                can indicate.

       flags                    The flags field MUST be set according to
                                how the response was handled within the
                                responder.  Ideally this should be an
                                exact copy of the flags field from the
                                request, assuming the flags were
                                understood.  Non-understood flags MUST be
                                set to 0 in the response.

                                If the command responder can determine
                                that the last object to be returned within
                                the requested search range is contained
                                within the Get-Object-Response-PDU, then the
                                containedLastDataObject SHOULD be set.

       index-number:            This will be one of:
                                  a) the count of the object into the
                                     INDEX clause of the component for
                                     which the data is being returned if
                                     the dontReturnObjectNumbers flag bit
                                     in the response is 0.
                                  b) If the dontReturnObjectNumbers flag
                                     bit in the request was 1 and the
                                     agent response's sets the
                                     dontReturnObjectNumbers to 1, then
                                     this field is dropped from the
                                     response and only the next field (the



Wes Hardaker                                                   [Page 14]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                     value) is present.

       column-number:           This will be one of:
                                  a) the assigned sub-component number of
                                     the object being returned if the
                                     dontReturnObjectNumbers flag bit in
                                     the response is 0.
                                  b) If the dontReturnObjectNumbers flag
                                     bit in the request was 1 and the
                                     agent response's sets the
                                     dontReturnObjectNumbers to 1, then
                                     this field is dropped from the
                                     response and only the next field (the
                                     value) is present.



4.3.  The Write-Object-PDU

    This Write-Object-PDU is used to update a remote entity with new
    data.

        Write-Object-PDU ::= {
           request-id           Integer32,
           flags                BITS { returnDataOnlyOnError(0) },
           option-field              {}          -- a sequence
                                                    reserved for future use

           set-objects[] ::= {
             {
               transaction-flags          BITS {
                                             needSuccess(0),
                                             needAll(1),
                                             notOrderDependent(2),
                                          },
               option-field               { }        -- a sequence
                                                     reserved for future use

               transaction-data-list[] ::= {
                 choice {
                    create-transaction,
                    modify-transaction,
                    delete-transaction,
                    set-objects                      -- sub-transactions
                    -- iana assigned extensions here?
                 }, ...
               }
             }



Wes Hardaker                                                   [Page 15]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


             ...  -- possibly more set-objects
           }
        }

        -- creates new rows.  error condition if indexes or required
        -- columns aren't complete.
        create-transaction ::= {
            request-base-OID,                      -- (eg, OID for a table)

            index-data-list[] ::= {
                { index-number        Integer32,
                  index-value         BER },
                ...
            }

            column-data-list[] ::= {
                { column-number        Integer32,
                  column-value         BER },
                ...
            }
        }

        -- modifies existing rows based on search criteria.
        -- error condition on any modification failure.
        modify-transaction ::= {
            request-base-OID,                      -- (eg, OID for a table)

            index-search-objects[] ::= {
                { index-number         Integer32,
                  match-type           MATCH-TYPE,
                  index-search-value   BER },
                ...
            },

            column-search-objects[] ::= {
                { column-number        Integer32,
                  match-type           MATCH-TYPE,
                  column-search-value  BER },
                ...
            }

            column-data-list[] ::= {
                { column-number        Integer32,          -- ** see below
                  column-value         BER },
                ...
            }
        }




Wes Hardaker                                                   [Page 16]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


        -- deletes existing rows based on search criteria.
        -- error condition on any
        delete-transaction ::= {
            request-base-OID,                      -- (eg, OID for a table)

            index-search-objects[] ::= {
                { index-number         Integer32,
                  match-type           MATCH-TYPE,
                  index-search-value   BER },
                ...
            },

            column-search-objects[] ::= {
                { column-number        Integer32,
                  match-type           MATCH-TYPE,
                  column-search-value  BER },
                ...
            }
        }

    In the above, the following pieces need explaining:

       flags                    Global flags to apply to the entire PDU.
                                If the returnDataOnlyOnError bit is set,
                                then the Write-Object-Response-PDU will
                                only contain a duplicate set-objects
                                portion of the message if there was an
                                error somewhere in the processing of the
                                message, otherwise the objects will be
                                truncated.  Command Responder
                                implementations SHOULD support this flag,
                                but if for any reason they decide to
                                return the set-objects data portion of the
                                message they MUST NOT set the
                                returnDataOnlyOnError bit.

       transaction-flags:       Flags which apply to each sub-element of
                                the transaction to be performed.
                                Currently there are 3 bits to define
                                transactional processing semantics to be
                                used when processing this message.  These
                                values are described in greater detail in
                                the next section.

       operation:               Indicates what type of operation is to be
                                performed by this transaction set.
                                Specifically:




Wes Hardaker                                                   [Page 17]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


                                    create: creates a new row.  It is to
                                    be considered an error condition if
                                    either the row can not be created or
                                    if the row already existed.

                                    modify: modifies an existing row to
                                    replace some or all of the writable
                                    parameters within the row.  It is an
                                    error condition if the row to be
                                    modified does not exist.

                                    delete: deletes a given row.  If the
                                    row does not exist or can not be
                                    deleted for some reason, it is
                                    considered to be an error condition.
                                    The column-data-list MUST be empty
                                    when transmitting this operation.

       transaction-data-list:   The transaction-data-list contains all of
                                the data to be applied based on the
                                operation choice type.

                                The search criteria imposed by the
                                index-search-objects and
                                column-search-objects are identical in
                                operation to the Get-Object-PDU
                                equivalents, except that instead of
                                requested information back, the
                                column-data field objects should be
                                applied in the case of a create or a
                                modify, or the rows should simply be
                                deleted in the case of a delete.  Unlike
                                the Get-Object-PDU match-type handling, an
                                unsupported match-type will always trigger
                                an error condition.

4.3.1.  Write-Object-PDU transaction semantics

    In short, the flags defining Write-Object semantics can be
    summarized as follows:

     needSuccess
          If the needSuccess bit is turned on, it means that this trans¡
          action is to be considered a failed transaction if during any
          time an error condition occurs.  If at anytime a failure
          occurs when processing the transaction-data-list, the entire
          transaction must be rolled back.




Wes Hardaker                                                   [Page 18]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


     needAll
          If needAll is specified, it means each sub-component in the
          transaction-data-list must be attempted.

     notOrderDependent
          If the notOrderDependent bit is turned on, the transactions
          contained in the transaction-data-list MAY be executed in an
          order, or in parallel.  Note that they must still revert to
          their previous values in an error condition requires a state
          rollback.

In short the following bit combinations are described in combination:

     needSuccess = true, needAll = true:  doAll [doUntilFailure]
          In this case, all contained transactions must succeed.  If any
          failure occurs, the entire set must be rolled back.

     needSuccess = false, needAll = true: tryAll
          With this combination set, the command responder must try to
          achieve all the transactions, however if any fail it is not
          required to roll back the rest of the transactions.  The
          failed transactions themselves, however, must individually
          revert to the before-write state.

     needSuccess = true, needAll = false:  doAtLeastOne  [doUntilSuc¡
          cess]
          In this case, at least one must succeed for the transaction as
          a whole to succeed.  More importantly, if any one transaction
          component does succeed, processing MUST be stopped and the
          transaction as a whole is considered successful.  Another way
          to put it: at most one successful component is executed never
          more than one.

     needSuccess = false, needAll = false:  tryAtLeastOne
          In this case, at least one must succeed for the transaction as
          a whole to succeed.  More importantly, if any one transaction
          component does succeed, processing MUST be stopped and the
          transaction as a whole is considered successful.  Another way
          to put it: at most one successful component is executed never
          more than one.  However, in this case even if none of the
          transaction components succeeds, the transaction as a whole is
          still considered successful.  It is impossible for a transac¡
          tion of this type to be considered a failure in itself.

Also, error reporting will always occur on failed objects even if they
don't affect the containing transactions and surrounding transactions.

4.4.  The Write-Object-Response-PDU



Wes Hardaker                                                   [Page 19]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    This Write-Object-Response-PDU returns the results of the Write-
    Object-PDU operation.  Note that more data can be returned in many
    cases when search operations required operations on multiple rows
    based on the search criteria.

        Write-Object-Response-PDU ::= {
           request-id           Integer32,
           flags                BITS { returnDataOnlyOnError(0) },
           option-field              {}          -- a sequence
                                                    reserved for future use

           set-objects-response[] ::= {
             {
               error-status               Integer32,  -- will include "tooComplex"
               error-index                Integer32,
               error-string               OCTET STRING,
               transaction-flags          BITS {
                                             needSuccess(0),
                                             needAll(1),
                                             notOrderDependent(2),
                                          },
               option-field               { }        -- a sequence
                                                     reserved for future use

               transaction-response-list[] ::= {
                 choice {
                    create-transaction-response,
                    modify-transaction-response,
                    delete-transaction-response,
                    set-objects-response              -- sub-transactions
                    -- iana assigned extensions here?
                 }, ...
               }
             }
             ...  -- possibly more set-objects
           }
        }

        -- duplication of the original requested creation.
        create-transaction-response ::= {
            request-base-OID,                      -- (eg, OID for a table)

            index-data-list[] ::= {
                { index-number        Integer32,
                  index-value         BER },
                ...
            }




Wes Hardaker                                                   [Page 20]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


            column-data-list[] ::= {
                { column-number        Integer32,
                  column-value         BER },
                ...
            }
        }

        -- returns all indexes for all rows affected by the modification request
        -- note that the return is a array, but the request was not.  IE,
        -- all objects which were operated on are returned.
        modify-transaction-response[] ::= { {
            request-base-OID,                      -- (eg, OID for a table)

            index-data-list[] ::= {
                { index-number         Integer32,          -- ** see below
                  index-value          BER },
                ...
            },

            column-data-list[] ::= {
                { column-number        Integer32,          -- ** see below
                  column-value         BER },
                ...
            }
        } }

        -- returns all indexes for all rows affected by the deletion request
        -- note that the return is a array, but the request was not.  IE,
        -- all objects which were operated on are returned.
        delete-transaction ::= {
            request-base-OID,                      -- (eg, OID for a table)

            index-data-list[] ::= {
                { index-number         Integer32,          -- ** see below
                  index-value          BER },
                ...
            }
        }

5.  ASN.1 definitions for the PDUs

    To be defined at a later date.









Wes Hardaker                                                   [Page 21]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


6.  Examples

    Here are some example requests and responses of data retrieval (I
    didn't have time to put in Write examples).  In each case, the curly
    brases indicate a sequence of some kind within BER (in the case of
    index lists, they'd be a application taged sequence as opposed to
    the normal BER sequence).

6.1.  Retrieve a specific row from the ifTable

    This example retrieves the ifDescr and ifType columns for the 5th
    interface from the ifTable

    The Request:

       Get-Object-PDU {
         request-id              1
         request-objects ::= { {
           max-return-objects    0              -- get all
           skip-objects          0              -- starting with the first
           cursor                ""             -- 0 length for first request
           flags                 0              -- none specified.
           option-field          {}

           request-base-object ::= OID:ifTable

           index-request-list  ::= {}
           column-request-list ::= {2, 3}           -- ifDescr, ifType

           index-search-objects ::= {
              { index-number       = 1,             -- ifIndex
                match-type         = 0,             -- equals
                index-search-value = 5 }            -- the fifth
           }

           column-search-objects ::= { }            -- none
        } }
      }

    The Response:

       Get-Object-Response-PDU {
         request-id              1
         response-objects ::= { {
           error-status    0              -- noError
           error-index     0              -- must be 0 if noError
           error-string    ""
           cursor          "interface 5"  -- agent implementation cursor.



Wes Hardaker                                                   [Page 22]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


           flags           0              -- none specified.
           option-field    {}

           request-base-object ::= OID:ifTable

           data-list ::= { {
             index-data-list ::= { }                    -- none were requested

             column-data-list ::= {
               { column-number = 2,
                 column-value  = "interface 5" },
               { column-number = 3,
                 column-value  = 6 }                    -- ethernetCsmacd
             }
           } }
         } }
       }


6.2.  A multiple-packet example with a double filter.

    This example shows the retrieval of the elements of the ifTable
    which are of type "ethernetCsmacd" and have a ifSpeed >= 10,000,000
    bps.  Retrieve only 1 row at a time.  Note that the response has the
    objects returned in the order the remote agent specified [interface
    12, then interface 5], not in something that would map to the older-
    style lexographical ordering.  The order returned must be consistent
    from one request to the next, but the manner in which the ordering
    is accomplished is ipmlementation specific.  The cursor is used to
    indicate to the base agent where the request should restart from.
    Also, the dontReturnObjectNumbers bit is specified, which means the
    returned response should not include the component numbering fields
    and that the manager will remember what the original request was in
    order to understand the response.
    The first request:

       Get-Object-PDU {
         request-id              2
         request-objects ::= { {
           max-return-objects    1              -- only return 1
           skip-objects          0              -- starting with the first
           cursor                ""             -- 0 length for first request
           flags                 { dontReturnObjectNumbers }
           option-field          {}

           request-base-object ::= OID:ifTable

           index-request-list  ::= {}               -- none



Wes Hardaker                                                   [Page 23]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


           column-request-list ::= {1, 2, 3}        -- ifIndex, ifDescr, ifType

           index-search-objects ::= { }             -- none

           column-search-objects ::= {
                   { column-number        = 3,      -- ifType
                     match-type           = 0,      -- equals
                     column-search-value  = 6 },    -- ethernetCsmacd
                   { column-number        = 5,      -- ifSpeed
                     match-type           = 12,     -- greaterThanOrEqual
                     column-search-value  = 10000000 }, -- 10 Mbps
           }
        } }
      }

    The first response:

       Get-Object-Response-PDU {
         request-id              2
         response-objects ::= { {
           error-status    0              -- noError
           error-index     0              -- must be 0 if noError
           error-string    ""
           cursor          "interface 12" -- agent implementation cursor.
           flags           { dontReturnObjectNumbers }
           option-field          {}

           request-base-object ::= OID:ifTable

           data-list ::= { {
             index-data-list ::= { }                    -- none requested

             column-data-list ::= {
               { column-value  = 12 }                   -- ifIndex = 12
               { column-value  = "interface 12" },      -- idDescr
               { column-value  = 100000000 }           -- ifSpeed = 100Mbs
             }
           } }
         } }
       }

    The second request to obtain the rest of the data:

       Get-Object-PDU {
         request-id              2
         request-objects ::= { {
           max-return-objects    1              -- only return 1
           skip-objects          0              -- functionally not used



Wes Hardaker                                                   [Page 24]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


           cursor                "interface 12" -- cursor where we left off at
           flags                 { dontReturnObjectNumbers }
           option-field          {}

           request-base-object ::= OID:ifTable

           index-request-list  ::= {}               -- none
           column-request-list ::= {1, 2, 5}        -- ifIndex, ifDescr, ifSpeed

           index-search-objects ::= { }             -- none

           column-search-objects ::= {
                   { column-number        = 3,      -- ifType
                     match-type           = 0,      -- equals
                     column-search-value  = 6 },    -- ethernetCsmacd
                   { column-number        = 5,      -- ifSpeed
                     match-type           = 12,     -- greaterThanOrEqual
                     column-search-value  = 10000000 }, -- 10 Mbps
           }
        } }
      }

    The second response:

       Get-Object-Response-PDU {
         request-id              2
         response-objects ::= { {
           error-status    0              -- noError
           error-index     0              -- must be 0 if noError
           error-string    ""
           cursor          "interface 5"  -- agent implementation cursor.
           flags                 { dontReturnObjectNumbers }
           option-field          {}

           request-base-object ::= OID:ifTable

           data-list ::= { {
             index-data-list ::= { }                    -- none requested

             column-data-list ::= {
               { column-value  = 5 }                   -- ifIndex = 5
               { column-value  = "interface 5" },      -- idDescr
               { column-value  = 100000000 }           -- ifSpeed = 100Mbs
             }
           } }
         } }
       }




Wes Hardaker                                                   [Page 25]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


7.  Elements of Procedure.

    To be done...

8.  Design Considerations and Questions

    A lot of thought has gone into the PDUs defined in this document.
    I've tried to achieve a balance between flexibility and interoper¡
    ability that will lean toward interoperability most of the time.
    Comments welcome.  This section describes some of the things that
    I'm still thinking about and would like feedback on.

8.1.  Return-field ranges

    Currently the list of columns/indexes to return contains only a list
    of integers, which could be long if you needed every column from
    1-25 but not 26-30, for example.  Should we support the notion of
    "1-25" and if we do, should we only support ranges or should we try
    and mix and match.  IE, how do you expresss "1-10 and 15 and 20-30":
      a) 1,10,15,15,20,30
      b) {1,10},15,{20,30}           {}s would have to specially tagged sequences
      c) 1,2,3,...,10,15,20,21,...,30

8.2.  Write-Object-PDU complexity

    In the long run, I made the Write-Object-PDU more powerful than I
    was originally thinking.  It took me a while to decide what to do,
    but the more I thought about it the processing of the requests con¡
    tained within will not be that difficult.  Specifically, the opera¡
    tions are very recursive in nature and the complexity when dealing
    with one specific component is isolated.  Rollback to some extent is
    still going to be necessary, but the PDU likely reduces the amount
    of UNDO processing due to the fact that you can encode failure cases
    which may be known to be problematic and can be ignored.

    I debated for a while whether to put create/delete/modify transac¡
    tions with the same request, but I've come to believe that it's very
    necessary.  Specifically, it's likely that you'll only want to
    delete a row if and only if the creation of another row succeeds.
    If either of these fail, then the entire transaction should fail
    else the box may be left in an un-usable state.  However, there are
    also likely times that they are completely unrelated transactions,
    and thus can be flagged as independent using the needSuccess bit.

    One possible simplification would be to remove the recursiveness of
    the transaction and to leave everything else.  If I were to remove
    anything, this would likely be it.  I don't actually think it'll
    remove processing code within the agent, but it may lead to greater



Wes Hardaker                                                   [Page 26]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    interoperability.  I'm not at all convinced that's the case, how¡
    ever.

8.3.  Get-Object/Write-Object commonality.

    The more I think about it, the more that I'm beginning to lean
    toward the idea that the Get-Object and Write-Object-PDUs should be
    similar in design.  I debated for a long time whether the search
    criteria should go into the Write-Object-PDU or not, and I'm still
    not entirely decided (but it's there now).

    The danger comes in non-equal sign search criteria where you might
    think you know all the data on the far side that you're going to
    operate on, but it turns out that new rows have added by another
    source and thus you might affect a row you didn't otherwise intend
    to.  However, I'm currently leaning toward the thought that the
    power to affect multiple objects with one transaction would be
    greatly beneficial.  It will certainly help scaling with respect to
    management of extremely large networks containing lots of data which
    needs to be modified.

    In either case, it would be highly beneficial to retrieve a list of
    all the rows which were modified, thus the Write-Object transactions
    are designed such that the indexes of all the datasets which have
    been affected by the transaction are returned to the caller.  This
    is one way to check for errors in the case of external modifica¡
    tions.

    So, the real question is: Do we want search criteria in Write-Object
    operations?  I'm still leaning toward yes (even more so after writ¡
    ing this section).

8.4.  Concrete packet formats vs optional field formats.

    Warning: Assumes a lot of knowledge about BER encoding beyond what
    SNMP uses today.  Some background is given, but not as much as is
    probably needed.

    The PDUs defined in this document today aren't described in an ASN.1
    notation yet.  We have a few options when deciding how we want to
    encode them.

    First, ASN.1/BER has the ability to define "optional" fields.  These
    fields simply wouldn't exist in the packet unless they are needed.
    SNMP has traditionally relied on a fixed packet format without
    optional fields.  Breaking from this tradition may provide some
    packet compression and extensibility benefits.  The down side is
    that sequences with enumerated data fields have an extra tag/length



Wes Hardaker                                                   [Page 27]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    wrapper around each component within a sequence.  (so data within
    becomes: sequence-number-tag length datatype-tag length DATA).  Note
    that you essentially get a minimum of another 2-byte overhead on
    each field within each sequence.

    The optional-field structures within the packet, I think, must be
    defined using these enumerated sequences and everything within must
    be defined as OPTIONAL, or else they may not be expressible in an
    extensible way.

    However, there are some other cases where we may want to adopt this
    style of encoding.  In the above PDUs, the following components are
    functionally "optional" in nature.  Some are sequences, and having a
    empty sequence is functionally equivalent to an optional set of
    data.  However, if truly marked as OPTIONAL then they wouldn't be in
    the packet at all (and the two byte "30 00" empty sequence portion
    wouldn't be encoded):

      Get-Object-PDU:
        index-request-list
        column-request-list
        index-search-objects
        column-search-objects
        option-field
        match-type                          -- missing is =

      Get-Object-Response-PDU:
        error-status                        -- if missing, no error!
        error-index
        error-string
        option-field
        index-number
        column-number

      Write-Object-PDU:
        index-search-objects
        column-search-objects
        option-field
        match-type                          -- missing is =

    I don't think we should mix and match encoding styles.  IE, we
    should probably pick whether we going to do enumerated sequences for
    every portion of the packet (suffering the two-byte-minimum overhead
    on each portion) or not do it at all.  Anyone have preferences?

8.5.  Push Button Functionality.

    SNMP usage has proven that method invocation is needed within the



Wes Hardaker                                                   [Page 28]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    protocol.  The SET semantics and Write-Object semantics do not make
    this easy.  Should a "invocation" write method be put in here now,
    even though we don't have a SMI that can define it's usage yet?

9.  Author's Addresses:

    Wes Hardaker
    P.O. Box 382
    Davis, CA  95617
    Email: hardaker@tislabs.com

10.  References

    [OPREQ]  Woodcock, D., "Operator Requirements of Infrastructure Management
         Methods", Internet Draft draft-ops-operator-req-mgmt-02.txt,
         expired August 2002.

11.  Full Copyright Statement

    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 develop¡
    ing 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.

12.  Humor

    GOP GORP?
    WOP WORP.



Wes Hardaker                                                   [Page 29]


INTERNET-DRAFT       Object Oriented PDU's for SNMP                Sep. 2002


    NOP NORP!


















































Wes Hardaker                                                   [Page 30]