Subject: [MIB-DOCTORS] mib doctor review of draft-ietf-eman-rfc4133bis-05.txt

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 14 Jan 2013 10:55:05 +0100

I have reviewed draft-ietf-eman-rfc4133bis-05.txt as part of the MIB
doctors efforts to review all documents containing MIB modules. See
4181 for some more details.

This document has a number of serious issues that need to be resolved
before it is ready to be brought to the IESG. I appreciate a quick
turn around and in particular if some of the more senior co-editors
can make sure issues mentioned below are properly addressed.

a) The compliance definitions must be updated to follow SMIv2 rules.
   This was already mentioned on the list. In short, it is not
   appropriate to rewrite existing compliance or group definitions.
   Instead, new ones must be created as needed.

b) Move the RFC 2119 requirements language paragraph at the end of
   section 1 where it belongs (right now it sits at the end of the I-D
   boilerplate which gets replaced, not in the body of the document)

c) The overview states "This is presently true for at least 3 standard
   MIBs". Did someone check whether this is still accurate? Or better,
   as an alternative, rephrase this sentence to get rid of
   "presently"?

d) Section 2 provides a high-level overview over the changes of
   ENTITY-MIB version 2 and 3. There is unfortunately no such text for
   the version 4.

e) I think a paragraph should be added to section 2.12.1 to describe
   the addition made by version 4 - and if it is just for document
   consistency.

     Version 4 of the Entity MIB provides [...]

   This would also be a good place to explain whether UUIDs are
   supposed to also be represented as URIs (and why or why not).

f) In 2.12.2, can we find a better phrase than "SNMP ARCH [RFC3411]
   method of context identification"? For example, "an SnmpEngineID
   and ContextName pair [RFC3411] for context identification".

g) Overall, replace MIBs with MIB modules.

h) Section 2.16.2 needs to be updated once the conformance mess has been
   fixed.

i) Proposal for a rewording of 2.16.1:

   Over time, there is the need to add new enumerated values to the
   PhysicalClass textual convention. To allow for such additions
   without requiring to re-issue this MIB module, a new MIB module
   called IANA-ENTITY-MIB has been created which provides the
   IANA-maintained textual convention IANAPhysicalClass. The
   PhysicalClass TC has been deprecated.

j) The PhysicalClass TC has been removed from the document, which is
   another violation of SMIv2 update rules. The TC must be put back and
   the status of the TC should be changed to deprecated and an explanation
   added why this was done (see RFC 2579 section 5).

k) RFC 4122 is listed both as normative and informative. I think it is
   normative, no?

j) The EMAN example (section 4.3) is full of Cisco details, I think it
   is more suitable to follow the vendor neutral ACME style of the other
   examples. Furthermore, it appears to me that the UUID values shown
   are not RFC 4122 UUID values. :-( And what is an _MSC_ card? Please
   avoid all vendor specific terms. The indexing of the line card slot
   in the example also seems to be all messed up. And should the line
   card slot not be contained in the chassis?

l) Security considerations: Anything to say about entPhysicalUris and
   entPhysicalUUID concerning the sensitivity of the data the carry?

m) Since this document obsoletes older ENTITY-MIB definitions, are the
   old definitions still normative references? I would expect not. Note
   that the document header also does not state that this document
   obsoletes RFC 4133 - only the abstract does.

n) The description of revision 201212110000Z of the ENTITY-MIB has an
   incomplete sentence... And there is no point in changing previous
   revision statements (in particular revision 200508100000Z). This
   also needs to be reverted back.

o) In the ENTITY-MIB, the syntax of entPhysicalUris has been changed to
   Uri imported from the URI-TC-MIB. Is is _not_ a backwards compatible
   change since entPhysicalUris used to contain a whitespace separated
   list of URIs. Interestingly, this change is not mentioned anywhere
   in the changes text. As this change is not compatible, you have to
   revert it back.

p) The description of ianaEntityMIB is not even a complete sentence.

q) Proposed rewrite for the description of 'energyObject':

  OLD

      The enumeration ?energyObject? is applicable if the
      physical entity is some sort of a energy object i.e.
      a piece of equipment that is part of or attached to
      a communications network that is monitored, controlled,
      or aids in the management of another device for Energy
      Management.

  NEW

      The enumeration 'energyObject' is applicable if the
      physical entity class is some sort of a energy object, 
      i.e., a piece of equipment that is part of or attached to
      a communications network that is monitored, controlled,
      or aids in the management of another device for Energy
      Management.

  Putting energyObject in single quotes etc. for consistency.

r) Proposed rewrite for the description of 'battery':
  
  OLD

      The enumeration 'battery' is applicable of the physical
      entity class is some sort of an energy battery device. "

  NEW

      The enumeration 'battery' is applicable if the physical
      entity class is some sort of a battery."

  (Fixing of->if, avoiding 'device', removing useless 'energy'.)

s) The description of uuidTCMIB is not even a complete sentence.  (The
   indentation of the SYNTAX clause is somewhat unusual but
   syntactically valid.)

t) The last three paragraphs of the security considerations should
   be updated to match the new boilerplate text posted here:

   http://trac.tools.ietf.org/area/ops/trac/wiki/mib-security

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Benoit Claise <[email-masked]>
Date: Mon, 14 Jan 2013 11:31:41 +0100

Juergen, draft-ietf-eman-rfc4133bis authors,

I did the AD review and the IETF LC started. Juergen, based on AD review 
email, discovered an important problem with the MIB. Then I proposed to 
quickly post a new version, before the actual MIB doctor job started (*)

Looking at the list of requested changes from Juergen, it's better to 
wait for the end of the IETF LC to post the next version.
However, in the mean time, I advice the draft-ietf-eman-rfc4133bis 
authors to work on temp version to get Juergen's green light on the new 
text.
Btw, I agree with Juergen's comments.

(*) I made a process mistake with this draft: mea culpa. Normally, the 
MIB doctor review is done between the WG LC and the start the IETF LC. 
So I sent this draft to IETF LC too fast. So thanks to Juergen for his 
quick review.

Regards, Benoit

---

From: "Mouli Chandramouli (moulchan)" <[email-masked]>
Date: Mon, 14 Jan 2013 10:44:16 +0000

Benoit,

As you have suggested we shall submit an interim version to address the comments of Juergen Schoenwaelder. 

Thanks
Mouli

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Benoit Claise (bclaise)
Sent: Monday, January 14, 2013 4:02 PM
To: [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: [eman] mib doctor review of draft-ietf-eman-rfc4133bis-05.txt

Regards, Benoit
>     http://trac.tools.ietf.org/area/ops/trac/wiki/mib-security

_______________________________________________
eman mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/eman

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Mon, 14 Jan 2013 16:05:21 +0000

Hi Juergen, 

Thanks for the detailed review. 

Please see in-line the responses and proposals for update. 

For a couple of points I am waiting for answers from Mouli. 

Please let us know if the proposed resolutions answer your concerns.

Regards,

Dan

> From: Juergen Schoenwaelder [mailto:j.schoenwaelder@jacobs-
> university.de]
> Sent: Monday, January 14, 2013 11:55 AM
> To: [email-masked]; [email-masked]
> Cc: [email-masked]; [email-masked]
> Subject: mib doctor review of draft-ietf-eman-rfc4133bis-05.txt
> 
> before it is ready to be brought to the IESG. I appreciate a quick turn
> around and in particular if some of the more senior co-editors can make
> sure issues mentioned below are properly addressed.
> 

[[DR]] Right. The existing compliance and group definitions will be kept as in RFC4133 today and we shall create two new compliance groups entity4Compliance and entity4CRCompliance. 

>    boilerplate which gets replaced, not in the body of the document)
[[DR]] Actually I believe that this document does not need any reference to RFC 2119 at all, so we can take out that paragraph and the reference to [2119] out completely. 

>    as an alternative, rephrase this sentence to get rid of
[[DR]] This text is taken 'as is' from RFC 4133. None of the three example MIB modules was deprecated. So it's still true. 

In general we avoided making changes in the document unless necessary.

>    ENTITY-MIB version 2 and 3. There is unfortunately no such text for
[[DR]] Proposed Solution: 

Add at the end of Section 2 the following text: 

   Version 3 of this MIB addresses new requirements, which have emerged
   since the publication of the third Entity MIB (RFC 4133 [RFC4133]).
   There is a need to add new enumerated values for physical classes, a 
   need to provide identification information for entity objects in 
   a Universal Unique Identifier (UUID) formats, and a need to describe
   Constrained Resources (CR) entities. The PhysicalClass Textual 
   Convention (TC) was deprecated and a new IANAPhysicalClass TC was 
   created. A new TC UUIDorZero was created to represent a UUID and a
   new object was added to the entPhysicalTable to identify the UUID. 

>    supposed to also be represented as URIs (and why or why not).
[[DR]] I will let Mouli address this, as I am not sure 100% about the response to the issue of representation. 

>    and ContextName pair [RFC3411] for context identification".

[[DR]] This is the verbiage used in RFC 4133. Unless we need to fix a bug I suggest to avoid such changes. 

> g) Overall, replace MIBs with MIB modules.
[[DR]] Same as the previous point. 

> h) Section 2.16.2 needs to be updated once the conformance mess has been
[[DR]] 

OLD: 

   Creation of a new MODULE-COMPLIANCE module entity4CRCompliance for
   devices with constrained resources like batteries, which might
   require a limited number of objects to be supported
   (entPhysicalClass, entPhysicalName, entPhysicalUUID) 

NEW: 
   Creation of two new MODULE-COMPLIANCE modules entity4Compliance
   for full compliance with version 4 of the Entity MIB and 
   entity4CRCompliance for
   devices with constrained resources like batteries, which might
   require a limited number of objects to be supported
   (entPhysicalClass, entPhysicalName, entPhysicalUUID) 

>    PhysicalClass TC has been deprecated.
[[DR]] OK

>    added why this was done (see RFC 2579 section 5).
[[DR]] OK - we shall change the status to deprecated and add text clarifying 
that starting with version 4 of the MIB module the use of the IANAPhysicalClass
TC is recommended instead. 

> k) RFC 4122 is listed both as normative and informative. I think it is

[[DR]] yes.

>    card slot not be contained in the chassis?
[[DR]] Mouli - can you please look at these? 

>    entPhysicalUUID concerning the sensitivity of the data the carry?

[[DR]] good point, although entPhysicalUri was not listed previously as sensitive. I would suggest to add the two objects to the list of objects that expose information about the physical entities within a managed system, which may be used to identify the vendor, model, and version information of each system component. 

>    obsoletes RFC 4133 - only the abstract does.

[[DR]] The header should be updated. 

>    also needs to be reverted back.

[[DR]] OK. Actually the 2012... revision will not be mentioned any longer. 

>    in the changes text. As this change is not compatible, you have to
[[DR]] It's the first time this comment is made (as a few other as well). Sure, if the change is not backwards compatible, this needs to be reversed. 

> p) The description of ianaEntityMIB is not even a complete sentence.
[[DR]] s/This MIB module/This MIB Module defines a Textual Convention that provides an indication of the general hardware type of a particular physical entity./

>   Putting energyObject in single quotes etc. for consistency.

[[DR]] OK. 

>   (Fixing of->if, avoiding 'device', removing useless 'energy'.)

[[DR]] OK. 

>    indentation of the SYNTAX clause is somewhat unusual but
[[DR]] s/This MIB module/This MIB module defines a Textual Convention that provides an indication of the general hardware type of a particular physical entity./

>    http://trac.tools.ietf.org/area/ops/trac/wiki/mib-security

[[DR]] OK.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 14 Jan 2013 17:45:33 +0100

> Please let us know if the proposed resolutions answer your concerns.

I will only respond to those issues where we either disagree or where
further clarification may be necessary.

>    new object was added to the entPhysicalTable to identify the UUID. 

I am not sure the "need to describe Constrained Resources (CR)
entities" explains it well. Perhaps there is a "need for conformance
statements for Constrained Resources (CR) entities" or something like
that.
 
> [[DR]] This is the verbiage used in RFC 4133. Unless we need to fix a bug I suggest to avoid such changes. 

It is document clarity. But I won't insist on this, I just find the
current text unnecessarily confusing.
 
> [[DR]] Same as the previous point. 

Again, it is document clarity. It is rather obvious that this change
does not break anything, no? Let Bert decide - he is the owner of the
one MIB many MIB modules song. ;-)

> > k) RFC 4122 is listed both as normative and informative. I think it is

So I assume you will remove the informative reference, right?
 
> [[DR]] The header should be updated. 

And the references to the old revisions will become informative, right?
 
> [[DR]] OK. Actually the 2012... revision will not be mentioned any longer. 

Yes, but there will be a 2013... revision.

> [[DR]] It's the first time this comment is made (as a few other as well). Sure, if the change is not backwards compatible, this needs to be reversed. 

Yes, apparently the level of review this MIB module enjoyed has not
been very extensive.

/js

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Tue, 15 Jan 2013 13:07:43 +0000

See in-line. 

Thanks and Regards,

Dan

> Sent: Monday, January 14, 2013 6:46 PM
> To: Romascanu, Dan (Dan)
> Cc: [email-masked]; [email-masked];
> [email-masked]; [email-masked]
> Subject: Re: mib doctor review of draft-ietf-eman-rfc4133bis-05.txt
> 
> I am not sure the "need to describe Constrained Resources (CR) entities"
> explains it well. Perhaps there is a "need for conformance statements
> for Constrained Resources (CR) entities" or something like that.
> 

[[DR]] OK. 

> one MIB many MIB modules song. ;-)

[[DR]] I also sing the song when I review new documents, but in this case we would interfere in the text of the document that is now at version 4. 

> So I assume you will remove the informative reference, right?

[[DR]] Right.

> And the references to the old revisions will become informative, right?

[[DR]] Right.

> Yes, but there will be a 2013... revision.

[[DR]] of course :-)

> > [[DR]] It's the first time this comment is made (as a few other as
> well). Sure, if the change is not backwards compatible, this needs to be
> reversed.
> 
> Yes, apparently the level of review this MIB module enjoyed has not been
> very extensive.
> 
> /js
> 
> --

---

From: "Mouli Chandramouli (moulchan)" <[email-masked]>
Date: Tue, 15 Jan 2013 13:09:49 +0000

Hello Juergen, 

Thanks for the review. Replies inline. 

Regards
Mouli

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Romascanu, Dan (Dan)
Sent: Monday, January 14, 2013 9:35 PM
To: Juergen Schoenwaelder; [email-masked]; [email-masked]
Cc: [email-masked]; [email-masked]
Subject: Re: [eman] mib doctor review of draft-ietf-eman-rfc4133bis-05.txt

Hi Juergen, 

Regards,

Dan

> Subject: mib doctor review of draft-ietf-eman-rfc4133bis-05.txt

[ycm] snip ... 

[[DR]] I will let Mouli address this, as I am not sure 100% about the response to the issue of representation. 
[ycm] 
[ycm] Thanks for the comment. To be consistent, we shall add the following paragraph on in Section 2.12.1. 

NEW 
  
Version 4 of the Entity MIB provides an additional MIB object  for each physical entity. 

entPhysicalUUID - This object provides an additional unique identification about the physical entity.  
This object contains a globally unique identifier for the physical entity with the format as defined in RFC 4122 [RFC4122]. 
The UUID shall be represented as URIs. 

To support the existing implementations of ENTITY-MIB v3,  entPhyiscalUris object which uses the URI syntax can 
be used to store the UUID value of the physical entity. Caution should to be exercised since this MIB object is read-write.  

With the implementation of ENTITY-MIB v4, the value of UUID can be stored in new MIB object entPhysicalUUID (which is read-only) 
and the UUID value can also be duplicated in entPhysicalUris MIB object. To enable this capability, the syntax of the 
two MIB objects should be similar. 

[ycm] 

[[DR]] Mouli - can you please look at these? 
 [ycm] I will remove the reference to Cisco terns and use a generic name as ACME and also the 128 bit UUID values in the URI representation.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 15 Jan 2013 15:09:07 +0100

> [[DR]] I also sing the song when I review new documents, but in this case we would interfere in the text of the document that is now at version 4. 

So what? Time to fix this. Anyway, I will not fight for this if
editors believe it is best to not update vocabularity to current
rules.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 15 Jan 2013 15:15:20 +0100

> The UUID shall be represented as URIs. 

Sure? This is not what the definitions do (and I think it would even
be wrong to do this). Please check your document.

> be used to store the UUID value of the physical entity. Caution should to be exercised since this MIB object is read-write.  

Why caution? I suggest to either spell out what the issue is or leave
this out.
 
> two MIB objects should be similar. 

Again, I think the last sentence should be removed since the syntax is
actually different.

/js

---

From: Benoit Claise <[email-masked]>
Date: Mon, 28 Jan 2013 13:16:39 +0000

Dan,
> editors believe it is best to not update vocabularity to current
I agree with Juergen on the two points above.

Every single time I speak SNMP/MIB with someone, I try to use the right 
language, and correct my interlocutor if needed, with a little of education.
I don't understand why we don't jump on the opportunity to correct this 
document.
There are two types of audience for this new document:
1. The people who have not read the first 3 versions. So I guess not 
that familiar with the SNMP/MIB. They would benefit from the right 
terminology
2. The persons who need a diff with the previous version. So I guess 
familiar with SNMP/MIB. And the improvements would be obvious to them.

Therefore, there is no harm in improving the document. And I don't buy 
in the argument that we need to keep consistency with RFC 4133 ..; for 
something that is not clear.

Regards, Benoit

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Mon, 28 Jan 2013 13:24:43 +0000

Sure, there are 7 instances of 'MIBs' in the latest version of the document - we can replace them all by 'MIB modules'. 

Are there any other issues that need to be edited before submitting a revised version? We (the authors) believe that we fixed all issues raised by the MIB Doctor review, but mistakes are always possible. 

Regards,

Dan

> From: Benoit Claise [mailto:[email-masked]]
> Sent: Monday, January 28, 2013 3:17 PM
> To: Romascanu, Dan (Dan); [email-masked]; draft-ietf-eman-
> [email-masked]; [email-masked]; [email-masked]
> Subject: Re: [MIB-DOCTORS] mib doctor review of draft-ietf-eman-
> rfc4133bis-05.txt
> 
> Dan,
> >>>> [[DR]] This is the verbiage used in RFC 4133. Unless we need to fix
> >>>> a
> >>> bug I suggest to avoid such changes.
> >>>
> >>> does not break anything, no? Let Bert decide - he is the owner of
> >>> the one MIB many MIB modules song. ;-)
> >>>
> >> [[DR]] I also sing the song when I review new documents, but in this
> case we would interfere in the text of the document that is now at
> version 4.
> terminology 2. The persons who need a diff with the previous version. So
> I guess familiar with SNMP/MIB. And the improvements would be obvious to
> them.
>