Subject: AD review of draft-ietf-snmpconf-pm-11.txt - part 1

From: "Wijnen, Bert (Bert)" <[email-masked]>
Date: Tue, 28 Jan 2003 00:53:37 +0100

Here is a list of NITS, admin/bureucratic comments and
more or less serious concerns/questions.

- on the fornt page, I would not repeat the authors/editors'
  names under the title.
- At next revision, update copyright date
- the RFC-Editor does not want the abstract to be a numbered 
  section
- Section 2, we have a new MIB boilerplate since the SNMPv3
  RFCs have been published as STD 62.
  See: http:/www.ops.ietf.org
- We also have a new MIB security guidelines at the same
  place. You may want to check if that means some changes
  to your Security Considereations section.
- References need to be split in Normative and Informative
  See http://www.rfc-editor.org/policy.html
- last para on page 4 talsk about 
   "..this document defines standard management objects" and
   "... in a standard form..."
  The attribute of STDs track is assigned external to an RFC,
  so you should not state/claim that this is standard in the
  document itself.
- First list of bullets in section 3 seems to be a marketing
  statement. We do not need those in RFCs.
- In general, I would like the authors/editors to go through 
  the document and to properly use the terms MIB, MIB Module.
  I think too often then term "MIBs" is used when you really 
  mean "MIB Modules". I noticed it at least twice in sect 5.3
- Sect 5.5.1.
  s/are are/are/
- Section 6 states in 3rd para:
  "Some examples of the features that have been removed...."
  Not sure it is really "have been removed" or if it is better
  stated as "are not used" or "are not available" or 
  "are not inherited" or such.
- Has anyone checked the EBNF specification via a syntax checker?
  See http://www.ietf.org/ID-nits.html section 2 6th bullet,
  which also points to
  http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt
  For example, I am not sure this is correct (page 18)
         unary_op:          '+' | '-' | ' | '!' | '++' | '--'
  What does that single quote between the 2nd and 3rd } mean?
- sect 6.2.1
  I get a bit confused when you talk about 8-bit elements for
  a string (in UTF-8 context). Steve tried to explain, but 
  the current text still confuses me. I think he was going to
  try and add some text to unconfuse me (and possibly others).
- When you use EBNF, LHS, RHS and such acronyms the first time 
  in the document, pls expand them Thisis another RFC-Editor
  policy.
- I had some conversation with Steve about the Library functions,
  on hos they are split in 4 categories and which of the
  "reserved words" can be used when and where. Also a question
  on the "which categories must be supported". I believe the 
  answer was all. Steve is going to clarify some of this.
- Sect 9.1.1 starts with a ">"... ??
  I saw that at a few more places
- Sect 9.1.1 I see
    snmp-function(...[, integer mPModel,
                        string tDomain, string tAddress,
                        integer secModel, string secName,
                        integer secLevel, string contextEngineID
    ]) 

  It seems to me we need to be able to express the contextName
  for local and for remote SNMP engines? How do we do that?
  I think when I look further in the document, that one of the
  "..." arguments is probably the contextName. Might be good to 
  explain some of that.

- when I see this
    snmp-function(...[, integer mPModel,
                        string tDomain, string tAddress,
                        integer secModel, string secName,
                        integer secLevel, string contextEngineID
    ]) 

  and if I understand it correctlym then all those extra args
  are positional and optional, is then not the better notation:

    snmp-function(...[, integer mPModel [,
                        string tDomain [, string tAddress [,
                        integer secModel [, string secName [,
                        integer secLevel [, string contextEngineID
    ]]]]]]]) 

- The sample that follows
    getVar("sysDescr.0", "", SNMPv3, "snmpUDPDomain",
           "192.168.1.1/161", SNMPv3, "joe", "NoAuthNoPriv");
  confuses me somewhat. 
  I think it is a getVar for sysDescr.0, in the default contextName
  but it seems to list a SN MPv3 secModel. I am not aware that
  we have such a secmodel, do we? We have a USM secModel.
  We also have an SNMPv1 and SNMPv2c, or even an any secModel.
  But not an SNMPv3 secModel.

- Sect 9.1.1 also talks about TDomain. I would suggest to consider
  to use terms from RFc3419, which includes values for IPv6, which
  is something that IESG really wants these days.

- bottom of page 34. Why do we allow a trailing dot if it can case 
  strncmp() problems?

- sect 9.1.3.1
  The empty (zero length)  string is the default context.
  so I guess if one omits it that one also gets the default
  context. Not sure if that is clear here.
  At least the text
              If 'contextName' is not present,
        this element's contextName will be used.
  Confuses me. What does that mean?
  This comes back in a lot of the function descriptions

- Sect 9.1.3.1 and following sections
  So do we realize that a "programmer" of these scripts needs
  to speak OID lingo as opposed to descriptors?
  Do we really believe that that is encouraging?

- Sect 9.1.3.2
    The exists() function is used to verify the existence of an
    SNMP MIB instance.
  Do you mean s/MIB/MIB object/ 
  You cannot be meaning a complete MIB instance, do you?
  Similar text is used in following sections too.

- I guess that exists() returns an integer cause we do not
  have a boolean in our language, right?

- Sect 9.1.3.4
  Mmm... why not rename "pattern" to "searchString" ??

  And is the programmer expected to use digits to express
  which mode to use? Or are there reserved words for that?

- Sect 9.1.3.6
  I wonder how rows that have multiple integers, or octet
  strings or such as index, how they get created?

  Does the last para on page 42 agree with the code fragment
  on the next page? Spefically, does the if createRow() call
  and and checking of return code and index agree with that
  para? Maybe I am just confused.

- page 44 talks about "noSuchName or noSuchObject"
  - do we still want to talk about noSuchName (SNMPv1 ??)
  - do we not need to talk about noSuchInstance?

- sect 9.1.4.1
  How about error-status and error-index?

- sect 9.1.4.2
  I wonder if pdu should not be prefixed with &pdu ?

  Can this function never return an error?

- sect 9.1.4.3 and 9.1.4.4
  I see
          int readVar(integer pdu, integer varBindIndex,
  and I see
    integer snmpSend(integer reqPDU, integer reqNumVarbinds,
  So I wonder, do we have both int and integer as a datatype?

- sect 9.1.4.5
  What if you pass a non-existing pdu handle?
  Will it return an error? so should it be:

  integer  readError(integer pdu, integer numVarbinds,
                     integer &errorStatus, integer &errorIndex,
                     integer &hasException)

  to show that it can return an error?
  The same question for some of the other functions in sect 9.1

- sect 9.2
  I wonder if this is not better sect 9.1.5 ??
  It is part of the SNMP library functions, no?

- sect 9.2
    const integer Integer       = 2;
  So does that potentially cause confusion for people to
  recognize the difference between integer with lowercase i
  and upprecase I ??
  In fact I wonder if these could not all better be prefixed
  with some string like SNMP or so, e.g.

  const integer SNMP_Integer       = 2;
  const integer SNMP_Integer32     = 2;
  etc

  You refer to RFC1905, better to refer to RFC3416

  You also refer to RFC2571, better to use RFC3411

- sect 9.3.1
  I fail to see how the function returns an indication on
  how the object is indexed.
  And does the prototype function not need arguments?

- sect 9.3.4 and 9.3.5
  I had asked steve if the function ev() and ec()
  could be better named elementValue() and elementCount().
  He answered that thes function will be used a lot, similar
  to argv and argc in C. So.. are we happy that these
  are such cryptic functiuon names? Is elemv() and elemc() 
  a better compromise. 
  I can live with ev() and ec() if the WG says it is OK.

- sect 9.3.4 and 9.3.5
  I wonder if it is easy to know what "this element" means.
  I think it is explained in sect 7... but that is quite
  a few pages back. 

- When I see things like the roleMatch function and I know
  that we are in a UTF-8 environment, then I think we need
  to include stringprep functionality as per RFC3454.
  In fact Patrik Faltstrom, APPS AD has confirmed that this
  is needed, and he has already pointed the authors to a
  sample.

- I guess we have another set of reserved words at the end of
  sect 9.3.7
  Maybe we need one section that lists them all, no?

- sect 9.4.6 last sentence
  "... twice if is an expression" ???

- sect 9.4.8
  I first thought that oid needed to be &oid.
  But the resulting OID is returned as a string (is what Steve
  told me). I guess the "...replace len subids in oid1.."
  is what confused me.

OK, part 2 comes tomorrow.

Bert

Thanks,
Bert