Hi Juergen,
Did you get a chance to consider this proposed text for mandatory nodes
at all?
Thanks,
Rob
On 23/09/2015 14:50, Robert Wilton wrote:
Hi Juergen,
On 21/09/2015 09:26, Juergen Schoenwaelder wrote:
On Tue, Sep 15, 2015 at 10:00:46AM +0200, Ladislav Lhotka wrote:
Juergen Schoenwaelder <[email protected]> writes:
Still some text needs to be written explaining that breaking old
clients by adding new mandatory nodes is a no go. I did not ask to
enumerate all situations where it is allowed, I am looking for text
that clearly says what people have to look out for if they add
mandatory nodes.
Would it be sufficient to just change the MUST NOT to SHOULD NOT and
then reference section 5.17.2 of draft-ietf-netmod-rfc6087bis which
seems to provide the explanation that you are requesting?
E.g. something like:
draft-ietf-netmod-rfc6020bis, section 7.17. The augment Statement
From:
If the target node is in another module, then nodes added by the
augmentation MUST NOT be mandatory nodes (see Section 3.1).
To:
If the target node is in another module, then nodes added by the
augmentation SHOULD NOT be mandatory nodes (see Section 3.1). The
safe scenarios to augment with mandatory nodes are described in
[draft-ietf-netmod-rfc6087bis] section 5.17.2.
For reference, I've also reproduced the text for
draft-ietf-netmod-rfc6087bis-04] section 5.17.2 below:
5.17. Augment Statements
The YANG "augment" statement is used to define a set of data
definition statements that will be added as child nodes of a target
data node. The module namespace for these data nodes will be the
augmenting module, not the augmented module.
A top-level "augment" statement SHOULD NOT be used if the target data
node is in the same module or submodule as the evaluated "augment"
statement. The data definition statements SHOULD be added inline
instead.
5.17.1. Conditional Augment Statements
The "augment" statement is often used together with the "when"
statement and/or "if-feature" statement to make the augmentation
conditional on some portion of the data model.
The following example from [RFC7223] shows how a conditional
container called "ethernet" is added to the "interface" list only for
entries of the type "ethernetCsmacd".
augment "/if:interfaces/if:interface" {
when "if:type = 'ianaift:ethernetCsmacd'";
container ethernet {
leaf duplex {
...
}
}
}
5.17.2. Conditionally Mandatory Data Definition Statements
YANG has very specific rules about how configuration data can be
updated in new releases of a module. These rules allow an "old
client" to continue interoperating with a "new server".
If data nodes are added to an existing entry, the old client MUST NOT
be required to provide any mandatory parameters that were not in the
original module definition.
It is possible to add conditional augment statements such that the
old client would not know about the new condition, and would not
specify the new condition. The conditional augment statement can
contain mandatory objects only if the condition is false unless
explicitly requested by the client.
Only a conditional augment statement that uses the "when" statement
form of condition can be used in this manner. The YANG features
enabled on the server cannot be controlled by the client in any way,
so it is not safe to add mandatory augmenting data nodes based on the
"if-feature" statement.
The XPath "when" statement condition MUST NOT reference data outside
of target data node because the client does not have any control over
this external data.
In the following dummy example, it is OK to augment the "interface"
entry with "mandatory-leaf" because the augmentation depends on
support for "some-new-iftype". The old client does not know about
this type so it would never select this type, and therefore not be
adding a mandatory data node.
module my-module {
...
identity some-new-iftype {
base iana:iana-interface-type;
}
augment "/if:interfaces/if:interface" {
when "if:type = 'mymod:some-new-iftype'";
leaf mandatory-leaf {
mandatory true;
...
}
}
}
Note that this practice is safe only for creating data resources. It
is not safe for replacing or modifying resources if the client does
not know about the new condition. The YANG data model MUST be
packaged in a way that requires the client to be aware of the
mandatory data nodes if it is aware of the condition for this data.
In the example above, the "some-new-iftype" identity is defined in
the same module as the "mandatory-leaf" data definition statement.
This practice is not safe for identities defined in a common module
such as "iana-if-type" because the client is not required to know
about "my-module" just because it knows about the "iana-if-type"
module.
Rob
/js
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
