idnits 2.17.1
draft-ietf-netmod-schema-mount-12.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 344 has weird spacing: '... prefix yan...'
-- The document date (October 17, 2018) is 2018 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Missing Reference: 'RFC 2119' is mentioned on line 605, but not defined
== Outdated reference: A later version (-07) exists of
draft-ietf-netconf-rfc7895bis-06
** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446)
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
-- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH'
== Outdated reference: A later version (-42) exists of
draft-ietf-isis-yang-isis-cfg-24
Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Bjorklund
3 Internet-Draft Tail-f Systems
4 Intended status: Standards Track L. Lhotka
5 Expires: April 20, 2019 CZ.NIC
6 October 17, 2018
8 YANG Schema Mount
9 draft-ietf-netmod-schema-mount-12
11 Abstract
13 This document defines a mechanism to add the schema trees defined by
14 a set of YANG modules onto a mount point defined in the schema tree
15 in some YANG module.
17 Status of This Memo
19 This Internet-Draft is submitted in full conformance with the
20 provisions of BCP 78 and BCP 79.
22 Internet-Drafts are working documents of the Internet Engineering
23 Task Force (IETF). Note that other groups may also distribute
24 working documents as Internet-Drafts. The list of current Internet-
25 Drafts is at http://datatracker.ietf.org/drafts/current/.
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference
30 material or to cite them other than as "work in progress."
32 This Internet-Draft will expire on April 20, 2019.
34 Copyright Notice
36 Copyright (c) 2018 IETF Trust and the persons identified as the
37 document authors. All rights reserved.
39 This document is subject to BCP 78 and the IETF Trust's Legal
40 Provisions Relating to IETF Documents
41 (http://trustee.ietf.org/license-info) in effect on the date of
42 publication of this document. Please review these documents
43 carefully, as they describe your rights and restrictions with respect
44 to this document. Code Components extracted from this document must
45 include Simplified BSD License text as described in Section 4.e of
46 the Trust Legal Provisions and are provided without warranty as
47 described in the Simplified BSD License.
49 Table of Contents
51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
52 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5
53 2.1. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 6
54 2.2. Namespace Prefixes . . . . . . . . . . . . . . . . . . . 6
55 3. Schema Mount . . . . . . . . . . . . . . . . . . . . . . . . 7
56 3.1. Mount Point Definition . . . . . . . . . . . . . . . . . 7
57 3.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 8
58 3.3. Specification of the Mounted Schema . . . . . . . . . . . 8
59 3.4. Multiple Levels of Schema Mount . . . . . . . . . . . . . 9
60 4. Referring to Data Nodes in the Parent Schema . . . . . . . . 9
61 5. RPC operations and Notifications . . . . . . . . . . . . . . 11
62 6. Network Management Datastore Architecture (NMDA)
63 Considerations . . . . . . . . . . . . . . . . . . . . . . . 11
64 7. Interaction with the Network Configuration Access Control
65 Model (NACM) . . . . . . . . . . . . . . . . . . . . . . . . 11
66 8. Implementation Notes . . . . . . . . . . . . . . . . . . . . 12
67 9. Schema Mount YANG Module . . . . . . . . . . . . . . . . . . 12
68 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
69 11. Security Considerations . . . . . . . . . . . . . . . . . . . 17
70 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18
71 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 19
72 13.1. Normative References . . . . . . . . . . . . . . . . . . 19
73 13.2. Informative References . . . . . . . . . . . . . . . . . 20
74 Appendix A. Example: Device Model with LNEs and NIs . . . . . . 21
75 A.1. Physical Device . . . . . . . . . . . . . . . . . . . . . 21
76 A.2. Logical Network Elements . . . . . . . . . . . . . . . . 23
77 A.3. Network Instances . . . . . . . . . . . . . . . . . . . . 26
78 A.4. Invoking an RPC Operation . . . . . . . . . . . . . . . . 27
79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
81 1. Introduction
83 Modularity and extensibility were among the leading design principles
84 of the YANG data modeling language. As a result, the same YANG
85 module can be combined with various sets of other modules and thus
86 form a data model that is tailored to meet the requirements of a
87 specific use case. Server implementors are only required to specify
88 all YANG modules comprising the data model (together with their
89 revisions and other optional choices) in the YANG library data
90 ([RFC7895], [I-D.ietf-netconf-rfc7895bis] and Section 5.6.4 of
91 [RFC7950]) implemented by the server. Such YANG modules appear in
92 the data model "side by side", i.e., top-level data nodes of each
93 module - if there are any - are also top-level nodes of the overall
94 data model.
96 YANG has two mechanisms for contributing a schema hierarchy defined
97 elsewhere to the contents of an internal node of the schema tree;
98 these mechanisms are realized through the following YANG statements:
100 o The "uses" statement explicitly incorporates the contents of a
101 grouping defined in the same or another module. See Section 4.2.6
102 of [RFC7950] for more details.
104 o The "augment" statement explicitly adds contents to a target node
105 defined in the same or another module. See Section 4.2.8 of
106 [RFC7950] for more details.
108 With both mechanisms, the YANG module with the "uses" or "augment"
109 statement explicitly defines the exact location in the schema tree
110 where the new nodes are placed.
112 In some cases these mechanisms are not sufficient; it is sometimes
113 necessary that an existing module (or a set of modules) is added to
114 the data model starting at locations other than the root. For
115 example, YANG modules such as "ietf-interfaces" [RFC8343] are defined
116 so as to be used in a data model of a physical device. Now suppose
117 we want to model a device that supports multiple logical devices
118 [I-D.ietf-rtgwg-lne-model], each of which has its own instantiation
119 of "ietf-interfaces", and possibly other modules, but, at the same
120 time, we want to be able to manage all these logical devices from the
121 master device. Hence, we would like to have a schema tree like this:
123 +--rw interfaces
124 | +--rw interface* [name]
125 | ...
126 +--rw logical-network-element* [name]
127 +--rw name
128 | ...
129 +--rw interfaces
130 +--rw interface* [name]
131 ...
133 With the "uses" approach, the complete schema tree of
134 "ietf-interfaces" would have to be wrapped in a grouping, and then
135 this grouping would have to be used at the top level (for the master
136 device) and then also in the "logical-network-element" list (for the
137 logical devices). This approach has several disadvantages:
139 o It is not scalable because every time there is a new YANG module
140 that needs to be added to the logical device model, we have to
141 update the model for logical devices with another "uses" statement
142 pulling in contents of the new module.
144 o Absolute references to nodes defined inside a grouping may break
145 if the grouping is used in different locations.
147 o Nodes defined inside a grouping belong to the namespace of the
148 module where it is used, which makes references to such nodes from
149 other modules difficult or even impossible.
151 o It would be difficult for vendors to add proprietary modules when
152 the "uses" statements are defined in a standard module.
154 With the "augment" approach, "ietf-interfaces" would have to augment
155 the "logical-network-element" list with all its nodes, and at the
156 same time define all its nodes at the top level. The same hierarchy
157 of nodes would thus have to be defined twice, which is clearly not
158 scalable either.
160 This document introduces a new mechanism, denoted as schema mount,
161 that allows for mounting one data model consisting of any number of
162 YANG modules at a specified location of another (parent) schema.
163 Unlike the "uses" and "augment" approaches discussed above, the
164 mounted modules needn't be specially prepared for mounting and,
165 consequently, existing modules such as "ietf-interfaces" can be
166 mounted without any modifications.
168 The basic idea of schema mount is to label a data node in the parent
169 schema as the mount point, and then define a complete data model to
170 be attached to the mount point so that the labeled data node
171 effectively becomes the root node of the mounted data model.
173 In principle, the mounted schema can be specified at three different
174 phases of the data model life cycle:
176 1. Design-time: the mounted schema is defined along with the mount
177 point in the parent YANG module. In this case, the mounted
178 schema has to be the same for every implementation of the parent
179 module.
181 2. Implementation-time: the mounted schema is defined by a server
182 implementor and is as stable as the YANG library information of
183 the server.
185 3. Run-time: the mounted schema is defined by instance data that is
186 part of the mounted data model. If there are multiple instances
187 of the same mount point (e.g., in multiple entries of a list),
188 the mounted data model may be different for each instance.
190 The schema mount mechanism defined in this document provides support
191 only for the latter two cases. Design-time mounts are outside the
192 scope of this document, and could be possibly dealt with in a future
193 revision of the YANG data modeling language.
195 Schema mount applies to the data model, and specifically does not
196 assume anything about the source of instance data for the mounted
197 schemas. It may be implemented using the same instrumentation as the
198 rest of the system, or it may be implemented by querying some other
199 system. Future specifications may define mechanisms to control or
200 monitor the implementation of specific mount points.
202 How and when specific mount points are instantiated by the server is
203 out of scope for this document. Such mechanisms may be defined in
204 future specifications.
206 This document allows mounting of complete data models only. Other
207 specifications may extend this model by defining additional
208 mechanisms such as mounting sub-hierarchies of a module.
210 The YANG modules in this document conform to the Network Management
211 Datastore Architecture (NMDA) [RFC8342].
213 2. Terminology and Notation
215 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
216 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
217 "OPTIONAL" in this document are to be interpreted as described in BCP
218 14 [RFC2119] [RFC8174] when, and only when, they appear in all
219 capitals, as shown here.
221 The following terms are defined in [RFC7950] and are not redefined
222 here:
224 o action
226 o container
228 o data node
230 o list
232 o RPC operation
234 o schema node
236 o schema tree
238 The following terms are defined in [RFC8342] and are not redefined
239 here:
241 o client
243 o notification
245 o operational state
247 o server
249 The following term is defined in [RFC8343] and is not redefined here:
251 o system-controlled interface
253 The following term is defined in [I-D.ietf-netconf-rfc7895bis] is not
254 redefined here:
256 o YANG library content identifier
258 The following additional terms are used within this document:
260 o mount point: A container or a list node whose definition contains
261 the "mount-point" extension statement. The argument of the
262 "mount-point" statement defines a label for the mount point.
264 o schema: A collection of schema trees with a common root.
266 o top-level schema: A schema rooted at the root node.
268 o mounted schema: A schema rooted at a mount point.
270 o parent schema (of a mounted schema): A schema containing the mount
271 point.
273 o schema mount: The mechanism to combine data models defined in this
274 document.
276 2.1. Tree Diagrams
278 Tree diagrams used in this document follow the notation defined in
279 [RFC8340]
281 2.2. Namespace Prefixes
283 In this document, names of data nodes, YANG extensions, actions and
284 other data model objects are often used without a prefix, as long as
285 it is clear from the context in which YANG module each name is
286 defined. Otherwise, names are prefixed using the standard prefix
287 associated with the corresponding YANG module, as shown in Table 1.
289 +---------+------------------------+--------------------------------+
290 | Prefix | YANG module | Reference |
291 +---------+------------------------+--------------------------------+
292 | yangmnt | ietf-yang-schema-mount | Section 9 |
293 | inet | ietf-inet-types | [RFC6991] |
294 | yang | ietf-yang-types | [RFC6991] |
295 | yanglib | ietf-yang-library | [RFC7895], |
296 | | | [I-D.ietf-netconf-rfc7895bis] |
297 +---------+------------------------+--------------------------------+
299 Table 1: Namespace Prefixes
301 3. Schema Mount
303 The schema mount mechanism defined in this document provides a new
304 extensibility mechanism for use with YANG 1.1. In contrast to the
305 existing mechanisms described in Section 1, schema mount defines the
306 relationship between the source and target YANG modules outside these
307 modules. The procedure consists of two separate steps that are
308 described in the following subsections.
310 3.1. Mount Point Definition
312 A "container" or "list" node becomes a mount point if the
313 "mount-point" extension (defined in the "ietf-yang-schema-mount"
314 module) is used in its definition. This extension can appear only as
315 a substatement of "container" and "list" statements.
317 The argument of the "mount-point" extension is a YANG identifier that
318 defines a label for the mount point. A module MAY contain multiple
319 "mount-point" statements having the same argument.
321 It is therefore up to the designer of the parent schema to decide
322 about the placement of mount points. A mount point can also be made
323 conditional by placing "if-feature" and/or "when" as substatements of
324 the "container" or "list" statement that represents the mount point.
326 The "mount-point" statement MUST NOT be used in a YANG version 1
327 module [RFC6020]. The reason for this is that otherwise it is not
328 possible to invoke mounted RPC operations, and receive mounted
329 notifications. See Section 5 for details. Note, however, that
330 modules written in any YANG version, including version 1, can be
331 mounted under a mount point.
333 Note that the "mount-point" statement does not define a new data
334 node.
336 3.2. Data Model
338 This document defines the YANG 1.1 module [RFC7950]
339 "ietf-yang-schema-mount", which has the following structure:
341 module: ietf-yang-schema-mount
342 +--ro schema-mounts
343 +--ro namespace* [prefix]
344 | +--ro prefix yang:yang-identifier
345 | +--ro uri? inet:uri
346 +--ro mount-point* [module label]
347 +--ro module yang:yang-identifier
348 +--ro label yang:yang-identifier
349 +--ro config? boolean
350 +--ro (schema-ref)
351 +--:(inline)
352 | +--ro inline!
353 +--:(shared-schema)
354 +--ro shared-schema!
355 +--ro parent-reference* yang:xpath1.0
357 3.3. Specification of the Mounted Schema
359 Mounted schemas for all mount points in the parent schema are
360 determined from state data in the "/schema-mounts" container.
362 Generally, the modules that are mounted under a mount point have no
363 relation to the modules in the parent schema; specifically, if a
364 module is mounted it may or may not be present in the parent schema
365 and, if present, its data will generally have no relationship to the
366 data of the parent. Exceptions are possible and such needs to be
367 defined in the model defining the exception. For example,
368 [I-D.ietf-rtgwg-lne-model] defines a mechanism to bind interfaces to
369 mounted logical network elements.
371 The "/schema-mounts" container has the "mount-point" list as one of
372 its children. Every entry of this list refers through its key to a
373 mount point and specifies the mounted schema.
375 If a mount point is defined in the parent schema but does not have an
376 entry in the "mount-point" list, then the mounted schema is void,
377 i.e., instances of that mount point MUST NOT contain any data except
378 those that are defined in the parent schema.
380 If multiple mount points with the same name are defined in the same
381 module - either directly or because the mount point is defined in a
382 grouping and the grouping is used multiple times - then the
383 corresponding "mount-point" entry applies equally to all such mount
384 points.
386 The "config" property of mounted schema nodes is overridden and all
387 nodes in the mounted schema are read-only ("config false") if at
388 least one of the following conditions is satisfied for a mount point:
390 o the mount point is itself defined as "config false"
392 o the "config" leaf in the corresponding entry of the "mount-point"
393 list is set to "false".
395 An entry of the "mount-point" list can specify the mounted schema in
396 two different ways, "inline" or "shared-schema".
398 The mounted schema is determined at run time: every instance of the
399 mount point that exists in the operational state MUST contain a copy
400 of YANG library data that defines the mounted schema exactly as for a
401 top-level schema. A client is expected to retrieve this data from
402 the instance tree. In the "inline" case, instances of the same mount
403 point MAY use different mounted schemas, whereas in the
404 "shared-schema" case, all instances MUST use the same mounted schema.
405 This means that in the "shared-schema" case, all instances of the
406 same mount point MUST have the same YANG library content identifier.
407 In the "inline" case, if two instances have the same YANG library
408 content identifier it is not guaranteed that the YANG library
409 contents are equal for these instances.
411 Examples of "inline" and "shared-schema" can be found in Appendix A.2
412 and Appendix A.3, respectively.
414 3.4. Multiple Levels of Schema Mount
416 YANG modules in a mounted schema MAY again contain mount points under
417 which other schemas can be mounted. Consequently, it is possible to
418 construct data models with an arbitrary number of mounted schemas. A
419 schema for a mount point contained in a mounted module can be
420 specified by implementing "ietf-yang-library" and
421 "ietf-yang-schema-mount" modules in the mounted schema, and
422 specifying the schemas exactly as it is done in the top-level schema.
424 4. Referring to Data Nodes in the Parent Schema
426 A fundamental design principle of schema mount is that the mounted
427 schema works exactly as a top-level schema, i.e., it is confined to
428 the "mount jail". This means that all paths in the mounted schema
429 (in leafrefs, instance-identifiers, XPath [XPATH] expressions, and
430 target nodes of augments) are interpreted with the mount point as the
431 root node. YANG modules of the mounted schema as well as
432 corresponding instance data thus cannot refer to schema nodes or
433 instance data outside the mount jail.
435 However, this restriction is sometimes too severe. A typical example
436 is network instances (NI) [I-D.ietf-rtgwg-ni-model], where each NI
437 has its own routing engine but the list of interfaces is global and
438 shared by all NIs. If we want to model this organization with the NI
439 schema mounted using schema mount, the overall schema tree would look
440 schematically as follows:
442 +--rw interfaces
443 | +--rw interface* [name]
444 | ...
445 +--rw network-instances
446 +--rw network-instance* [name]
447 +--rw name
448 +--rw root
449 +--rw routing
450 ...
452 Here, the "root" node is the mount point for the NI schema. Routing
453 configuration inside an NI often needs to refer to interfaces (at
454 least those that are assigned to the NI), which is impossible unless
455 such a reference can point to a node in the parent schema (interface
456 name).
458 Therefore, schema mount also allows for such references. For every
459 mount point in the "shared-schema" case, it is possible to specify a
460 leaf-list named "parent-reference" that contains zero or more XPath
461 1.0 expressions. Each expression is evaluated with the node in the
462 parent data tree where the mount point is defined as the context
463 node. The result of this evaluation MUST be a nodeset (see the
464 description of the "parent-reference" node for a complete definition
465 of the evaluation context). For the purposes of evaluating XPath
466 expressions within the mounted data tree, the union of all such
467 nodesets is added to the accessible data tree.
469 It is worth emphasizing that the nodes specified in
470 "parent-reference" leaf-list are available in the mounted schema only
471 for XPath evaluations. In particular, they cannot be accessed there
472 via network management protocols such as NETCONF [RFC6241] or
473 RESTCONF [RFC8040].
475 5. RPC operations and Notifications
477 If a mounted YANG module defines an RPC operation, clients can invoke
478 this operation as if it were defined as an action for the
479 corresponding mount point, see Section 7.15 of [RFC7950]. An example
480 of this is given in Appendix A.4.
482 Similarly, if the server emits a notification defined at the top
483 level of any mounted module, it MUST be represented as if the
484 notification was connected to the mount point, see Section 7.16 of
485 [RFC7950].
487 Note, inline actions and notifications will not work when they are
488 contained within a list node without a "key" statement (see section
489 7.15 and 7.16 of [RFC7950]). Therefore, to be useful, mount points
490 that contain modules with RPCs, actions, and notifications SHOULD NOT
491 have any ancestor node that is a list node without a "key" statement.
492 This requirement applies to the definition of modules using the
493 "mount-point" extension statement.
495 6. Network Management Datastore Architecture (NMDA) Considerations
497 The schema mount solution presented in this document is designed to
498 work both with servers that implement the NMDA [RFC8342], and old
499 servers that don't implement the NMDA.
501 Note to RFC Editor: please update the date YYYY-MM-DD below with the
502 revision of the ietf-yang-library in the published version of draft-
503 ietf-netconf-rfc7895bis, and remove this note.
505 Specifically, a server that doesn't support the NMDA, MAY implement
506 revision 2016-06-21 of "ietf-yang-library" [RFC7895] under a mount
507 point. A server that supports the NMDA, MUST implement at least
508 revision YYYY-MM-DD of "ietf-yang-library"
509 [I-D.ietf-netconf-rfc7895bis] under the mount points.
511 7. Interaction with the Network Configuration Access Control Model
512 (NACM)
514 If NACM [RFC8341] is implemented on a server, it is used to control
515 access to nodes defined by the mounted schema in the same way as for
516 nodes defined by the top-level schema.
518 For example, suppose the module "ietf-interfaces" is mounted in the
519 "root" container in the "logical-network-element" list defined in
520 [I-D.ietf-rtgwg-lne-model]. Then the following NACM path can be used
521 to control access to the "interfaces" container (where the character
522 '\' is used where a line break has been inserted for formatting
523 reasons):
525
528 /lne:logical-network-elements\
529 /lne:logical-network-element/lne:root/if:interfaces
530
532 8. Implementation Notes
534 Network management of devices that use a data model with schema mount
535 can be implemented in different ways. However, the following
536 implementations options are envisioned as typical:
538 o shared management: instance data of both parent and mounted
539 schemas are accessible within the same management session.
541 o split management: one (master) management session has access to
542 instance data of both parent and mounted schemas but, in addition,
543 an extra session exists for every instance of the mount point,
544 having access only to the mounted data tree.
546 9. Schema Mount YANG Module
548 This module references [RFC6991].
550 file "ietf-yang-schema-mount@2018-10-16"
552 module ietf-yang-schema-mount {
553 yang-version 1.1;
554 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount";
555 prefix yangmnt;
557 import ietf-inet-types {
558 prefix inet;
559 reference
560 "RFC 6991: Common YANG Data Types";
561 }
563 import ietf-yang-types {
564 prefix yang;
565 reference
566 "RFC 6991: Common YANG Data Types";
567 }
569 organization
570 "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
572 contact
573 "WG Web:
574 WG List:
576 Editor: Martin Bjorklund
577
579 Editor: Ladislav Lhotka
580 ";
582 // RFC Ed.: replace XXXX with actual RFC number and
583 // remove this note.
584 description
585 "This module defines a YANG extension statement that can be used
586 to incorporate data models defined in other YANG modules in a
587 module. It also defines operational state data that specify the
588 overall structure of the data model.
590 Copyright (c) 2018 IETF Trust and the persons identified as
591 authors of the code. All rights reserved.
593 Redistribution and use in source and binary forms, with or
594 without modification, is permitted pursuant to, and subject to
595 the license terms contained in, the Simplified BSD License set
596 forth in Section 4.c of the IETF Trust's Legal Provisions
597 Relating to IETF Documents
598 (https://trustee.ietf.org/license-info).
600 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
601 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
602 'MAY', and 'OPTIONAL' in the module text are to be interpreted
603 as described in BCP 14 [RFC 2119] [RFC8174] when, and only when,
604 they appear in all capitals, as shown here.
606 This version of this YANG module is part of RFC XXXX
607 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for
608 full legal notices.";
610 // RFC Ed.: update the date below with the date of RFC publication
611 // and remove this note.
612 revision 2018-10-16 {
613 description
614 "Initial revision.";
615 reference
616 "RFC XXXX: YANG Schema Mount";
617 }
618 /*
619 * Extensions
620 */
622 extension mount-point {
623 argument label;
624 description
625 "The argument 'label' is a YANG identifier, i.e., it is of the
626 type 'yang:yang-identifier'.
628 The 'mount-point' statement MUST NOT be used in a YANG
629 version 1 module, neither explicitly nor via a 'uses'
630 statement.
632 The 'mount-point' statement MAY be present as a substatement
633 of 'container' and 'list', and MUST NOT be present elsewhere.
634 There MUST NOT be more than one 'mount-point' statement in a
635 given 'container' or 'list' statement.
637 If a mount point is defined within a grouping, its label is
638 bound to the module where the grouping is used.
640 A mount point defines a place in the node hierarchy where
641 other data models may be attached. A server that implements a
642 module with a mount point populates the
643 /schema-mounts/mount-point list with detailed information on
644 which data models are mounted at each mount point.
646 Note that the 'mount-point' statement does not define a new
647 data node.";
648 }
650 /*
651 * State data nodes
652 */
654 container schema-mounts {
655 config false;
656 description
657 "Contains information about the structure of the overall
658 mounted data model implemented in the server.";
659 list namespace {
660 key "prefix";
661 description
662 "This list provides a mapping of namespace prefixes that are
663 used in XPath expressions of 'parent-reference' leafs to the
664 corresponding namespace URI references.";
665 leaf prefix {
666 type yang:yang-identifier;
667 description
668 "Namespace prefix.";
669 }
670 leaf uri {
671 type inet:uri;
672 description
673 "Namespace URI reference.";
674 }
675 }
676 list mount-point {
677 key "module label";
678 description
679 "Each entry of this list specifies a schema for a particular
680 mount point.
682 Each mount point MUST be defined using the 'mount-point'
683 extension in one of the modules listed in the server's
684 YANG library instance with conformance type 'implement'.";
685 leaf module {
686 type yang:yang-identifier;
687 description
688 "Name of a module containing the mount point.";
689 }
690 leaf label {
691 type yang:yang-identifier;
692 description
693 "Label of the mount point defined using the 'mount-point'
694 extension.";
695 }
696 leaf config {
697 type boolean;
698 default "true";
699 description
700 "If this leaf is set to 'false', then all data nodes in the
701 mounted schema are read-only (config false), regardless of
702 their 'config' property.";
703 }
704 choice schema-ref {
705 mandatory true;
706 description
707 "Alternatives for specifying the schema.";
708 container inline {
709 presence
710 "A complete self-contained schema is mounted at the
711 mount point.";
712 description
713 "This node indicates that the server has mounted at least
714 the module 'ietf-yang-library' at the mount point, and
715 its instantiation provides the information about the
716 mounted schema.
718 Different instances of the mount point may have
719 different schemas mounted.";
720 }
721 container shared-schema {
722 presence
723 "The mounted schema together with the 'parent-reference'
724 make up the schema for this mount point.";
725 description
726 "This node indicates that the server has mounted at least
727 the module 'ietf-yang-library' at the mount point, and
728 its instantiation provides the information about the
729 mounted schema. When XPath expressions in the mounted
730 schema are evaluated, the 'parent-reference' leaf-list
731 is taken into account.
733 Different instances of the mount point MUST have the
734 same schema mounted.";
735 leaf-list parent-reference {
736 type yang:xpath1.0;
737 description
738 "Entries of this leaf-list are XPath 1.0 expressions
739 that are evaluated in the following context:
741 - The context node is the node in the parent data tree
742 where the mount-point is defined.
744 - The accessible tree is the parent data tree
745 *without* any nodes defined in modules that are
746 mounted inside the parent schema.
748 - The context position and context size are both equal
749 to 1.
751 - The set of variable bindings is empty.
753 - The function library is the core function library
754 defined in [XPath] and the functions defined in
755 Section 10 of [RFC7950].
757 - The set of namespace declarations is defined by the
758 'namespace' list under 'schema-mounts'.
760 Each XPath expression MUST evaluate to a nodeset
761 (possibly empty). For the purposes of evaluating XPath
762 expressions whose context nodes are defined in the
763 mounted schema, the union of all these nodesets
764 together with ancestor nodes are added to the
765 accessible data tree.
767 Note that in the case 'ietf-yang-schema-mount' is
768 itself mounted, a 'parent-reference' in the mounted
769 module may refer to nodes that were brought into the
770 accessible tree through a 'parent-reference' in the
771 parent schema.";
772 }
773 }
774 }
775 }
776 }
777 }
779
781 10. IANA Considerations
783 This document registers a URI in the IETF XML registry [RFC3688].
784 Following the format in RFC 3688, the following registration is
785 requested to be made.
787 URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
789 Registrant Contact: The IESG.
791 XML: N/A, the requested URI is an XML namespace.
793 This document registers a YANG module in the YANG Module Names
794 registry [RFC6020].
796 name: ietf-yang-schema-mount
797 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
798 prefix: yangmnt
799 reference: RFC XXXX
801 11. Security Considerations
803 YANG module "ietf-yang-schema-mount" specified in this document
804 defines a schema for data that is designed to be accessed via network
805 management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040].
806 The lowest NETCONF layer is the secure transport layer, and the
807 mandatory-to-implement secure transport is Secure Shell (SSH)
808 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-
809 implement secure transport is TLS [RFC5246].
811 The network configuration access control model [RFC8341] provides the
812 means to restrict access for particular NETCONF or RESTCONF users to
813 a preconfigured subset of all available NETCONF or RESTCONF protocol
814 operations and content.
816 Some of the readable data nodes in this YANG module may be considered
817 sensitive or vulnerable in some network environments. It is thus
818 important to control read access (e.g., via get, get-config, or
819 notification) to these data nodes. These are the subtrees and data
820 nodes and their sensitivity/vulnerability:
822 o /schema-mounts: The schema defined by this state data provides
823 detailed information about a server implementation may help an
824 attacker identify the server capabilities and server
825 implementations with known bugs. Server vulnerabilities may be
826 specific to particular modules included in the schema, module
827 revisions, module features, or even module deviations. For
828 example, if a particular operation on a particular data node is
829 known to cause a server to crash or significantly degrade device
830 performance, then the schema information will help an attacker
831 identify server implementations with such a defect, in order to
832 launch a denial-of-service attack on the device.
834 It is important to take the security considerations for all nodes in
835 the mounted schemas into account, and control access to these nodes
836 by using the mechanism described in Section 7.
838 Care must be taken when the "parent-reference" XPath expressions are
839 constructed, since the result of the evaluation of these expressions
840 is added to the accessible tree for any XPath expression found in the
841 mounted schema.
843 12. Contributors
845 The idea of having some way to combine schemas from different YANG
846 modules into one has been proposed independently by several groups of
847 people: Alexander Clemm, Jan Medved, and Eric Voit
848 ([I-D.clemm-netmod-mount]); and Lou Berger and Christian Hopps:
850 o Lou Berger, LabN Consulting, L.L.C.,
852 o Alexander Clemm, Huawei,
854 o Christian Hopps, Deutsche Telekom,
856 o Jan Medved, Cisco,
858 o Eric Voit, Cisco,
860 13. References
862 13.1. Normative References
864 [I-D.ietf-netconf-rfc7895bis]
865 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
866 and R. Wilton, "YANG Library", draft-ietf-netconf-
867 rfc7895bis-06 (work in progress), April 2018.
869 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
870 Requirement Levels", BCP 14, RFC 2119,
871 DOI 10.17487/RFC2119, March 1997, .
874 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
875 DOI 10.17487/RFC3688, January 2004, .
878 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
879 (TLS) Protocol Version 1.2", RFC 5246,
880 DOI 10.17487/RFC5246, August 2008, .
883 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
884 the Network Configuration Protocol (NETCONF)", RFC 6020,
885 DOI 10.17487/RFC6020, October 2010, .
888 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
889 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
890 .
892 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
893 RFC 6991, DOI 10.17487/RFC6991, July 2013,
894 .
896 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
897 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
898 .
900 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
901 RFC 7950, DOI 10.17487/RFC7950, August 2016,
902 .
904 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
905 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
906 May 2017, .
908 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
909 Access Control Model", STD 91, RFC 8341,
910 DOI 10.17487/RFC8341, March 2018, .
913 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
914 and R. Wilton, "Network Management Datastore Architecture
915 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
916 .
918 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
919 Version 1.0", World Wide Web Consortium Recommendation
920 REC-xpath-19991116, November 1999,
921 .
923 13.2. Informative References
925 [I-D.clemm-netmod-mount]
926 Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined
927 Information from Remote Datastores", draft-clemm-netmod-
928 mount-06 (work in progress), March 2017.
930 [I-D.ietf-isis-yang-isis-cfg]
931 Litkowski, S., Yeung, D., Lindem, A., Zhang, Z., and L.
932 Lhotka, "YANG Data Model for IS-IS protocol", draft-ietf-
933 isis-yang-isis-cfg-24 (work in progress), August 2018.
935 [I-D.ietf-rtgwg-device-model]
936 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps,
937 "Network Device YANG Logical Organization", draft-ietf-
938 rtgwg-device-model-02 (work in progress), March 2017.
940 [I-D.ietf-rtgwg-lne-model]
941 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
942 Liu, "YANG Model for Logical Network Elements", draft-
943 ietf-rtgwg-lne-model-10 (work in progress), March 2018.
945 [I-D.ietf-rtgwg-ni-model]
946 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
947 Liu, "YANG Model for Network Instances", draft-ietf-rtgwg-
948 ni-model-12 (work in progress), March 2018.
950 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
951 and A. Bierman, Ed., "Network Configuration Protocol
952 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
953 .
955 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
956 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
957 .
959 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
960 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
961 .
963 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
964 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
965 .
967 Appendix A. Example: Device Model with LNEs and NIs
969 This non-normative example demonstrates an implementation of the
970 device model as specified in Section 2 of
971 [I-D.ietf-rtgwg-device-model], using both logical network elements
972 (LNE) and network instances (NI).
974 In these examples, the character '\' is used where a line break has
975 been inserted for formatting reasons.
977 A.1. Physical Device
979 The data model for the physical device may be described by this YANG
980 library content, assuming the server supports the NMDA:
982 {
983 "ietf-yang-library:yang-library": {
984 "content-id": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899",
985 "module-set": [
986 {
987 "name": "physical-device-modules",
988 "module": [
989 {
990 "name": "ietf-datastores",
991 "revision": "2018-02-14",
992 "namespace":
993 "urn:ietf:params:xml:ns:yang:ietf-datastores"
994 },
995 {
996 "name": "iana-if-type",
997 "revision": "2015-06-12",
998 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type"
999 },
1000 {
1001 "name": "ietf-interfaces",
1002 "revision": "2018-02-20",
1003 "feature": ["arbitrary-names", "pre-provisioning" ],
1004 "namespace":
1005 "urn:ietf:params:xml:ns:yang:ietf-interfaces"
1006 },
1007 {
1008 "name": "ietf-ip",
1009 "revision": "2018-02-22",
1010 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip"
1011 },
1012 {
1013 "name": "ietf-logical-network-element",
1014 "revision": "2016-10-21",
1015 "feature": [ "bind-lne-name" ],
1016 "namespace":
1017 "urn:ietf:params:xml:ns:yang:\
1018 ietf-logical-network-element"
1019 },
1020 {
1021 "name": "ietf-yang-library",
1022 "revision": "2018-02-21",
1023 "namespace":
1024 "urn:ietf:params:xml:ns:yang:ietf-yang-library"
1025 },
1026 {
1027 "name": "ietf-yang-schema-mount",
1028 "revision": "2018-03-20",
1029 "namespace":
1030 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"
1031 }
1032 ],
1033 "import-only-module": [
1034 {
1035 "name": "ietf-inet-types",
1036 "revision": "2013-07-15",
1037 "namespace":
1038 "urn:ietf:params:xml:ns:yang:ietf-inet-types"
1039 },
1040 {
1041 "name": "ietf-yang-types",
1042 "revision": "2013-07-15",
1043 "namespace":
1044 "urn:ietf:params:xml:ns:yang:ietf-yang-types"
1045 }
1046 ]
1047 }
1048 ],
1049 "schema": [
1050 {
1051 "name": "physical-device-schema",
1052 "module-set": [ "physical-device-modules" ]
1053 }
1054 ],
1055 "datastore": [
1056 {
1057 "name": "ietf-datastores:running",
1058 "schema": "physical-device-schema"
1059 },
1060 {
1061 "name": "ietf-datastores:operational",
1062 "schema": "physical-device-schema"
1063 }
1064 ]
1065 }
1066 }
1068 A.2. Logical Network Elements
1070 Each LNE can have a specific data model that is determined at run
1071 time, so it is appropriate to mount it using the "inline" method,
1072 hence the following "schema-mounts" data:
1074 {
1075 "ietf-yang-schema-mount:schema-mounts": {
1076 "mount-point": [
1077 {
1078 "module": "ietf-logical-network-element",
1079 "label": "root",
1080 "inline": {}
1081 }
1082 ]
1083 }
1084 }
1086 An administrator of the host device has to configure an entry for
1087 each LNE instance, for example,
1088 {
1089 "ietf-interfaces:interfaces": {
1090 "interface": [
1091 {
1092 "name": "eth0",
1093 "type": "iana-if-type:ethernetCsmacd",
1094 "enabled": true,
1095 "ietf-logical-network-element:bind-lne-name": "eth0"
1096 }
1097 ]
1098 },
1099 "ietf-logical-network-element:logical-network-elements": {
1100 "logical-network-element": [
1101 {
1102 "name": "lne-1",
1103 "managed": true,
1104 "description": "LNE with NIs",
1105 "root": {
1106 ...
1107 }
1108 }
1109 ...
1110 ]
1111 }
1112 }
1114 and then also place necessary state data as the contents of the
1115 "root" instance, which should include at least
1117 o YANG library data specifying the LNE's data model, for example,
1118 assuming the server does not implement the NMDA:
1120 {
1121 "ietf-yang-library:modules-state": {
1122 "module-set-id": "9358e11874068c8be06562089e94a89e0a392019",
1123 "module": [
1124 {
1125 "name": "iana-if-type",
1126 "revision": "2014-05-08",
1127 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type",
1128 "conformance-type": "implement"
1129 },
1130 {
1131 "name": "ietf-inet-types",
1132 "revision": "2013-07-15",
1133 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
1134 "conformance-type": "import"
1135 },
1136 {
1137 "name": "ietf-interfaces",
1138 "revision": "2014-05-08",
1139 "feature": [
1140 "arbitrary-names",
1141 "pre-provisioning"
1142 ],
1143 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",
1144 "conformance-type": "implement"
1145 },
1146 {
1147 "name": "ietf-ip",
1148 "revision": "2014-06-16",
1149 "feature": [
1150 "ipv6-privacy-autoconf"
1151 ],
1152 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip",
1153 "conformance-type": "implement"
1154 },
1155 {
1156 "name": "ietf-network-instance",
1157 "revision": "2016-10-27",
1158 "feature": [
1159 "bind-network-instance-name"
1160 ],
1161 "namespace":
1162 "urn:ietf:params:xml:ns:yang:ietf-network-instance",
1163 "conformance-type": "implement"
1164 },
1165 {
1166 "name": "ietf-yang-library",
1167 "revision": "2016-06-21",
1168 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library",
1169 "conformance-type": "implement"
1170 },
1171 {
1172 "name": "ietf-yang-schema-mount",
1173 "revision": "2017-05-16",
1174 "namespace":
1175 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount",
1176 "conformance-type": "implement"
1177 },
1178 {
1179 "name": "ietf-yang-types",
1180 "revision": "2013-07-15",
1181 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
1182 "conformance-type": "import"
1183 }
1185 ]
1186 }
1187 }
1189 o state data for interfaces assigned to the LNE instance (that
1190 effectively become system-controlled interfaces for the LNE), for
1191 example:
1193 {
1194 "ietf-interfaces:interfaces": {
1195 "interface": [
1196 {
1197 "name": "eth0",
1198 "type": "iana-if-type:ethernetCsmacd",
1199 "oper-status": "up",
1200 "statistics": {
1201 "discontinuity-time": "2016-12-16T17:11:27+02:00"
1202 },
1203 "ietf-ip:ipv6": {
1204 "address": [
1205 {
1206 "ip": "fe80::42a8:f0ff:fea8:24fe",
1207 "origin": "link-layer",
1208 "prefix-length": 64
1209 }
1210 ]
1211 }
1212 }
1213 ]
1214 }
1215 }
1217 A.3. Network Instances
1219 Assuming that network instances share the same data model, it can be
1220 mounted using the "shared-schema" method as follows:
1222 {
1223 "ietf-yang-schema-mount:schema-mounts": {
1224 "namespace": [
1225 {
1226 "prefix": "if",
1227 "uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces"
1228 },
1229 {
1230 "prefix": "ni",
1231 "uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance"
1232 }
1233 ],
1234 "mount-point": [
1235 {
1236 "module": "ietf-network-instance",
1237 "label": "root",
1238 "shared-schema": {
1239 "parent-reference": [
1240 "/if:interfaces/if:interface[\
1241 ni:bind-network-instance-name = current()/../ni:name]"
1242 ]
1243 }
1244 }
1245 ]
1246 }
1247 }
1249 Note also that the "ietf-interfaces" module appears in the
1250 "parent-reference" leaf-list for the mounted NI schema. This means
1251 that references to LNE interfaces, such as "outgoing-interface" in
1252 static routes, are valid despite the fact that "ietf-interfaces"
1253 isn't part of the NI schema.
1255 A.4. Invoking an RPC Operation
1257 Assume that the mounted NI data model also implements the "ietf-isis"
1258 module [I-D.ietf-isis-yang-isis-cfg]. An RPC operation defined in
1259 this module, such as "clear-adjacency", can be invoked by a client
1260 session of a LNE's RESTCONF server as an action tied to a the mount
1261 point of a particular network instance using a request URI like this
1262 (all on one line):
1264 POST /restconf/data/ietf-network-instance:network-instances/
1265 network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1
1267 Authors' Addresses
1269 Martin Bjorklund
1270 Tail-f Systems
1272 Email: mbj@tail-f.com
1274 Ladislav Lhotka
1275 CZ.NIC
1277 Email: lhotka@nic.cz