-----Original Message----- From: netmod <[email protected]> On Behalf Of Schönwälder, Jürgen Sent: 2020. január 20., hétfő 15:46 To: Kent Watsen <[email protected]> Cc: NETMOD Working Group <[email protected]> Subject: Re: [netmod] WG Last Call: draft-ietf-netmod-yang-instance-file-format-06
On Tue, Jan 07, 2020 at 12:41:23PM +0000, Kent Watsen wrote:
>
> This begins a two-week Working Group Last Call (WGLC) on
draft-ietf-netmod-yang-instance-file-format-06. The WGLC ends on Jan 21.
Please send your comments to the working group mailing list.
>
> Positive comments, e.g., "I've reviewed this document and believe it is
ready for publication", are welcome! This is useful and important, even
from authors. Objections, concerns, and suggestions are also welcomed at
this time.
>
I have reviewed draft-ietf-netmod-yang-instance-file-format-06. I believe
this is an important document but not quite ready yet. Most of the points I
am raising below should, however, be easy to resolve, many concern
terminology and writing consolidation and do not affect the technical
solution.
/js
* Abstract
I think we should avoid referring to some <get> operation. Here is a
proposal of a rewrite:
OLD
running server available. This document specifies a standard file
format for YANG instance data (which follows the syntax and semantic
from existing YANG models, re-using the same format as the reply to a
<get> operation/request) and annotates it with metadata.
NEW
running server available. This document specifies a standard file
format for YANG instance data, which follows the syntax and semantic
of existing YANG models, and annotates it with metadata.
BALAZS: Other have expressly asked for a reference to "get" but if you want
I can remove it.
* Terminology
- Add missing dots (full stops) at the end of sentences
BALAZS: OK
- I fail to see the difference between 'content-schema' and 'content
defining YANG module(s)'. The 'content-schema' is already a set of
YANG modules. I suggest to remove 'Content defining YANG module(s)
as it is not a necessary term. Rewrite all places where the phrase
'content defining YANG modules' is used.
BALAZS: a schema is a full set of YANG modules needed to define the
structure and properties of the instance data (+features, deviations).
A "content defining YANG module" is an individual YANG module is
part of the content-schema. So the difference is a set versus one item.
I updated the description to emphasize this difference.
- Is "YANG Instance Data" a newly defined term? It's introduction
does not follow the colon style. I also wonder why we need this
term. Why is YANG in there? I would prefer to have this defined in
RFC 7950 terms. Is 'instance data' a collection of instantiated
'data nodes'? Perhaps then we should do the following and move
this up to the first definition, so we define instance data first,
then instance data set, and finally instance data file.
OLD
YANG Instance Data, or just instance data for short, is data that
could be stored in a datastore and whose syntax and semantics is
defined by YANG models.
NEW
Instance Data: A collection of instantiated data nodes.
BALAZS: OK, updated.
* Introduction
- It seems UC5 subsumes UC4.
BALAS: OK UC4 and 5 merged
- One could add UCx: Storing instance data used as test cases but
then this list of use cases does not need to be exhaustive (means
I do not care much).
BALAZS: Valid use case, but not added for now. If you say so I can add it.
- Is it necessary to describe P2 in terms of (presumably) NETCONF
operations? I would prefer to have the document written in a
protocol agnostic style. Perhaps simply drop "similar to the
response of a <get> operation/request".
BALAZS: This is a reference both to NETCONF and RESTCONF. It was explicitly
asked for by other reviewers.
- P4: What is 'many'? Or did you want to use 'multiple'?
BALAZS: OK, changed to multiple,
* Instance Data File Format
- Replace "real data" with instance data
OLD
"real data" that we want to document/provide.
NEW
instance data that we want to document/provide.
BALAZS: OK
- I do not understand that text about the default attribute. Section
4.8.9 defines a query parameter, not an attribute. And I do not
know how that fits into content data.
BALAZS: https://tools.ietf.org/html/rfc8040#section-4.8.9:
" If the "with-defaults" parameter is set to "report-all-tagged", then
the server MUST adhere to the default-reporting behavior defined in
Section 3.4 of [RFC6243]. Metadata is reported by the server as
specified in Section 5.3. The XML encoding for the "default"
attribute sent by the server for default nodes is defined in
Section 6 of [RFC6243]. The JSON encoding for the "default"
attribute MUST use the same values, as defined in [RFC6243], but
encoded according to the rules in [RFC7952]. The module name
"ietf-netconf-with-defaults" MUST be used for the "default"
attribute. "
Here the usage of the default ATTRIBUTE is defined.
- Similarly, I do not understand why implementation specific
metadata may be included in the content-data. This seems to be the
wrong place, no? Should metadata not go into the header?
BALAZS: As this might be meta-data about the individual instance
data nodes (e.g. metadata following the principles from rfc7952) it belongs
here.
- Why MUST XML attributes be ignored, why is there no text about
unknown JSON data, 'attributes' (or annotations)? What should
implementations generally do about unknown elements, attributes,
objects, arrays, ...)? Why are we specific about only one specific
case?
BALAZS: Generally we want to allow users/creators to decorate the data
with additional information, that is not standardized. Like YANG extensions
these may be useful, but at least should not cause problems.
XML attributes are often used as meta-data and I was asked to list them
specifically.
It is not stated what an application should do with additional unknown data
(XML elements, JSON data) that do not fit the above categories. Should we
say something about it?
IMHO no. We don't want to be too restrictive, as there are many potential
users with different needs. We could state
"Users of the instance data MAY discard any other unknown data".
However that does not mean much.
- References may be helpful in this sentence since <get-data> is not
part of the original NETCONF specification:
The content-data part will be very similar to the result returned for
a NETCONF <get-data> or for a RESTCONF get operation.
BALAZS: OK: will add reference.
It is unclear what "will be very similar" really means but perhaps
this is clarified later. If not, this sentence says nothing in
terms of a technical specification.
- Does the following sentence imply that any additional data in an
instance file renders the instance file useless?
The content-data part MUST conform to the content-schema.
BALAZS: Maybe not useless, but at least partly corrupt.
- You first write that instance data MUST conform to the schema and
two paragraphs later you state that instance data MAY be partial,
i.e., it MAY NOT conform to the content-schema. Perhaps I have an
idea what you wanted to say but the text that is written here is
a contradiction.
BALAZS: OK. I will correct it. The content-data part MUST conform to
the content-schema, while allowing for the exceptions listed below.
- The introduction contains several MAYs and MUSTS that are not
understandable yet and they do not seem to belong into an
'Introduction' in the first place.
BALAZS: Section 2 Introduction 1 'may'
" further instance data formats may be specified"
I was specifically asked to include this. Why is this not understandable?
Where should this be if not in the introduction chapter?
Section 2 does not contain the word must.
Maybe I am not understanding your comment.
- Why is EXTERNAL in all caps but Inline in capitalized form? In
the YANG definitions, EXTERNAL seems to be uri. I think we reduce
ambiguity by being consistent with how we name things.
BALAZS: OK, EXTERNAL should not be all caps.
Here external means that the content-schema is defined externally
to the instance data set, not even a URI is included.
- What is a 'real-life YANG module'?
BALAZS: OK, will rephrase it.
- 3.1.1 How are the details specified in the anydata? Perhaps a
forward reference might help. What are 'version labels'?
BALAZS: Added reference to example.
Version/Revision labels are defined in
draft-verdt-netmod-yang-module-versioning;
added as a reference. I added them here (only as an example) as they are
highly relevant to specifying module versions even if they are not
agreed in Netmod yet. The name was changed from version-label to
revision-label lately.
- 3.1.2 What is a 'list of content'? Which revision is used? What
about these 'version labels' here?
BALAZS: You cut the sentence in half: List of content defining YANG modules"
The term "Content defining YANG module" is defined in the terminology
section.
In this case there is no possibility for using version/revision labels.
People asked for a simple method.
- 3.2 I do not understand the example. Has this been validated? As
far as I can tell, the ietf-yang-library defines modules-state and
not module-state. This inconsistency shows up multiple times.
BALAZS: Corrected to modules-state
- I like to understand why we need several methods to specify the
schema. Having N solution is always bad for interoperability and
also for maintainability. Perhaps the WG failed to reach consensus
on a single solution. Or there are strong technical reasons - but
then they should be clearly stated. What are implementations
expected to support, all methods? Or whatever the implementer
prefers? How do we achieve interoperability across tools?
BALAZS: Different people in the WG wanted different solutions.
- Some (as I remember you too) asked for a full flexible solution
which can use multiple modules potentially not even the
ietf-yang-library to define the schema (Inline solution)
- some asked for a simple solution listing the content schema modules
- some wanted just to use a reference (If any this is the one, I would
remove)
- some stated that they do not want to define the
content-schema at all because it is already known
So we ended up with 4 methods
* Data Life Cycle
- I am not sure the first paragraph is needed.
BALAZS: OK removed
- In the second paragraph, I like to see some discussion of snapshot
consistency. How much consistency can be expected? Are there
indicators for the level of consistency? I would remove the
sentence about "valid values can be retrieved at run-time" as this
is obvious but then I am not sure why 'valid' values? Perhaps the
authors meant 'current' values?
BALAZS: OK< Changed to current. I want to keep the second sentence
as it describes the duality between the original documented values and
the current values that can be read in run-time.
Consistency is out of scope. No indicators are provided. It is very
much use-case and implementation specific.
- How do I implement the "SHOULD be described"? The default is that
data can change, only in rare cases data is static. But how does a
tool creating instance data know 'when and how' data changes in the
future? I suggest to remove the SHOULD. The text saying that instance
data is a snapshot is in my view sufficient.
BALAZS: We do not want to specify the how the changes should be described,
But we do want to state that this information should be made available.
Just a few ideas how this could be done. Provide
- some plain text in the description of the instance data set
- some additional metadata e.g. etags, timestamp for the individual data
nodes.
- a change indicator in the content defining yang module itself
- This section talks about YANG instance data but it likely should
talk about YANG instance data sets.
BALAZS: I think both are acceptable terms here. Naturally if the data
changes
the data set containing it also changes.
* Delivery of Instance Data
- Why do we need this SHOULD? I do not think we should use RFC 2119
keywords to define how organizations may use the instance data
format. My proposal is to delete this entire section.
BALAZS: I will change it to lower case may.
I was asked to and I want to state that we want to use instance data
both for offline delivery of design time information and for run-time
delivery of other data.
(The first 3 users of this format all want to use this for early delivery of
server capabilities. It is for now the dominant use case for which the
2119 SHOULD is important.).
* Backwards Compatibility
- I do not think 'managed entity' is a YANG term.
BALAZS: What term do you propose for something that is managed like
an interface or user etc. ? I was told managed entity is a generic term
that is commonly understood . Would "managed item" or "managed thing" be
better?
- I think this text is use case specific and the items are kind of
conflicting with each other (2nd says changing the semantics of a
list should lead to a change of the key while the 1st suggests
that changing keys may lead to misinterpretation of something
being new).
- My proposal is to simply drop this entire section. If use case
specific text is needed, add it to the use cases in the appendix.
BALAZS: You don't know how many trouble reports we got in
multiple use-cases for violating these recommendations. While
they may not be important for all use-cases, the are important for many.
Actually we met the problem or had to avoid it in all but one of
the listed use-cases.
* YANG Model
- How is the inline-content-schema feature used? Which component
does indicate that inline content-schema is supported? Do all
implementations have to support simplified-inline? If
inline-schema is used, how do I find out which schema formats are
supported? The more formats there are, the more interoperability
issues will arise.
Balazs:
- case inline { is decorated with "if-feature inline-content-schema"
- feature support is generally indicated as part of the ietf-yang-library
- simplified-inline is mandatory to support. It is relatively simple, so
IMHO not a problem
- what do you mean with schema-formats? The yang schema is not actually
included anywhere.
If the "inline" case is used, instance data corresponding to the
inline-modules is included, not the schema.
anydata inline-schema {
description
"Instance data corresponding to the YANG modules
specified in the inline-module nodes defining the set
of content defining YANG modules for this
instance-data-set."
* Security Considerations
- "is designed as a wrapper" - what does this tell me? I suggest to
rewrite the first paragraph and to remove this phrase or to explain
what it means.
- Why is the header part not security sensitive? Almost all data is
security sensitive in certain situations.
BALAZS: IMHO it is a valid and meaningful statement to differentiate
between security sensitive data like passwords and non-sensitive data
like a revision date. RFC8341 states:
"One of the most important aspects of the data model documentation,
and one of the biggest concerns during deployment, is the
identification of security-sensitive content."
So the differentiation between sensitive and non-sensitive information is
important.
In your opinion which part of the header data is sensitive?
- I would prefer if the text would not use the phrase "result of a
<get> operation". As stated before, I like to see things written
in protocol neutral forms.
BALAZS: OK, I will change to the generic "read" operation as used by
RFC8341 (although for me <get> is much more clear).
- Since instance data files may require protection, is there any
recommendation how to do this, e.g., by wrapping everything into a
cryptographic message syntax or so? It would be important in
certain use cases to be able to verify that instance data is
authentic (i.e., it is signed by the original source). In other
cases, it may be crucial to protect the instance data itself
against occasional readers.
BALAZS: File security is an important but really big topic and
I was instructed by multiple people to avoid a half baked discussion on the
topic.
- It may be useful to explain that data in instance data sets may
have been filtered by access control rules like NACM and that data
in instance data sets itself won't be filtered anymore by access
control rules like NACM. In other words, if I take snapshots and
stored them as instance data files, these snapshots may leak
information that is otherwise protected. Hence it is important
that NACM rules and file access control rules are consistent.
BALAZS: We do not know if the instance data set was originally
filtered by NACM or not. We don't know if the users on
Netconf/Restconf/cli are the same as the users defined in the
file system., so I fear defining what consistent means would be impossible.
It is stated that " The same kind of handling should be applied, that would
be needed for the result of a <get> operation returning the same
data." IMHO we can't really say more.
--
Juergen Schoenwaelder Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax: +49 421 200 3103 <https://www.jacobs-university.de/>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
