Re: I-D ACTION:draft-ietf-hubmib-power-ethernet-mib-02.txt

On Wed, 3 Jul 2002 [email protected] wrote:

> A New Internet-Draft is available from the on-line Internet-Drafts
> directories.  This draft is a work item of the Ethernet Interfaces
> and Hub MIB Working Group of the IETF.
> 
> 	Title		: Power Ethernet (DTE Power via MDI) MIB
> 	Author(s)	: A. Berger, D. Romascanu
> 	Filename	: draft-ietf-hubmib-power-ethernet-mib-02.txt
> 	Pages		: 28
> 	Date		: 02-Jul-02
> 	
> This memo defines a portion of the Management Information Base (MIB)
> for use with network management protocols in the Internet community.
> The document proposes an extension to the Ethernet-like Interfaces
> MIB [RFC2665] with a set of objects for managing a power Ethernet
> Powered Device (PD) and/or Power Source Equipment (PSE).
> 
> A URL for this Internet-Draft is:
> http://www.ietf.org/internet-drafts/draft-ietf-hubmib-power-ethernet-mib-02.txt

Greetings,

I have some MIB doctor type comments about this draft.  When I run it through
smilint-0.4.0 with all complaints turned on except for warnings about long
identifier names I get this:

% smilint -l 9 -s ./POWER-ETHERNET-MIB |& egrep -v 'name .* longer than 32 characters$'
./POWER-ETHERNET-MIB:117: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:128: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:375: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:485: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:549: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:561: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:600: [6] use Integer32 instead of INTEGER in SMIv2
./POWER-ETHERNET-MIB:76: [5] index element `pethPsePortGroupIndex' of row `pethPsePortEntry' should be not-accessible in SMIv2 MIB
./POWER-ETHERNET-MIB:76: [5] index element `pethPsePortIndex' of row `pethPsePortEntry' should be not-accessible in SMIv2 MIB
./POWER-ETHERNET-MIB:456: [5] index element `pethMainPseGroupIndex' of row `pethMainPseEntry' should be not-accessible in SMIv2 MIB
./POWER-ETHERNET-MIB:628: [5] notification `pethPsePortOnOffTrap' is not reverse mappable
./POWER-ETHERNET-MIB:637: [5] notification `pethPsePortCurrentStatusTrap' is not reverse mappable
./POWER-ETHERNET-MIB:645: [5] notification `pethMainPseBackUpActivatedTrap' is not reverse mappable
./POWER-ETHERNET-MIB:653: [5] notification `pethMainPowerUsageOnTrap' is not reverse mappable
./POWER-ETHERNET-MIB:661: [5] notification `pethMainPowerUsageOffTrap' is not reverse mappable
./POWER-ETHERNET-MIB:181: [4] node `pethPsePortPowerDetectionControl' must be contained in at least one conformance group
./POWER-ETHERNET-MIB:484: [4] node `pethMainPseGroupIndex' must be contained in at least one conformance group
./POWER-ETHERNET-MIB:670: [6] current group `pethPsePortTrapGroup' is unconditionally optional
./POWER-ETHERNET-MIB:676: [6] current group `pethMainPowerTrapGroup' is unconditionally optional

The complaints about use of INTEGER vs. Integer32, about notifications
being assigned OIDs that preclude a reversible v2 -> v1 transformation,
and about accessible objects not in a conformance group can be dealt with
by some fairly mechanical edits.  Since I've included a context diff below
with explicit suggestions for fixes I won't say anything further about
these matters (note, the context diff has some typo corrections too).

Fixing the complaints about accessible index items is not so mechanical.
It turns out that the objects in question -- pethPsePortGroupIndex,
pethPsePortIndex, and pethMainPseGroupIndex -- are present in the
OBJECTS clause of the notifications, which requires that they be
made accessible.  Although this practice is supported by SMIv2, it
is only supposed to be used when translating legacy MIB modules from
SMIv1 (see RFC 2578, Section 7.7, pp. 28-29 and in particular note (a)
on the top of p. 29).  To remedy this, the following steps are suggested:

(1) Remove the index objects from the OBJECTS clauses.  If the remaining
objects do not contain an accessible column from each of the tables to
which the deleted index objects applied, add one or more such columns
for each such table.  (Note: since the name field of the accessible
column will contain the index values when the notification is sent,
this obviates the need to send the index objects separately.)

(2) Reduce the MAX-ACCESS of the index objects to not-accessible and
remove them from the object groups where they presently appear.

There are two traps where step (1) is not mechanical --
pethMainPowerUsageOnTrap and pethMainPowerUsageOffTrap
currently list only pethMainPseGroupIndex in the OBJECTS
clause.  Perhaps pethMainPseConsumptionPower would be a
suitable column to include.

Before I close I'd like to comment on a few other things.  First,
the two NOTIFICATION-GROUPs appear in the notification definition
section rather than the conformance section and are registered under
the notification OID rather than the conformance OID.  That's not
illegal but it is a bit unusual;  it might be better to follow
established custom of putting them in the conformance section.
Second, these notification groups are not mentioned in any of
the GROUP clauses of the compliance statements, whence the
"unconditionally optional" warning.  It would be better to have a
GROUP clause even if the unconditionally optional status was intended.
Since the pethTrapsControlGroup is mandatory for PSEs, I would suspect
that unconditionally optional status was not intended (and is
inappropriate) for the pethMainPowerTrapGroup.  Finally, the relationship
between pethTrapsControlGroupIndex and pethMainPseGroupIndex needs to be
clarified so that it is clear what the objects in pethTrapsControlTable
actually control (if there is always a 1-1 correspondence between
the rows in the pethTrapsControlTable and the pethMainPseTable then
it would be possible to just put pethTrapsControlEnable into the
pethMainPseTable and eliminate the pethTrapsControlTable).

Regards,

Mike

*** draft-ietf-hubmib-power-ethernet-mib-02.txt	Tue Jul  2 11:13:23 2002
--- draft-ietf-hubmib-power-ethernet-mib-0X.txt	Fri Jul  5 09:23:24 2002
***************
*** 459,465 ****
            DESCRIPTION
                     "The MIB module for for managing Powered Devices (PD) or
                     Power Source Equipment (PSE) working according to the IEEE
!                    802.af Powere Ethernet (DTE Power via MDI) standard.
  
                    The following terms are used throughout this
                    MIB module.  For complete formal definitions,
--- 459,465 ----
            DESCRIPTION
                     "The MIB module for for managing Powered Devices (PD) or
                     Power Source Equipment (PSE) working according to the IEEE
!                    802.af Power Ethernet (DTE Power via MDI) standard.
  
                    The following terms are used throughout this
                    MIB module.  For complete formal definitions,
***************
*** 524,532 ****
  
        PethPsePortEntry ::= SEQUENCE {
            pethPsePortGroupIndex
!              INTEGER,
            pethPsePortIndex
!              INTEGER,
            pethPsePortAdminEnable
                INTEGER,
            pethPsePortPowerPairsControlAbility
--- 524,532 ----
  
        PethPsePortEntry ::= SEQUENCE {
            pethPsePortGroupIndex
!              Integer32,
            pethPsePortIndex
!              Integer32,
            pethPsePortAdminEnable
                INTEGER,
            pethPsePortPowerPairsControlAbility
***************
*** 564,570 ****
        }
  
          pethPsePortGroupIndex OBJECT-TYPE
!           SYNTAX      INTEGER (1..2147483647)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
--- 564,570 ----
        }
  
          pethPsePortGroupIndex OBJECT-TYPE
!           SYNTAX      Integer32 (1..2147483647)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
***************
*** 575,581 ****
            ::= { pethPsePortEntry 1 }
  
          pethPsePortIndex OBJECT-TYPE
!           SYNTAX      INTEGER(1..2147483647)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
--- 575,581 ----
            ::= { pethPsePortEntry 1 }
  
          pethPsePortIndex OBJECT-TYPE
!           SYNTAX      Integer32 (1..2147483647)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
***************
*** 872,878 ****
  
        PethPdPortEntry ::= SEQUENCE {
            pethPdPortIndex
!               INTEGER,
            pethPdPortPowerPairs
                INTEGER,
            pethPdPortDetectionStatus
--- 872,878 ----
  
        PethPdPortEntry ::= SEQUENCE {
            pethPdPortIndex
!               Integer32,
            pethPdPortPowerPairs
                INTEGER,
            pethPdPortDetectionStatus
***************
*** 882,888 ****
        }
  
          pethPdPortIndex OBJECT-TYPE
!           SYNTAX      INTEGER (0..65535)
            MAX-ACCESS  not-accessible
            STATUS      current
            DESCRIPTION
--- 882,888 ----
        }
  
          pethPdPortIndex OBJECT-TYPE
!           SYNTAX      Integer32 (0..65535)
            MAX-ACCESS  not-accessible
            STATUS      current
            DESCRIPTION
***************
*** 999,1005 ****
  
        PethMainPseEntry ::= SEQUENCE {
            pethMainPseGroupIndex
!               INTEGER,
            pethMainPsePower
                Integer32,
            pethMainPseOperStatus
--- 999,1005 ----
  
        PethMainPseEntry ::= SEQUENCE {
            pethMainPseGroupIndex
!               Integer32,
            pethMainPsePower
                Integer32,
            pethMainPseOperStatus
***************
*** 1011,1017 ****
             pethMainPseBackupActivated
                  TruthValue,
            pethMainPseUsageThreshold
!               INTEGER,
  
  
  
--- 1011,1017 ----
             pethMainPseBackupActivated
                  TruthValue,
            pethMainPseUsageThreshold
!               Integer32,
  
  
  
***************
*** 1025,1034 ****
  
  
            pethMainPseMaximumDcPower
!                 INTEGER
        }
          pethMainPseGroupIndex OBJECT-TYPE
!           SYNTAX      INTEGER (0..65535)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
--- 1025,1034 ----
  
  
            pethMainPseMaximumDcPower
!                 Integer32
        }
          pethMainPseGroupIndex OBJECT-TYPE
!           SYNTAX      Integer32 (0..65535)
            MAX-ACCESS  read-only
            STATUS      current
            DESCRIPTION
***************
*** 1104,1121 ****
                    ::= { pethMainPseEntry 6 }
  
          pethMainPseUsageThreshold OBJECT-TYPE
!           SYNTAX      INTEGER (1..99)
            UNITS      "%"
            MAX-ACCESS  read-write
            STATUS      current
            DESCRIPTION
!                   "The usage threshold expressed in percens for
                     comparing the measured power and initiating
                     an alarm if the threshold is exceeded."
            ::= { pethMainPseEntry 7 }
  
        pethMainPseMaximumDcPower  OBJECT-TYPE
!          SYNTAX             INTEGER
           UNITS               "Watts"
           MAX-ACCESS         read-write
           STATUS             current
--- 1104,1121 ----
                    ::= { pethMainPseEntry 6 }
  
          pethMainPseUsageThreshold OBJECT-TYPE
!           SYNTAX      Integer32 (1..99)
            UNITS      "%"
            MAX-ACCESS  read-write
            STATUS      current
            DESCRIPTION
!                   "The usage threshold expressed in percent for
                     comparing the measured power and initiating
                     an alarm if the threshold is exceeded."
            ::= { pethMainPseEntry 7 }
  
        pethMainPseMaximumDcPower  OBJECT-TYPE
!          SYNTAX             Integer32
           UNITS               "Watts"
           MAX-ACCESS         read-write
           STATUS             current
***************
*** 1162,1173 ****
  
        PethTrapsControlEntry ::= SEQUENCE {
            pethTrapsControlGroupIndex
!               INTEGER,
            pethTrapsControlEnable
                  INTEGER
        }
          pethTrapsControlGroupIndex OBJECT-TYPE
!           SYNTAX      INTEGER (1..65535)
            MAX-ACCESS  not-accessible
            STATUS      current
            DESCRIPTION
--- 1162,1173 ----
  
        PethTrapsControlEntry ::= SEQUENCE {
            pethTrapsControlGroupIndex
!               Integer32,
            pethTrapsControlEnable
                  INTEGER
        }
          pethTrapsControlGroupIndex OBJECT-TYPE
!           SYNTAX      Integer32 (1..65535)
            MAX-ACCESS  not-accessible
            STATUS      current
            DESCRIPTION
***************
*** 1207,1218 ****
     --
     --
  
          pethPsePortOnOffTrap NOTIFICATION-TYPE
              OBJECTS     { pethPsePortGroupIndex,pethPsePortIndex,pethPsePortDetectionStatus }
              STATUS      current
              DESCRIPTION " This trap indicate if Pse Port is delivering
                            or not power to the PD."
!              ::= { pethNotifications 1 }
  
  
  
--- 1207,1220 ----
     --
     --
  
+         pethTraps OBJECT IDENTIFIER ::= { pethNotifications 0 }
+ 
          pethPsePortOnOffTrap NOTIFICATION-TYPE
              OBJECTS     { pethPsePortGroupIndex,pethPsePortIndex,pethPsePortDetectionStatus }
              STATUS      current
              DESCRIPTION " This trap indicate if Pse Port is delivering
                            or not power to the PD."
!              ::= { pethTraps 1 }
  
  
  
***************
*** 1222,1228 ****
              DESCRIPTION
                    " This trap indicate Port Change Status and
                         it will be sent on every status change."
!             ::= { pethNotifications 2 }
  
          pethMainPseBackUpActivatedTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex,pethMainPseBackupActivated }
--- 1224,1230 ----
              DESCRIPTION
                    " This trap indicate Port Change Status and
                         it will be sent on every status change."
!             ::= { pethTraps 2 }
  
          pethMainPseBackUpActivatedTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex,pethMainPseBackupActivated }
***************
*** 1230,1236 ****
              DESCRIPTION
                    " This trap indicate BackUp is Activated or
                         BackUp is released."
!             ::= { pethNotifications 3 }
  
          pethMainPowerUsageOnTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex }
--- 1232,1238 ----
              DESCRIPTION
                    " This trap indicate BackUp is Activated or
                         BackUp is released."
!             ::= { pethTraps 3 }
  
          pethMainPowerUsageOnTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex }
***************
*** 1238,1244 ****
              DESCRIPTION
                    " This trap indicate PSE Threshold  usage indication is on,
                         the usage power is above the threshold."
!             ::= { pethNotifications 4 }
  
           pethMainPowerUsageOffTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex }
--- 1240,1246 ----
              DESCRIPTION
                    " This trap indicate PSE Threshold  usage indication is on,
                         the usage power is above the threshold."
!             ::= { pethTraps 4 }
  
           pethMainPowerUsageOffTrap NOTIFICATION-TYPE
              OBJECTS     { pethMainPseGroupIndex }
***************
*** 1246,1253 ****
              DESCRIPTION
                    " This trap indicate PSE Threshold usage indication off,
                         the usage power is below the threshold.."
!             ::= { pethNotifications 5 }
  
  
       pethPsePortTrapGroup NOTIFICATION-GROUP
               NOTIFICATIONS { pethPsePortOnOffTrap, pethPsePortCurrentStatusTrap}
--- 1248,1257 ----
              DESCRIPTION
                    " This trap indicate PSE Threshold usage indication off,
                         the usage power is below the threshold.."
!             ::= { pethTraps 5 }
! 
  
+      pethTrapGroups OBJECT IDENTIFIER ::= { pethNotifications 1 }
  
       pethPsePortTrapGroup NOTIFICATION-GROUP
               NOTIFICATIONS { pethPsePortOnOffTrap, pethPsePortCurrentStatusTrap}
***************
*** 1265,1277 ****
  
  
               DESCRIPTION  "Pse trap indications"
!            ::= { pethNotifications 6 }
  
         pethMainPowerTrapGroup NOTIFICATION-GROUP
               NOTIFICATIONS { pethMainPseBackUpActivatedTrap, pethMainPowerUsageOnTrap,pethMainPowerUsageOffTrap}
               STATUS          current
               DESCRIPTION  "Pse trap indications"
!            ::= { pethNotifications 7 }
  
  
     --
--- 1269,1281 ----
  
  
               DESCRIPTION  "Pse trap indications"
!            ::= { pethTrapGroups 1 }
  
         pethMainPowerTrapGroup NOTIFICATION-GROUP
               NOTIFICATIONS { pethMainPseBackUpActivatedTrap, pethMainPowerUsageOnTrap,pethMainPowerUsageOffTrap}
               STATUS          current
               DESCRIPTION  "Pse trap indications"
!            ::= { pethTrapGroups 2 }
  
  
     --
***************
*** 1339,1344 ****
--- 1343,1349 ----
            pethPsePortAdminEnable,
            pethPsePortPowerPairsControlAbility,
            pethPsePortPowerPairs,
+           pethPsePortPowerDetectionControl,
            pethPsePortDetectionStatus,
            pethPsePortPowerPriority,
            pethPsePortCurrentStatus,
***************
*** 1365,1370 ****
--- 1370,1376 ----
  
     pethMainPseGroup OBJECT-GROUP
         OBJECTS {
+           pethMainPseGroupIndex,
            pethMainPsePower,
            pethMainPseOperStatus,
            pethMainPseConsumptionPower,