From: Gary.Hanson@radisys.com [mailto:Gary.Hanson@radisys.com]
Sent: Thursday, October 27, 2005 10:09 PM
To: Swortwood Bill-G3666C
Cc: Rahul.Ghosh@radisys.com
Subject: Comments on HPI-MIB from August 18, 2005


Bill,

Thanks for responding to my voicemail message, and for talking with me today.  Per our conversation, I am sending you the comments that I have, based on my review of the August 18, 2005 draft revision of the HPI-MIB that I had received a while back from Rahul.

I tried to find the links to the current revision of the HPI-MIB, but I saw one that had only minor differences from that revision at the following URL:
http://cvs.sourceforge.net/viewcvs.py/openhpi/openhpi-subagent/mib/hpi-mib.mib?rev=HEAD

If you could point me to where I can find the latest revision and/or send me the latest revision, I would be happy to take a look at it as well.

Thanks in advance for taking the time to review my comments.  I should note, first, that it is clear that a lot of good, hard work went into the creation of the HPI-MIB module, and that it looks like it models the HPI spec very well (based on my limited understanding of HPI).  I would hope that you can help the OpenHPI group see that cleaning up the remaining issues (many of which are not caught by MIB compilers, even the "anal-retentive" ones) could only help ensure that it will be accepted in a multi-vendor environment that is still based on SMIv2 and SNMPv1/SNMPv2c/SNMPv3.

Thanks.

Best regards,
Gary


Gary Hanson
RadiSys Corporation
desk: 503-615-1547
cell: 503-680-1452


Summary

The HPI-MIB module has been created to provide a means to access the HPI API using SNMP, via a set of objects and notifications specified in SMIv2.

As such, it seems reasonable to expect the HPI-MIB module to conform not only to the HPI specification but also to the standards for SNMP and SMIv2 as defined by the IETF.  However, this is not the case with the draft HPI-MIB published on August 18, 2005.

The HPI-MIB violates several basic SMIv2 rules for defining objects and notifications.  It also fails to follow some basic conventions normally followed by SMIv2 MIB modules.   Finally, it appears to promote SNMP agent behaviors that are at odds with rules for processing SNMP messages.

I realize that the OpenHPI group is not an IETF working group, and is not pursuing the development of the HPI-MIB as an IETF standard.  However, given that the HPI-MIB is obviously intended to be widely used as a standard MIB module by multiple vendors of computing and networking equipment, it is my hope that the OpenHPI group will correct these violations in order to achieve compliance with the IETF standards.

Fortunately, the changes necessary to bring the MIB module into compliance are not difficult, and any resulting changes to prototype SNMP agent software would likely be very localized.

I'll enumerate the issues, along with proposed corrections.  Be aware that changing a MIB module after it is "released" for generate usage is not a good idea, so I encourage you to make the fixes before releasing it.  If the OpenHPI group would like help editing the HPI-MIB to bring it into compliance before it is released, please let me know, and I would be happy to help.

SMIv2 violations in HPI-MIB module

1a.  A SYNTAX of Counter32 is used for objects representing gauge-like semantics (thus violating section 7.1.6  of RFC 2578).  Change the following objects to use a SYNTAX of Gauge32:
1b.  Here's an additional related suggestion that may help.  Renaming the above objects as "<table descriptor prefix>ActiveEntries" instead of "<table descriptor prefix>EntryCount" as they are changed from Counter32 to Gauge32 would not only help clarify the meaning of these objects, but would also help ensure that all pieces of code that use the incorrect BER encoding will be found and fixed.  (The term "active entries" is already used in the DESCRIPTION of saHpiEventLogInfoEntries.)  Doing this would also avoid embedding the term "Count" in the descriptor, to avoid further confusion between counters and gauges.

2.  Another set of objects indicates the total number of objects registered in each table over the lifetime of the given table.  These objects use the SYNTAX of Counter32, as is proper.  However, the descriptors chosen for these objects do not follow the normal convention of picking a name for the thing being counted and adding an "s" to denote plurality (as per section 3.1 of RFC 2578).  If the following objects were re-named as "<table descriptor prefix>LifetimeEntries" instead of "<table descriptor prefix>EntryCountTotal" the descriptors would follow this convention.  In addition, their semantics would be also be better implied by their descriptor:
3a.  The SaHpiTime TEXTUAL-CONVENTION is currently based on Counter64.  However, Counter64 and Counter32 is a SYNTAX intended for use in counting things, events, etc. by the means of computing deltas between successive samples and is thus not appropriate for representing timestamps.  This is especially so if the timestamp has a set of values with special significance (like the value 0x8000000000000000, or the value ranges that represent absolute vs. relative time, or the values 0 and -1.).  If a 64-byte timestamp is desired, it is not appropriate to pick Counter64 merely because it contains 64 bits.  If the objective is to model each timestamp as a single 64-bit value, a better approach that is consistent with SMIv2 conventions would be to use a SYNTAX of OCTET STRING (SIZE (8)) instead of Counter64.

3b.  It may also help to re-name the TEXTUAL-CONVENTION from SaHpiTime to SaHpiTimeString, to better indicate that the time is represented in the form of a hexadecimal-encoded string.

4.  The following objects are defined with a SYNTAX of SafUnsigned64, which is a TEXTUAL-CONVENTION based on Opaque:


This conflicts with the requirement in section 7.1.9 of RFC 2578 that objects in a "standard" MIB module should not use a SYNTAX of Opaque.  Although the HPI-MIB is intended for the IETF standards track, it is intended to be an "ad hoc" standard promoted by OpenHPI and SAForum, so I would consider that this requirement applies to it as well.

The TEXTUAL-CONVENTION for SafUnsigned64 has a REFERENCE to the discussion about Opaque in David Perkins' and Evan McGinnis' book.  However, it is better to adhere to the actual SMIv2 rules defined in RFC 2578 than to follow David's opinion in his book.  Remember that he was one of the three editors charged with cleaning up inconsistencies in SMIv2, and he either changed his mind or lost this particular battle.

Anyway, it appears that these three objects can simply use a SYNTAX of SaHpiTime instead, if the semantics are close enough.  I would recommend doing so and avoiding Opaque altogether.

Note that if Opaque were to be used, even in a TEXTUAL-CONVENTION, it must be included in the IMPORTS clause, per section 3.2 of RFC 2578.  The current HPI-MIB does not do that.  Again, though, I would recommend using SaHpiTime (or SaHpiTimeString, as per 3b above) instead of Opaque.

5a.  One INDEX object is an auxiliary object that has a SYNTAX of Counter32, which violates section 7.7 of RFC 2578:
Since the object obviously has semantics consistent with SaHpiEntryId, it would be better to use that SYNTAX.

5b.  A related object also has a SYNTAX of Counter32:
Since it is obvious that the saHpiRdrEntryId and saHpiRdrNextEntryId are in the same numbering space, the latter should also be changed to use a SYNTAX of SaHpiEntryId.

6a.  Some INDEX objects that are auxiliary objects are currently defined with a MAX-ACCESS other than not-accessible.  The following should have their MAX-ACCESS changed to "not-accessible" to comply with section 7.7 of RFC 2578.
Note that once that is done, these objects would have to be removed from OBJECT-GROUP clauses in which they are currently listed.  Specifically:
6b.  Also, as a result of fixing 6a above, one of these not-accessible objects can no longer be included in notifications, per section 8.1 of RFC 2578:
The good news is that it is usually better to use a non-INDEX object in notifications, anyway, since such an object already includes the desired instance information and (if chosen well) can also include some additional information that would frequently be useful to notification receiver applications.

I'd recommend using saHpiDomainActiveAlarms in place of saHpiDomainId in each of the nine notifications.  In other words, this object would be substituted for saHpiDomainId in each of the OBJECTS lists in the various NOTIFICATION-TYPE clauses.

7.  I would assume that the entries in the following tables should have a one-to-one relationship with the entries in the saHpiSensorTable (similar to the one-to-one relationship that exists between the entries in ifXTable and those they augment in the base table ifTable):
If this is true, to be compliant with section 7.8.1 of RFC 2578, the *Entry clauses for these tables should use an AUGMENTS clause instead of an INDEX clause.

There may be some other examples of one-to-one relationships as well, although I haven't scrutinized the HPI-MIB thoroughly enough to tell.  If so, they should also follow suite.  However, I assume that the entries in the following tables are NOT guaranteed to have a one-to-one relationship with the entries in saHpiSensorTable, because the DESCRIPTIONs for them specifically state that, "If SAI-HPI-B.01.01 SaHpiSensorThdDefnT field IsAccessible == FALSE then no threshold record is created.":
8.  The nine notifications are not defined with 0 as next-to-last sub-component, which violates section 8.5 of RFC 2578.  Even if no implementations of the HPI-MIB use SNMPv1, it would be wise to set a good example by following this convention, for the sake of other future MIB designers who might choose to use the HPI-MIB as an example.

The easiest way to handle this is to add "hpiNotificationsPrefix OBJECT IDENTIFIER :: = { hpiNotifications 0 }", and then define the nine notifications as { hpiNotificationsPrefix 1 } through { hpiNotificationsPrefix 9 }.

9.  The spelling of SaHpiInventoryFieldEntry is unrelated to saHpiFieldEntry.  The former should be changed to SaHpiFieldEntry in three places.

10.  The saHpiAdministrationGroup should be an OBJECT-GROUP instead of a NOTIFICATION-GROUP.

Other conventions not followed by HPI-MIB module

11.  It is not typical to include a descriptor in the IMPORTS clause and then not use it.  The following descriptor should be removed:
12a.  The TEXTUAL-CONVENTION for SaHpiEntryId implies that instances for the first and last entries in a table would be 0x00000000 and 0xFFFFFFFF.  This seems to imply that the corresponding objects for identifying an EntryId in a particular table would be re-numbered in the following cases (of which the second and third cases are probably the most likely):
If this is true, I believe that the indexing scheme resulting from this numbering convention would make it difficult for management applications to track table entries as they come and go, because of the re-numbering that would result.

But perhaps I misunderstand what was intended.  Can someone explain this to me more clearly?

12b.  If the first entry is indeed intended to be numbered 0x00000000, then this actually conflicts with a convention mentioned in section 7.7 of RFC 2578, which states the following: "The use of zero as a value for an integer-valued index object should be avoided, except in special cases."  It doesn't identify those special cases, so perhaps it is acceptable here, but it would still be better to use 0x00000001 as the first instance of table rows.

13.  The embedding of SAForum document version numbers (e.g., "hpiB0101") into the hierarchy of OIDs implies that there are plans to replace the existing objects and notifications with a new MIB module in future..
If this is true, then re-using "HPI-MIB" for that module's name and some other descriptor for the hierarchy (e.g., "hpiC0101") would render it difficult to distinguish objects and notifications in the current module from those in a future module in the event that some of the descriptors are NOT changed in the new module.  This is because objects and notifications must be uniquely identified as <module name>::<descriptor>.

For example, if the new HPI-MIB module retains saHpiWatchdogEventAction, then there is no way to distinguish the object from the current HPI-MIB from that in the new HPI-MIB, even though the latter would be under hpiC0101 instead of hpiB0101.  This is because they would both be called HPI-MIB::saHpiWatchdogEventAction.

I would recommend making one of the following changes:
14.  The first statement in the DESCRIPTION for hpiB0101 implies that users with concerns for security should consider SNMPv2c to be as secure as SNMPv3.  This is untrue, since SNMPv2c is in fact no more secure than SNMPv1 (since they both use community names in cleartext).  This statement should instead recommend that users pick SNMPv3 if they have strong concerns for security.

15.  The conformance information is usually written according to a convention that allows for future revision of the various object and notification groups and the compliances themselves.  Some suggestions:
16.  Some additional editing would help make the HPI-MIB module easier to read.  Some suggestions:
17.  Descriptors are easier to read if embedded acronyms are not fully capitalized.  Some suggestions:
18.  There is an inconsistent use of the term "Notifications" vs. "Notification" in the NOTIFICATION descriptors:
I think it would be better to use "Notification" instead of "Notifications" in order to denote what each notification actually means as it is generated:

19.  Several objects define mappings between SA_ERR_HPI_* values and SNMPv2 PDU error-status values.  Some of these mappings cause the semantics to conflict with the intentions.  (I need a little more time to write up a list of the specific mappings that are in conflict -- I wanted to at least let you know that the conflicts exist.)

Other issues and questions

19.  The object hierarchy in the HPI-MIB is currently defined under hpiD, which is imported from the SAF-TC-MIB module.  But it is not clear where to get the SAF-TC-MIB module from the OpenHPI web pages.  Where can we retrieve a copy of that module?

20.  The differences between the two lists of objects in  items 1 and 2 above indicate that some tables have an object indicating the current # of entries AND an object indicating the total # of lifetime entries, but other tables just have the former.  It is not clear why the latter is important for some tables but not for others.

I would assume that the latter set of objects are provided so that they can be polled periodically to determine if a new entry has been added that needs to be dealt with, and that some tables do not need this functionality.  If so, it may be better to have an object for each table that indicates when it last changed (e.g., as in ifTableLastChanged), since that can also shown when entries have been removed.

21.  The SaHpiStatusCondType TEXTUAL-CONVENTION is not used.  It looks like it should be used for the following objects that currently use an equivalent enumerated INTEGER:
BTW, the note in the saHpiDomainAlarmCondStatusCondType object's DESCRIPTION should be moved to the TEXTUAL-CONVENTION for SaHpiStatusCondType, since it presumably applies to all objects using that convention.

22.  The saHpiUserEventRowStatus object says that, "The status column uses four defined values" and then proceeds to list only two.  It is not clear whether this was supposed to be more like saHpiDomainAlarmRowStatus or not, although it is clear that some cut-and-pasting was used in the two DESCRIPTIONs.

23.  There is a comment following the MAX-ACCESS of read-only for saHpiDomainEventLogEntryId that says, "### SMIv2 bug?"  It is unclear what bug this comment refers to.

Perhaps an earlier version of the HPI-MIB attempted to use this object in the INDEX clause while it was read-only, thus leading to a MIB compiler error.  At this point, I don't see anything wrong here, so the comment can probably be removed.

24.  There are typographical errors in DESCRIPTIONs.  Here are some of the more obvious ones -- I suspect there are more: