Expert review comments on draft-ietf-ipcdn-docsisevent-mib-03

Folks,

Here are the expert review comments from Harrie on the docsis event mib draft 03. 
Special thanks to Harrie for the detailed review (and the comprehensive list of editorial comments). Upon resolution of the one technical issue you raised around the design choice of notifications, it is our intent to update the draft and request IETF Publication.

>From a WG prospective, so far, we've had expert review comments from David Raftus and Harrie Hazewinkel on this draft. I have not received any other volunteers and I would like to extend the period comment for 1 more week. Send any additional comments on the draft by Thursday 6/17 8am PT.

Jean-François 
-----Original Message-----
From: Harrie Hazewinkel [mailto:[email protected]] 
Sent: Wednesday, June 09, 2004 4:03 AM
To: Jean-Francois Mule
Cc: [email protected]; Raftus, David; Greg Nakanishi (E-mail); Azlina Ahmad (E-mail); Richard Woundy @ Comcast
Subject: Re: Any status on review ofdraft-ietf-ipcdn-docsisevent-mib-03.txt ?


Hi,

My review of the docsisevent-mib.
[snip]

regards,
Harrie
>   Event Notification Management Information Base for DOCSIS Compliant
>             Cable Modems and Cable Modem Termination Systems
>                   draft-ietf-ipcdn-docsisevent-mib-03

> Abstract
> 
>    This memo defines a portion of the Management Information Base (MIB)
>    for use with network management protocols in the Internet community.
>    In particular, it defines a basic set of managed objects for SNMP-
>    based event notification management of DOCSIS compliant Cable Modems
>    and Cable Modem Termination Systems. This MIB is defined as an
>    extension to the DOCSIS Cable Device MIB, RFC 2669 [5].


Reference in abstract is not allowed according to RFC editor. If I understand it.
> 2. Glossary
> 
>    The terms in this document are derived either from normal cable
>    system usage, or from the documents associated with the Data Over
>    Cable Service Interface Specification (DOCSIS) process.
> 
> 2.1 BPI - Baseline Privacy Interface
> 
>    A term referring to the DOCSIS [7] for enabling simple data privacy
>    in the DOCSIS 1.0 system.
> 
> 2.2 BPI - Baseline Privacy Plus Interface
> 
>    A term referring to the DOCSIS [8] for enabling CM authentication and
>    data privacy in the DOCSIS 1.1 system.




I presume you the 2 above stated terms are attempted to be described briefly. I am not getting any of it. 'A term referring to the DOCSIS for enabling....' 
1) I already know it is a term. :-)
2) Without the reference it looses all info.

Upon rereading, they are the same, with a different explaination. :-)

> 2.6 DOCSIS
> 
>    "Data-Over-Cable Service Interface Specifications".  A term 
> referring




   "Data-Over-Cable Service Interface Specifications".  A term referring

change (to make it a sentence)

   DOCSIS stands for "Data-Over-Cable Service Interface Specifications" and refers
>    to the ITU-T J.112 Annex B standard for cable modem systems [12]
>    commonly known as DOCSIS 1.0.  The DOCSIS 1.1 specification is an
>    extension of DOCSIS 1.0, with new features to support quality of
>    service, fragmentation, and requirements for European cable plants
>    [13].
> 
>    DOCSIS 2.0 [14] builds upon DOCSIS 1.1, and provides all of the
>    features and functionality that DOCSIS 1.1 provides. In addition, it
>    provides some significant enhancements in upstream capacity over
>    DOCSIS 1.1. such as 30.72 Mbps maximum upstream channel capacity,



OLD:
DOCSIS 1.1. such as

NEW:
DOCSIS 1.1, such as
>    Synchronous-Code Division Multiple Access (CDMA) operation, increased
>    robustness to upstream noise and channel impairments, Enhanced
>    Reed-Solomon error correction, and Trellis Coded Modulation.



OLD:
correction and Trellis Coded Modulation.

NEW (elements of style by RFC-editor):
correction and, Trellis Coded Modulation.

> 2.12 Upstream
> 
>    The direction from the subscriber towards the head-end.



SUBJECTIVE:
Is the term subscriber not needed as definition?

Quit clear, but to be complete.
> 3. Overview
> 
>    High Speed Internet Service offering in cable industry has become
> 
> 
> 
> Ahmad/Nakanishi         Expires May 31, 2004                  [Page 4]
> 
> 
> Internet-Draft           Event Notification MIB            December 2003
> 
> 
>    extremely successful. DOCSIS devices including CM and CMTS are 
> being



SUBJECTIVE:
OLD:
DOCSIS devices including CM and CMTS are being


NEW:
DOCSIS devices are being

>    deployed at a rate of multiple thousands per day. Although operators
>    are enjoying successful deployment, they are also facing a challenge
>    to properly manage deployed devices.  Operators are using Simple
>    Network Management Protocol, a set of Management Information Base
>    (MIB) required by DOCSIS, and SNMP Traps to manage deployed DOCSIS

OLD:
DOCSIS, and SNMP Traps

NEW:
DOCSIS, and SNMP Notifications



>    devices.  The usage of SNMP Trap for event reporting is becoming more
>    popular as an effective and efficient method for network 
> monitoring.
> 
>    Unfortunately, only a minimal set of SNMP Traps is currently

OLD:
SNMP Traps

NEW:
SNMP Notifications

>    available. This notification MIB in conjunction with [10] and [11]
>    provide a minimum set of standard DOCSIS Traps that DOCSIS devices

OLD:
DOCSIS Traps

NEW:
SNMP Notifications


NOTE: The notifications are DOCSIS related, but are SNMP.
>    will support to enable successful management of DOCSIS devices and



OLD:
will support

NEW:
SHOULD support
>    network.
> 
>    This document defines a set of objects required for the event
>    notification management of DOCSIS compliant Cable Modems (CMs) and
>    Cable Modem Termination Systems (CMTSs). The specification is 
> derived




What specification? Be more specific, since DOCSIS itself is also a specification and I believe you mean the MIB module.
>    from the DOCSIS [10] and [11].
> 
>    The Appendix H of [10] defines all DOCSIS 1.1 required events and the
>    Appendix D of [11] does that for DOCSIS 2.0.  The notifications
>    specified in this document are used to notify these events via 
> SNMP.
> 
>    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 RFC 2119 [1].
> 
> 3.1 Structure of the MIB
> 
>    This DOCS-IETF-CABLE-DEVICE-TRAP-MIB was designed to extend the
>    RFC2669 [5] notification module.




Why DOCS and not DOCSIS? I understand the length of 32 is
the limit, but DOCSIS seems to me quit an important prefix part.
>    Two groups of SNMP notification objects are defined in this document.
>    One group defines notifications for cable modem events, and the other
>    group defines notifications for cable modem termination system
>    events.
> 
>    Common to all CM notification objects (traps) is that in their
>    OBJECTS statements, a CM trap contains information about the event
>    priority, the event Id, the event message body, the CM DOCSIS



I have some difficulty to understand what you mean by the event message body. Would that be some kind of description? If so, I would suggest adjusting the naming.
>    capability, the CM DOCSIS register status, the cable interface MAC
>    address of the cable modem and the CMTS cable card MAC address to



OLD:
the cable modem and the CMTS

NEW (elements of style by RFC-editor):
the calbe modem and, the CMTS

> 3.1.1 Event Throttling
> 
>    SNMP event throttling is controlled as described in RFC 2669 [5].




Maybe so, but how does it relate to this MIB?
> 4. Definitions
> 
>    DOCS-IETF-CABLE-DEVICE-TRAP-MIB DEFINITIONS ::= BEGIN
> 
>      IMPORTS
>            MODULE-IDENTITY,
>            OBJECT-TYPE,
>            NOTIFICATION-TYPE,
>            mib-2
>            FROM SNMPv2-SMI




Add RFC as comment, like (nit: use also same indent as below):

FROM SNMPv2-SMI  -- RFC 2578
>            MODULE-COMPLIANCE,
>            OBJECT-GROUP,
>            NOTIFICATION-GROUP
>                  FROM SNMPv2-CONF



Add RFC as comment.
OLD:
FROM SNMPv2-CONF

NEW:
FROM SNMPv2-CONF   -- RFC 2580
>            docsDevEvLevel,
>            docsDevEvId,
>            docsDevEvText,
>            docsDevSwFilename,
>            docsDevSwServer,
>            docsDevServerDhcp,
>            docsDevServerTime
>                  FROM DOCS-CABLE-DEVICE-MIB --RFC 2669
> 
>            docsIfCmCmtsAddress,
>            docsIfCmtsCmStatusMacAddress,
>            docsIfDocsisBaseCapability,
>            docsIfCmStatusDocsisOperMode,
>            docsIfCmStatusModulationType,
>            docsIfCmtsCmStatusDocsisRegMode,
>            docsIfCmtsCmStatusModulationType
>                  FROM DOCS-IF-MIB -- draft-ietf-ipcdn-docs-rfmibv2-08



Is an RFC-editor note not needed here. I presume this MIB will not go forward as the DOCS-IF-MIB goes as well. Therefore, a note is in order to make sure the reference gets replaced.

(Some for reference)
>            ifPhysAddress
>                  FROM IF-MIB;




Add RFC as comment.
OLD:
FROM IF-MIB

FROM IF-MIB  -- RFC 2863
>      docsDevTrapMIB MODULE-IDENTITY

....
>            DESCRIPTION
>                "The Event Notification MIB is an extension of the
>                 CABLE DEVICE MIB defined in RFC 2669. It defines various
>                 trap objects for both cable modem and cable modem
>                 termination systems. Two groups of SNMP notification
>                 objects are defined. One group is for notifying cable
>                 modem events and one group for notifying cable modem
>                 termination system events. Common to all CM
>                 notification objects (traps) is that their OBJECTS
>                 statements contain information about the event priority,
>                 the event Id, the event message body, the CM DOCSIS
>                 capability, the CM DOCSIS QOS level, the CM DOCSIS
>                 upstream modulation type, the cable interface MAC
>                 address of the cable modem and the cable card MAC 
> address



OLD:
the cable modem and the CMTS

NEW (elements of style by RFC-editor):
the cable modem and, the cable card

Not this is slightly different as in the text before.
>                 of the CMTS to which the modem is connected.
> 
>                 These objects are docsDevEvLevel, docsDevId,
>                 docsDevEvText, docsIfDocsisBaseCapability,
>                 docsIfCmStatusDocsisOperMode, docsIfCmStatusModulationType
>                 ifPhysAddress and docsIfCmCmtsAddress. The values of



OLD:
ifPhysAddress and docsIfCmCmtsAddress

NEW (elements of style by RFC-editor):
ifPhysAddress and, docsIfCmCmtsAddress
>                 docsDevEvLevel, docsDevId, and docsDevEvText are from 
> the


OLD:
docsDevEvLevel, docsDevId, and docsDevEvText 

NEW (elements of style by RFC-editor):
docsDevEvLevel, docsDevId and, docsDevEvText 
>                 entry which logs this event in the docsDevEventTable,
>                 which is defined in DOCS-CABLE-DEVICE-MIB of RFC 2669. The
>                 docsIfDocsisBaseCapability, docsIfCmStatusDocsisOperMode,
>                 and docsIfCmStatusModulationType are defined in the
>                 DOCS-IF-MIB.  The ifPhysAddress value is the MAC address
>                 Of the cable interface of this cable modem. The
>                 docsIfCmCmtsAddress specifies the MAC address of the 
> CMTS
> 
> 
> 
> Ahmad/Nakanishi         Expires May 31, 2004                  [Page 7]
> 
> 
> Internet-Draft           Event Notification MIB            December 2003
> 
> 
>                (if there is a cable card/ interface in the CMTS, then it
>                 is actually the cable interface interface MAC address to
>                 which the CM is connected).  Individual CM trap may
>                 contain additional objects to provide necessary
>                 information.
> 
>                 Common to all CMTS notification objects (traps) is that
>                 their OBJECTS statements contain information about the
>                 event priority, the event Id, the event message body,
>                 the connected CM DOCSIS QOS status, the connected CM
>                 DOCSIS modulation type, the CM cable interface MAC
>                 address, the CMTS DOCSIS capability, and the CMTS MAC



OLD:
 DOCSIS capability, and the

NEW (elements of style by RFC-editor):
 DOCSIS capability and, the
>                 address.
> 
>                 These objects are docsDevEvLevel, docsDevId,



Where does 'These objects are' refer to?
>                 docsDevEvText, docsIfCmtsCmStatusDocsisRegMode,
>                 docsIfCmtsCmStatusModulationType,
>                 docsIfCmtsCmStatusMacAddress,
>                 docsIfDocsisBaseCapability, and ifPhysAddress. The values
>                 of docsDevEvLevel, docsDevId, and docsDevEvText are



OLD:
docsDevId, and docsDevEvText
NEW:
docsDevId and, docsDevEvText
>                 similar to those in CM traps. The values of
>                 docsIfCmtsCmStatusDocsisRegMode,
>                 docsIfCmtsCmStatusModulationType, and



OLD:
docsIfCmtsCmStatusModulationType, and

NEW:
docsIfCmtsCmStatusModulationType and, 
>                 docsIfCmtsCmStatusMacAddress are from the
>                 docsIfCmtsCmStatusEntry (defined in DOCS-IF-MIB)
>                 corresponding
>                 to a connected CM. The docsIfDocsisBaseCapability
>                 indicates the CMTS DOCSIS capability. The ifPhysAddress
>                 value is the CMTS MAC address (if there is a cable card/
>                 interface in the CMTS, then it is actually the MAC
>                 address of the cable interface which connected to the 
> CM).
> 
>                 Copyright (C) The Internet Society (2003). This version
>                 of this MIB module is part of RFC yyyy; see the RFC
>                 itself for full legal notices."
> 
>       -- RFC Ed.: replace yyyy with actual RFC number & remove this 
> note
> 
>            REVISION "200312190000Z" -- December 19, 2003
>            DESCRIPTION
>                "Initial version, published as RFC yyyy."
> 
>       -- RFC Ed.: replace yyyy with actual RFC number & remove this 
> note
> 
>            ::= { mib-2 xx }   -- xx to be assigned by IANA


>    docsDevCmTrapControl OBJECT-TYPE
>        SYNTAX BITS {
>            cmInitTLVUnknownTrap( 0),
>            cmDynServReqFailTrap( 1),
>            cmDynServRspFailTrap( 2),
>            cmDynServAckFailTrap( 3),
>            cmBpiInitTrap( 4),
>            cmBPKMTrap( 5),
>            cmDynamicSATrap( 6),
>            cmDHCPFailTrap( 7),
>            cmSwUpgradeInitTrap( 8),
>            cmSwUpgradeFailTrap( 9),
>            cmSwUpgradeSuccessTrap( 10),
>            cmSwUpgradeCVCTrap( 11),
>            cmTODFailTrap( 12),
>            cmDCCReqFailTrap( 13),
>            cmDCCRspFailTrap( 14),
>            cmDCCAckFailTrap( 15)
>        }
>       MAX-ACCESS read-write
>       STATUS current
>       DESCRIPTION
>           "The object is used to enable CM traps. From left to right,
>            the set bit indicates the corresponding CM trap is enabled.
>            For example, if the first bit is set, then
>            docsDevCmInitTLVUnknownTrap is enabled. If it is null,
>            the trap is disabled.



I am not understanding the 'From left to right,' and 'first bit' 
is this indicate some order? If so, that is better left out, since it is defined by the BER/SNMP itself (already) and it could be interpreted are the bits order in the system (CM). IMHO, also the use of 'null' in combination with bits is weird, use 'not set'.

This is to be repeated for the following definitions with the SYNTAX BITS as well.
>           "
>       DEFVAL { {} }
>       ::= { docsDevTrapControl 1 }

>    docsDevCmInitTLVUnknownTrap NOTIFICATION-TYPE
>        OBJECTS {
>            docsDevEvLevel,
>            docsDevEvId,


Why is this object added? Is this value not retrieved from the OID used for the docsDevEvLevel and docsDevEvText. In that case one can omit it.
>            docsDevEvText,
>            ifPhysAddress,
>            docsIfCmCmtsAddress,
>            docsIfDocsisBaseCapability,
>            docsIfCmStatusDocsisOperMode,
>            docsIfCmStatusModulationType
>        }
>        STATUS current
>        DESCRIPTION
>            "Event due to detection of unknown TLV during
>             the TLV parsing process.



What is a TLV? I would suggest to add this to the glossary.
>             The values of docsDevEvLevel, docsDevId, and
>             docsDevEvText are from the entry which logs this event
>             in the docsDevEventTable.



Are these 3 values uniquely identifying the event? If so, please indicate 
that.
>  The docsIfDocsisBaseCapability
>             indicates the DOCSIS version information.


The DOCSIS version information of what?
>  The
>             docsIfCmStatusDocsisOperMode indicates the QOS level of
>             the CM, while the docsIfCmStatusModulationType indicates
>             the upstream modulation methodology used by the CM.
>             The ifPhysAddress value is the MAC address of the cable
>             interface of this cable modem.
>             The docsIfCmCmtsAddress specifies the MAC address
>             of the CMTS to which the CM is connected to(if there is a cable
>             card/ interface in the CMTS, then it is actually the MAC address
>             of the cable interface which connected to the CM).



If you more or less list here all objects with a short description of what they are, I would suggest ma more 'bullet' oriented approach.
>             This part of information is uniformed across all CM traps.



What is ment by 'uniform accross all CM traps'?
>            "
>        ::= { docsDevCmTraps 1 }

DESIGN-CHOICE
On the design of these notifications I believe there must be made a choice.

1) Or simply repeat the description of the objects of the
first notification in all the others. That way each description is on its own correct.

2) Merge all these notifications into a single notification
and add an extra object specifying the event. Although, I am not sure and therefore I would like to know if the docsDevEvLevel, docsDevEvId and, docsDevEvText already do not describe that.


A justification in the beginning og the document would be useful to lay out the design choice here. And the intended use for the VACM part/filtering of the traps.

I am missing the correct description in which the association is provided between the objects in the notifications. For instance, an event described by docsDevEvLevel, docsDevId and, docsDevEcText i do not understand the  relationship with docsIfDocsisBaseCapability.


Can someone explain me what the real difference in values is between most of the CM oriented notification (I guess the question is also valid for the CMTS).

Most notifications also describe very briefly the event type. For implementors of this MIB it would be helpful to be a bit more descriptive.
>    docsDevCmSwUpgradeInitTrap NOTIFICATION-TYPE
>        OBJECTS {
>            docsDevEvLevel,
>            docsDevEvId,
>            docsDevEvText,
>            ifPhysAddress,
>            docsIfCmCmtsAddress,
>            docsDevSwFilename,
>            docsDevSwServer,
>            docsIfDocsisBaseCapability,
>            docsIfCmStatusDocsisOperMode,
>            docsIfCmStatusModulationType
>        }
>        STATUS current
>        DESCRIPTION
>            "An event to report a software upgrade initiated
>             event.



Weird sentence.
> The values of docsDevSwFilename, and
>             docsDevSwServer indicate the software image name
>             and the server IP address the image is from.



OLD:
is from.

NEW:
is retrieved from.
>            "
>        ::= { docsDevCmTraps 9 }

NOTE:
rest of MIb not really checked due to dependancy of 
previous potential change.
> 6. Acknowledgments
> 
>    This document was produced by the IPCDN Working Group. Special thanks
>    to Rich Woundy, who made several valuable suggestions to improve the
>    traps.

OLD:
traps.

NEW:
notifications.
> 7. Security Consideration
> 
>    There are a number of management objects defined in this MIB module
>    with a MAX-ACCESS clause of read-write and/or read-create.  Such
>    objects may be considered sensitive or vulnerable in some network
>    environments.  The support for SET operations in a non-secure
>    environment without proper protection can have a negative effect on
>    network operations.  These are the tables and objects and their
>    sensitivity/vulnerability:
> 
>    Setting docsDevCmTrapControl or docsDevCmtsTrapControl (defined in
>    RFC 2669) may cause flooding of traps, which can disrupt network

OLD:
traps,

NEW:
notifications,
>    service.
> 
>    This MIB defines a number of notification objects that send detailed
>    information about the event that caused the generation of the
>    notification.  Information included in the notification message
>    include: event priority, the event Id, the event message body, the CM
>    DOCSIS capability, the CM DOCSIS QOS level, the CM DOCSIS upstream
>    modulation type, the cable interface MAC address of the cable modem
>    and the cable card MAC address of the CMTS to which the modem is

OLD:

and the cable

NEW:
and, the cable

>    connected.  The monitoring of these notification messages could be
>    used to gather information about the state of the network and devices
>    (CM and CMTS) attached to the network.
> 
>    SNMP versions prior to SNMPv3 did not include adequate security. Even
>    if the network itself is secure (for example by using IPSec), even
>    then, there is no control as to who on the secure network is allowed
>    to access and GET/SET (read/change/create/delete) the objects in this
>    MIB module.
> 
>    It is RECOMMENDED that implementers consider the security features as
>    provided by the SNMPv3 framework (see [RFC3410], section 8),
>    including full support for the SNMPv3 cryptographic mechanisms (for
>    authentication and privacy).

> Normative References

>    [6]   Raftus, D., "Radio Frequency (RF) Interface Management
>          Information Base for DOCSIS 2.0 compliant RF interfaces",
>          Internet Draft draft-ietf-ipcdn-docs-rfmibv2-08, October 2003.

NOTE: this may need to be updated by RFC-editor.