Subject: Re: [netmod] comments on draft-ietf-netmod-smi-01

From: David Reid <[email-masked]>
Date: Tue, 11 Oct 2011 16:51:12 -0400

> Andy Bierman wrote:
> 
> sec 2:
> 
>     Implementations are encouraged to provide
>     options to handle situations where DISPLAY-HINTs are added during a
>     revision of a module and backwards compatibility must be preserved.
> 
> What are the options they are encouraged to provide?

I agree that this needs more work. I don't have a good solution at this point.

> 
> 
> sec 3:
> 
> The order modules are processed by a translator will affect the
> prefix algorithm, wrt/ detecting conflicts.   It seems this algorithm is
> ad-hoc, and there is no way to determine if the shortest unique
> prefix is really found.  IMO it would be better to allow a translator
> to use the entire converted module name to be sure the prefix is unique.

I agree with Andy about using the entire name for the prefix. I think the full
name makes the document more clear to the reader. In most cases, the algorithm
either does not shorten the name or only shortens it slightly. Not using the 
prefix algorithm can make for some long path statements in a few cases. But I 
still think the clarity of the full name outweighs the brevity of the shortened
names. There are a few cases in standard MIBs where using the prefix
algorithm results in different modules using the same prefix to refer to
different modules or different prefixes to refer to the same module. That's
perfectly legal yang, but I find it a bit confusing. The MIBs defined in 
RFC 5324 provide good examples that could support either side of this debate.
That is, the prefix algorithm results in significantly shorter names, but
could be confusing.

> 
> sec. 4:
> 
>     SMIv2 modules are mapped to corresponding YANG modules.  The YANG
>     module name MUST be the same as the SMIv2 module name.
> 
> Do you mean the converted module name, according to the algorithm in sec. 3?
> No.  I see further down this is not the case.  I suggest a new section
> called Mapping of the Module Name to make this more clear.

I didn't think this was unclear. Would it be more clear if the module name
translation and imports translation were in different sections instead of
the same?

> sec 6.1:
> 
>       SMIv2 INTEGER enumerations and SMIv2 BITS are mapped to YANG enum
>        / value and bit / position statements.
> 
> Are these forward slashes typos?  (also sec. 8.1)

I don't think they are typos, but I also found it confusing when I first
read it. Would this be more clear:

    SMIv2 INTEGER enumerations are mapped to YANG enum/value statements.
    SMIv2 BITS are mapped to YANG bit/position statements.

> sec. 8.3:
> 
>     YANG leaf statements of type leafref pointing to the
>     referenced definition are created.
> 
> then later in 8.5:
> 
>          leaf ifIndex {
>             type leafref {
>               path "/if-mib:ifMIB/if-mib:ifTable" +
>                    "/if-mib:ifEntry/if-mib:ifIndex";
>             }
>             description
>              "[Automatically generated leaf for a foreign index.]";
>           }
> 
> The text does not mention this automatic description-stmt.
> Should the text say this string SHOULD (or MAY) be used?

I would suggest removing description from the example. 

Also, if I understand the rules correctly, the path statement in this and 
several other examples is wrong. I thought the ifMIB container went around
the scalars but not the tables.

I actually don't like putting a container around the scalars for a couple of
reasons. The first reason is that it gets things out of order from the MIB. 
In a lot of MIBs, there are several groups which each have several scalars 
and one or more tables that logically go together. IF-MIB and DISMAN-EVENT-MIB
are two good examples. Putting all the scalars together under one container 
looses that logical ordering. A second reason that an SMIv1 module converted 
to SMIv2 might have the same module name but a MODULE-IDENTITY added in the 
SMIv2 version. HOST-RESOURCES-MIB is a good example (rfcs 1514 and 2790). The 
version without the MODULE-IDENTITY would produce a different path that the 
version with the MODULE-IDENTITY. Section 5.1 mentions the possibility of a
module not having a MODULE-IDENTITY, but does not suggest what to do about
the top level container if MODULE-IDENTITY is missing.

> Andy

-David Reid