Cable Device MIB -10 text for discussion

Folks,

Kevin Marez and I have been working on an update to the Cable Device
MIB. We were unable to make the July 18th draft submission cut-off, but
we are posting a "-10" version on the www.ipcdn.org for review by the
working group, our MIB doctor (Randy Presuhn), and our Area
Director/Advisor (Bert Wijnen).

Below are links to the XML version, TXT version, and diffs,
respectively:
<http://www.ipcdn.org/drafts/draft-ietf-ipcdn-device-mibv2-10-discussion
.xml>
<http://www.ipcdn.org/drafts/draft-ietf-ipcdn-device-mibv2-10-discussion
.txt>
<http://www.ipcdn.org/drafts/draft-ietf-ipcdn-device-mibv2.diffs.txt>

There are four significant discussion points remaining in this draft,
based on our understanding of the last MIB doctor review.

Below are the key MIB objects followed by MIB doctor comments and author
comments.

1.

docsDevNmAccessInterfaces OBJECT-TYPE
        SYNTAX      OCTET STRING (SIZE (1..32))
        MAX-ACCESS  read-create
        STATUS      deprecated
        DESCRIPTION
            "Specifies the set of interfaces from which requests from
             this NMS will be accepted.  Each octet within
             the value of this object specifies a set of eight
             interfaces, with the first octet specifying ports 1
             through 8, the second octet specifying interfaces 9
             through 16, etc.  Within each octet, the most
             significant bit represents the lowest numbered
             interface, and the least significant bit represents the
             highest numbered interface.  Thus, each interface is
             represented by a single bit within the value of this
             object.  If that bit has a value of '1' then that
             interface is included in the set.

             Note that entries in this table apply only to link-layer
             interfaces (e.g., Ethernet and CATV MAC).  Bits
             representing upstream and downstream channel interfaces
             MUST NOT be set to '1'.

             Note that according to the DOCSIS OSSIv1.1
             specification, when ifIndex '1' is included in the
             set, then this row applies to all CPE
             (customer-facing) interfaces.

             The size of this object is the minimum required to
             represent all configured interfaces for this device."
        DEFVAL { '80000000'h }
        ::= { docsDevNmAccessEntry 6 }

-- Randy comments:
--> The default value given here looks odd.  Do you *really*
-- intend for the default value to be four bytes long, and, according
-- to the DESCRIPTION clause, to refer to interface number
-- thirty-two?
--> In the DESCRIPTION, where it says:
--           Note that entries in this table apply only to link-layer
--           interfaces (e.g., Ethernet and CATV MAC).  Upstream and
--           downstream channel interfaces must not be specified.
-- Is the "must not" intended to be "MUST NOT"?  Does "specified"
-- mean "the corresponding bit set to one" if an interface number
-- exists for that interface?
-- When it says "The size of this object is the minimum required to
-- represent all configured interfaces for this device", several
-- questions come to mind.  What happens if a management system
-- attempts to set it to a larger or smaller size?  When the row is
-- being created, how does a management system know what size to use?
-- What value is used for bits corresponding to interfaces that do
-- not exist?
-- As interfaces are added to or removed from the device, do these
-- objects' sizes adjust automatically?  A lot of questions for a
-- deprecated object....
-- [KMarez]  Yes, a lot of questions.  Since the object is
-- deprecated, can we just let this one go?  I think it might be
-- reasonable to address two things though:
--        *  Clarify which octet is the 'first' one.  From left or
--           right?  While this might be implicit, it's probably good
--           to state it.
--        *  Clarify what to do with bits that correspond to
--           non-existent interfaces.
-- [RWoundy] I am sure that the wrong bit was set in the DEFVAL
-- (fixed).
--        I don't know how to make the DESCRIPTION any clearer.
--        I'm not sure how to do the wording for the "non-existent
--        interfaces". The general intent is that if an octet is
--        missing from the value of this object, then that octet
--        implicitly has the value '0' for all bits.

2.

docsDevNmAccessStatus OBJECT-TYPE
        SYNTAX      RowStatus
        MAX-ACCESS  read-create
        STATUS      deprecated
        DESCRIPTION
            "Controls and reflects the status of rows in this
             table.  Rows in this table may be created by either the
             create-and-go or create-and-wait paradigms.  There is no
             restriction on changing values in a row of this table
             while the row is active.

             The following objects MUST have valid values before this
             object can be set to active:  docsDevNmAccessIp,
             docsDevNmAccessStatus, docsDevNmAccessIpMask,
             docsDevNmAccessCommunity, docsDevNmAccessControl and
             docsDevNmAccessInterfaces."
        ::= { docsDevNmAccessEntry 7 }

-- Randy comments:
-- For docsDevNmAccessStatus, docsDevFilterLLCStatus,
-- docsDevFilterIpStatus, docsDevFilterPolicyStatus,
-- docsDevFilterTosStatus, docsDevCpeInetRowStatus, review guidelines
-- page 23 requires:
--   - The DESCRIPTION clause of the status column MUST specify which
--     columnar objects (if any) have to be set to valid values
--     before the row can be activated.  If any objects in cascading
--     tables have to be populated with related data before the row
--     can be activated, then this MUST also be specified.
-- docsDevNmAccessStatus, docsDevFilterLLCStatus,
-- docsDevFilterIpStatus, docsDevFilterPolicyStatus,
-- docsDevFilterTosStatus, docsDevCpeStatus,
-- docsDevCpeInetRowStatus, do not mention whether the agent can
-- create or destroy rows on its own. page 23 of the guidelines says:
--   - If the agent itself may also create and/or delete rows, then
--     the conditions under which this can occur MUST be clearly
--     documented in the row object DESCRIPTION clause.
-- consequently, this MIB may be read as not permitting an agent to
-- create or delete rows on its own in these tables.  The text in
-- section 3.3.2.1 that says "the policy for automatically creating
-- filters in those tables is controlled by docsDevCpeEnroll and
-- docsDevMaxCpe as well as the network management agent." makes me
-- think that that is not your intent, in at least some cases.  If
-- so, this is a MUST fix.
-- [KMarez]  I added text to address specifying which columnar
-- objects have to be set before the the row can be activated.  It
-- appears that docsDevFilterIpStatus and
-- docsDevFilterTosStatus actually covered that MUST.
-- You may want to confirm the others.
-- [RWoundy] My presumption is that docsDevEvControlTable rows with
-- local(0) reporting MUST persist across reboots on cable
-- modems, and all other tables on cable modems (e.g.
-- docsDevNmAccess, docsDevFilterLLC, docsDevFilterIp,
-- docsDevFilterPolicy, docsDevFilterTos, docsDevCpeInet) MUST NOT
-- persist across reboots on cable modems. Probably should be
-- discussed in the WG.
-- Also, we should change the DESCRIPTION of docsDevCpeStatus
-- and docsDevCpeInetRowStatus to document how the agent adds rows.

3.

docsDevEvReporting OBJECT-TYPE
        SYNTAX BITS {
            local(0),
            traps(1),
            syslog(2),
            localVolatile(8),
            stdInterface(9)
        }
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "Defines the action to be taken on occurrence of this
             event class.  Implementations may not necessarily
             support all options for all event classes, but at
             minimum must allow traps and syslogging to be
             disabled.

             If the local(0) bit is set, then log to the internal
             log and update non-volatile store, for backward
             compatibility with the original RFC 2669 definition.
             If the traps(1) bit is set, then generate
             an SNMP trap, and if the syslog(2) bit is set, then
             send a syslog message (assuming the syslog address
             is set).  If the localVolatile(8) bit is set, then
             log to the internal log without updating non-volatile
             store.  If the stdInterface(9) bit is set, then the
             agent ignores all other bits except the local(0),
             syslog(2) and localVolatile(8) bits.  Setting the
             stdInterface(9) bit indicates that RFC3413 and
             RFC3014 are being used to control event reporting
             mechanisms.
                
             Any attempt to SET the traps(1) or syslog(2) bits
             without setting the local(0) or localVolatile(8)
             bits MUST result in an error being generated."
        ::= { docsDevEvControlEntry 2 }

-- Randy comments:
-->  I'm puzzled by this addition:
--           Any attempt to SET the traps(1) or syslog(2) bits
--           without setting the local(0) or localVolatile(8)
--           bits MUST result in an error being generated."
--      Where did this come from?
-- [KMarez]  I've no idea where this came from either.  I cleaned
-- up the wording a bit on it, but the text was there in the
-- -06 version that I got from Rich.
-- [RWoundy] I don't remember exactly where this came from,
-- either. I think the concern was that there is information
-- captured in the docsDevEventTable that may not be
-- reflected in either SNMP PDUs or SYSLOG messages, and
-- that with the advent of localVolatile(8) logging
-- there is no implementation barrier to capturing all
-- events in docsDevEventTable.

4.

docsDevFilterLLCTable OBJECT-TYPE
        SYNTAX      SEQUENCE OF DocsDevFilterLLCEntry
        MAX-ACCESS  not-accessible
        STATUS      current
        DESCRIPTION
            "A list of filters to apply to (bridged) LLC
             traffic.  The filters in this table are applied to
             incoming traffic on the appropriate interface(s)  prior
             to any further processing (e.g. before handing the
             packet off for level 3 processing, or for bridging).
             The specific action taken when no filter is matched is
             controlled by docsDevFilterLLCUnmatchedAction.  Table
             entries MAY persist across reboots for any device."
        ::= { docsDevFilter 2 }

-- Randy comments:
--> the added text "Table entries are not required to persist
-- across reboots for any device." is a little odd.  More RFC
-- 2119-like would be something like "Table entries MAY persist
-- across reboots for any device" or "Persistance of table entries
-- across reboots is OPTIONAL for all devices."  (Whether this
-- optionality would be a good thing is a separate discussion.)
-- [KMarez] Done.
-- [RWoundy]
--> My presumption is we should say here, "Table entries MUST NOT
-- persist across reboots for cable modems." I think this requirement
-- needs to be applied to NmAccess, FilterLLC, FilterIp, Policy, Tos,
-- Cpe and InetCpe tables. This may require more discussion.


-- Rich