Subject: [netmod] review of -arch

From: "David Harrington" <[email-masked]>
Date: Tue, 11 Nov 2008 17:20:13 -0500

Hi,

Here is a review of the netmod-arch document.

1) YANG is to netconf as SMI is to SNMP.
I recommend starting the arch document by putting YANG into
perspective. I recommend fashioning the Introduction on the
Introductions to RFC2578, RFC2579, and RFC2580.

The follow that with the current Introduction.

2) The document should present its description of the architecture
without blatant marketing. Most notbaly, section 6 should be
eliminated.

section 2.1
s/nearly perfectly//

I think it is important to discuss the fact that Netconf has a PDU
format that is an XML document (or a fragment of an XML document).
YANG is a language for standardizing how to write XML documents for
use with Netconf. 

I am not sure I understand why we need an example of modeling ospf in
XML as an introduction to YANG as a modeling language. If XML matches
nearly perfectly the data needs of networking devices, then remind me
again why we need YANG??

section 2.2
So this is the part that explains YANG. Except that it actually
doesn't mention the relationship between YANG and the "nearly perfect"
XML of the previous section, and why YANG is needed.

The example does not look simpler than the XML example. I don't think
it mad every clear that YANG is a description of the XML model,
including the constraints. I think a very quick discussion of the
parts (container, key, range) that have specific purposes would be
helpful. Something like "the key field identifies an instance of the
area; the range show the legal values of the XML priority field, ..." 

2.2.1
There is some discussion of YANG modules, but no discussion of why
YANG is modular. In the MIB world, there is "the MIB" and then there
are modular parts of "the MIB", to make it easier to develop pieces of
the MIB. I think such a discussion might be helpful here.

I strongly recommend the WG choose a term for their MIB and their MIB
modules, so the documents can be consistent internally and across
documents. Just pick a term and go with it.

", introducing elements from that models' hierarchy ...". I think this
clause might be better as a separate sentence using example names for
each module. "Elements from model B's namespace may augment model A's
hierarchy." 

I think the document jumps too early into examples. By the time you
get into the proprietary extension example, you are showing syntax
that has not yet been defined. Explain the motivations for having a
YANG language. Explain about the motiviation for defining types, and
modules, and submodules, and groups, and supporting reuse, and so on.
No exmaples; no syntax discussions - motivations. Why do we need YANG?

"Extensions are seamlessly integrated" - I don't see this in the
example. I don't think readers who are not XML experts or YANG experts
will see that from this example.

You might do well to use ASCII art a lot at this point, to explain
some of the concepts without delving into syntax and examples.

section 3.
The MIB is defined as a virtual database of managed objects. I think
similar terminology would be helpful here. After you introduce a
virtual database, then discuss the fact that modules might be standard
or proprietary, and they fit together in the virtual database.

Throguhout the document, you seem to struggle with describing device
functionality device specific behavior and so on. Just call it
"instrumentation" - people already know that term. Or make a
distinction between the virtual database and the actual database (or
the instrumentation database or the configuration database).

You seem to use applicatiion to refer to different things, and I find
it confusing. You really need to standarize your use of terminology. I
recommend having a "Conventions" section right after the first
Introduction portion (i.e. section 2.1), to define the terms you will
use throughout. I would move the "Key words" section into that
Conventions section, and start the document wiht the Introduction. You
might want to consider using "manager" and "agent" since those are
well understood. Or you can use client and server terminology, which
is also well-understood. "application" and "device" are less clear,
since not all managed entities are devices, and "applications" can
exist both on the device and off the device.

What is the difference between a module and a schema? YANG allows you
to define modules, and support for those modules is discovered using
"schema" discovery. We need to be much more consistent in our
terminology usage.

The four paragraphs starting with "The schema discovery for standard
YANG modules ..." is about netconf, not about YANG.

During discussion of schema discovery, you talk about location of
schemas. Then, later in this section, you give an example that models
"location" using longitude and latitiude. Gee, does that mean when I
do a schema discovery, I discover the latitude and longitude of where
the schema can be found? ;-) You might want to use a different example
at this point.

"When the application interacts with a device, it ..."; 
s/it/the application/

"For a popular application, the vendor ..."
which vendor? the device vendor or the application vendor?

"uptake" - slang. The actual English meaning doesn't match the
sentence meaning.

I think the picture does add to comprehension. It would be better with
terminology consistent throughout the YANG environment.

The spacing before section 4 can be eliminated by using the xml2rfc
command to compact. I recommend the following switches in xml2rfc:
<?rfc toc="yes"?>
<?rfc compact="yes"?>
<?rfc symrefs="yes" ?>
<?rfc strict="yes" ?>
<?rfc rfcedstyle="yes" ?>

"Difficult as it is to believe, ..." is great when you are delivering
a presentation, but really does not belong in a standards document.
Can you clean up this paragraph, and can we lose the Sierra Madre
while we're at it?

"The complete standard mapping ... is implemented in "off the shelf"
open source and commercial software." Since we haven't defined this
yet, I have strong doubts that this statement is true. Let's not make
predictions of what will be.

"Many DSDL engines offer ...". I didn't know there were many DSDL
engines, never mind ones that offer ...

section 4.1
s/in the YANG module/in a YANG module/

4.1.2
This section wanders, talking about validation, and generation, and
serializers. Section 4.1.3 also talks about validation. I think this
section really needs to be about a particular use case, just as the
others sections are.

"generating and receiving XML content" - I suggest generating and
receiving "Netconf XML documents" or "Netconf PDUs" or "Netconf
content". But is this different than 4.1.3? And 4.1.3 mentions
"ascertian ... obeying the rules" which is the same as validation,
right?

"The YANG-based toolset" - we are not standardizing a toolset. We are
standardizing a language. If there are tools out there, we probably
should not be discussing them in this document, and claiming what they
can do. I also did not understand what this paragraph even said -
"generate support material", extensibility, augments? Is there a point
to this paragraph?

4.1.5
s/data in without/data without/
s/without understanding any specifics/without understanding any
semantics/
s/need only understand the YANG/need only understand the YANG syntax/
s/, but will have better information at its disposal with YANG.//
(If you want to make such a claim, you will need to qualify what
"better" means. If I wrote a YANG module with the same infoamrtion
available in a MIB, it is not better information just because it is
written in YANG, and more than a sentence with identical meaning
written in English and French would make one better than the other.)

4.1.5.1
s/In contrast to the generic approach/In contrast to the bottom-up
approach/

"the application transforms the application data into device data ...
allowing the transformation to be changed and updated without
affecting the device." - I find this unclear as to what you mean to
say. If you modify the contract that both application and device
follow, then changing the contract does affect the device.

I think your examples would be much more useful to show network
modelers how useful YANG could be to model their network, if you used
a network example rather than hotdogs. Cute doesn't necessarily make
things clearer, and our goal is to write clear and unambiguous
documents.

"The model may opt for a more complex model" - should be the modeler
who opts?

s/but applications that do not continue/but applications that do not
discover such behavior continue/

s/do their best to be explicit/be explicit/

s/But both server and client/Both server and client/

section 7
""The SSH transport for NETCONF provies such facilities." - Ummm, no
it doesn't. The SSH transport doesn't mention RADIUS or local
passwords. 

I think this section should discuss security considerations for YANG.
RFC2578 simply says:
   This document defines a language with which to write and read
   descriptions of management information.  The language itself has no
   security impact on the Internet.

Hope this helps,
David Harrington
[email-masked]
[email-masked]
[email-masked]

David Harrington
[email-masked]
[email-masked]
[email-masked]

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