idnits 2.17.1
draft-ietf-netmod-schema-mount-10.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 338 has weird spacing: '... prefix yan...'
-- The document date (April 12, 2018) is 2205 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)
== 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)
== Outdated reference: A later version (-42) exists of
draft-ietf-isis-yang-isis-cfg-19
Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--).
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: October 14, 2018 CZ.NIC
6 April 12, 2018
8 YANG Schema Mount
9 draft-ietf-netmod-schema-mount-10
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 October 14, 2018.
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. Glossary of New Terms . . . . . . . . . . . . . . . . . . 6
54 2.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 6
55 2.3. Namespace Prefixes . . . . . . . . . . . . . . . . . . . 6
56 3. Schema Mount . . . . . . . . . . . . . . . . . . . . . . . . 7
57 3.1. Mount Point Definition . . . . . . . . . . . . . . . . . 7
58 3.2. Data Model . . . . . . . . . . . . . . . . . . . . . . . 8
59 3.3. Specification of the Mounted Schema . . . . . . . . . . . 8
60 3.4. Multiple Levels of Schema Mount . . . . . . . . . . . . . 9
61 4. Referring to Data Nodes in the Parent Schema . . . . . . . . 9
62 5. RPC operations and Notifications . . . . . . . . . . . . . . 10
63 6. Network Management Datastore Architecture (NMDA)
64 Considerations . . . . . . . . . . . . . . . . . . . . . . . 11
65 7. Interaction with the Network Configuration Access Control
66 Model (NACM) . . . . . . . . . . . . . . . . . . . . . . . . 11
67 8. Implementation Notes . . . . . . . . . . . . . . . . . . . . 12
68 9. Schema Mount YANG Module . . . . . . . . . . . . . . . . . . 12
69 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
70 11. Security Considerations . . . . . . . . . . . . . . . . . . . 17
71 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18
72 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
73 13.1. Normative References . . . . . . . . . . . . . . . . . . 18
74 13.2. Informative References . . . . . . . . . . . . . . . . . 20
75 Appendix A. Example: Device Model with LNEs and NIs . . . . . . 21
76 A.1. Physical Device . . . . . . . . . . . . . . . . . . . . . 21
77 A.2. Logical Network Elements . . . . . . . . . . . . . . . . 23
78 A.3. Network Instances . . . . . . . . . . . . . . . . . . . . 26
79 A.4. Invoking an RPC Operation . . . . . . . . . . . . . . . . 27
80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
82 1. Introduction
84 Modularity and extensibility were among the leading design principles
85 of the YANG data modeling language. As a result, the same YANG
86 module can be combined with various sets of other modules and thus
87 form a data model that is tailored to meet the requirements of a
88 specific use case. Server implementors are only required to specify
89 all YANG modules comprising the data model (together with their
90 revisions and other optional choices) in the YANG library data
91 ([RFC7895], [I-D.ietf-netconf-rfc7895bis] and Section 5.6.4 of
92 [RFC7950]) implemented by the server. Such YANG modules appear in
93 the data model "side by side", i.e., top-level data nodes of each
94 module - if there are any - are also top-level nodes of the overall
95 data model.
97 YANG has two mechanisms for contributing a schema hierarchy defined
98 elsewhere to the contents of an internal node of the schema tree;
99 these mechanisms are realized through the following YANG statements:
101 o The "uses" statement explicitly incorporates the contents of a
102 grouping defined in the same or another module. See Section 4.2.6
103 of [RFC7950] for more details.
105 o The "augment" statement explicitly adds contents to a target node
106 defined in the same or another module. See Section 4.2.8 of
107 [RFC7950] for more details.
109 With both mechanisms, the source or target YANG module explicitly
110 defines the exact location in the schema tree where the new nodes are
111 placed.
113 In some cases these mechanisms are not sufficient; it is sometimes
114 necessary that an existing module (or a set of modules) is added to
115 the data model starting at locations other than the root. For
116 example, YANG modules such as "ietf-interfaces" [RFC8343] are defined
117 so as to be used in a data model of a physical device. Now suppose
118 we want to model a device that supports multiple logical devices
119 [I-D.ietf-rtgwg-lne-model], each of which has its own instantiation
120 of "ietf-interfaces", and possibly other modules, but, at the same
121 time, we want to be able to manage all these logical devices from the
122 master device. Hence, we would like to have a schema tree like this:
124 +--rw interfaces
125 | +--rw interface* [name]
126 | ...
127 +--rw logical-network-element* [name]
128 +--rw name
129 | ...
130 +--rw interfaces
131 +--rw interface* [name]
132 ...
134 With the "uses" approach, the complete schema tree of
135 "ietf-interfaces" would have to be wrapped in a grouping, and then
136 this grouping would have to be used at the top level (for the master
137 device) and then also in the "logical-network-element" list (for the
138 logical devices). This approach has several disadvantages:
140 o It is not scalable because every time there is a new YANG module
141 that needs to be added to the logical device model, we have to
142 update the model for logical devices with another "uses" statement
143 pulling in contents of the new module.
145 o Absolute references to nodes defined inside a grouping may break
146 if the grouping is used in different locations.
148 o Nodes defined inside a grouping belong to the namespace of the
149 module where it is used, which makes references to such nodes from
150 other modules difficult or even impossible.
152 o It would be difficult for vendors to add proprietary modules when
153 the "uses" statements are defined in a standard module.
155 With the "augment" approach, "ietf-interfaces" would have to augment
156 the "logical-network-element" list with all its nodes, and at the
157 same time define all its nodes at the top level. The same hierarchy
158 of nodes would thus have to be defined twice, which is clearly not
159 scalable either.
161 This document introduces a new mechanism, denoted as schema mount,
162 that allows for mounting one data model consisting of any number of
163 YANG modules at a specified location of another (parent) schema.
164 Unlike the "uses" and "augment" approaches discussed above, the
165 mounted modules needn't be specially prepared for mounting and,
166 consequently, existing modules such as "ietf-interfaces" can be
167 mounted without any modifications.
169 The basic idea of schema mount is to label a data node in the parent
170 schema as the mount point, and then define a complete data model to
171 be attached to the mount point so that the labeled data node
172 effectively becomes the root node of the mounted data model.
174 In principle, the mounted schema can be specified at three different
175 phases of the data model life cycle:
177 1. Design-time: the mounted schema is defined along with the mount
178 point in the parent YANG module. In this case, the mounted
179 schema has to be the same for every implementation of the parent
180 module.
182 2. Implementation-time: the mounted schema is defined by a server
183 implementor and is as stable as YANG library information of the
184 server.
186 3. Run-time: the mounted schema is defined by instance data that is
187 part of the mounted data model. If there are multiple instances
188 of the same mount point (e.g., in multiple entries of a list),
189 the mounted data model may be different for each instance.
191 The schema mount mechanism defined in this document provides support
192 only for the latter two cases. Design-time mounts are outside the
193 scope of this document, and could be possibly dealt with in a future
194 revision of the YANG data modeling language.
196 Schema mount applies to the data model, and specifically does not
197 assume anything about the source of instance data for the mounted
198 schemas. It may be implemented using the same instrumentation as the
199 rest of the system, or it may be implemented by querying some other
200 system. Future specifications may define mechanisms to control or
201 monitor the implementation of specific mount points.
203 This document allows mounting of complete data models only. Other
204 specifications may extend this model by defining additional
205 mechanisms such as mounting sub-hierarchies of a module.
207 The YANG modules in this document conform to the Network Management
208 Datastore Architecture (NMDA) [RFC8342].
210 2. Terminology and Notation
212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
214 "OPTIONAL" in this document are to be interpreted as described in BCP
215 14 [RFC2119] [RFC8174] when, and only when, they appear in all
216 capitals, as shown here.
218 The following terms are defined in [RFC7950] and are not redefined
219 here:
221 o action
223 o container
225 o data node
227 o list
229 o RPC operation
231 o schema node
233 o schema tree
235 The following terms are defined in [RFC8342] and are not redefined
236 here:
238 o client
240 o notification
241 o operational state
243 o server
245 The following term is defined in [RFC8343] and are not redefined
246 here:
248 o system-controlled interface
250 The following term is defined in [I-D.ietf-netconf-rfc7895bis] and
251 are not redefined here:
253 o YANG library checksum
255 2.1. Glossary of New Terms
257 o mount point: container or list node whose definition contains the
258 "mount-point" extension statement. The argument of the
259 "mount-point" statement defines a label for the mount point.
261 o schema: collection of schema trees with a common root
263 o top-level schema: schema rooted at the root node
265 o mounted schema: schema rooted at a mount point
267 o parent schema (of a mounted schema): schema containing the mount
268 point
270 2.2. Tree Diagrams
272 Tree diagrams used in this document follow the notation defined in
273 [RFC8340]
275 2.3. Namespace Prefixes
277 In this document, names of data nodes, YANG extensions, actions and
278 other data model objects are often used without a prefix, as long as
279 it is clear from the context in which YANG module each name is
280 defined. Otherwise, names are prefixed using the standard prefix
281 associated with the corresponding YANG module, as shown in Table 1.
283 +---------+------------------------+--------------------------------+
284 | Prefix | YANG module | Reference |
285 +---------+------------------------+--------------------------------+
286 | yangmnt | ietf-yang-schema-mount | Section 9 |
287 | inet | ietf-inet-types | [RFC6991] |
288 | yang | ietf-yang-types | [RFC6991] |
289 | yanglib | ietf-yang-library | [RFC7895], |
290 | | | [I-D.ietf-netconf-rfc7895bis] |
291 +---------+------------------------+--------------------------------+
293 Table 1: Namespace Prefixes
295 3. Schema Mount
297 The schema mount mechanism defined in this document provides a new
298 extensibility mechanism for use with YANG 1.1. In contrast to the
299 existing mechanisms described in Section 1, schema mount defines the
300 relationship between the source and target YANG modules outside these
301 modules. The procedure consists of two separate steps that are
302 described in the following subsections.
304 3.1. Mount Point Definition
306 A "container" or "list" node becomes a mount point if the
307 "mount-point" extension (defined in the "ietf-yang-schema-mount"
308 module) is used in its definition. This extension can appear only as
309 a substatement of "container" and "list" statements.
311 The argument of the "mount-point" extension is a YANG identifier that
312 defines a label for the mount point. A module MAY contain multiple
313 "mount-point" statements having the same argument.
315 It is therefore up to the designer of the parent schema to decide
316 about the placement of mount points. A mount point can also be made
317 conditional by placing "if-feature" and/or "when" as substatements of
318 the "container" or "list" statement that represents the mount point.
320 The "mount-point" statement MUST NOT be used in a YANG version 1
321 module [RFC6020]. The reason for this is that otherwise it is not
322 possible to invoke mounted RPC operations, and receive mounted
323 notifications. See Section 5 for details. Note, however, that
324 modules written in any YANG version, including version 1, can be
325 mounted under a mount point.
327 Note that the "mount-point" statement does not define a new data
328 node.
330 3.2. Data Model
332 This document defines the YANG 1.1 module [RFC7950]
333 "ietf-yang-schema-mount", which has the following structure:
335 module: ietf-yang-schema-mount
336 +--ro schema-mounts
337 +--ro namespace* [prefix]
338 | +--ro prefix yang:yang-identifier
339 | +--ro uri? inet:uri
340 +--ro mount-point* [module label]
341 +--ro module yang:yang-identifier
342 +--ro label yang:yang-identifier
343 +--ro config? boolean
344 +--ro (schema-ref)
345 +--:(inline)
346 | +--ro inline!
347 +--:(shared-schema)
348 +--ro shared-schema!
349 +--ro parent-reference* yang:xpath1.0
351 3.3. Specification of the Mounted Schema
353 Mounted schemas for all mount points in the parent schema are
354 determined from state data in the "/schema-mounts" container.
356 Generally, the modules that are mounted under a mount point have no
357 relation to the modules in the parent schema; specifically, if a
358 module is mounted it may or may not be present in the parent schema
359 and, if present, its data will generally have no relationship to the
360 data of the parent. Exceptions are possible and such needs to be
361 defined in the model defining the exception. For example,
362 [I-D.ietf-rtgwg-lne-model] defines a mechanism to bind interfaces to
363 mounted logical network elements.
365 The "/schema-mounts" container has the "mount-point" list as one of
366 its children. Every entry of this list refers through its key to a
367 mount point and specifies the mounted schema.
369 If a mount point is defined in the parent schema but does not have an
370 entry in the "mount-point" list, then the mounted schema is void,
371 i.e., instances of that mount point MUST NOT contain any data except
372 those that are defined in the parent schema.
374 If multiple mount points with the same name are defined in the same
375 module - either directly or because the mount point is defined in a
376 grouping and the grouping is used multiple times - then the
377 corresponding "mount-point" entry applies equally to all such mount
378 points.
380 The "config" property of mounted schema nodes is overridden and all
381 nodes in the mounted schema are read-only ("config false") if at
382 least one of the following conditions is satisfied for a mount point:
384 o the mount point is itself defined as "config false"
386 o the "config" leaf in the corresponding entry of the "mount-point"
387 list is set to "false".
389 An entry of the "mount-point" list can specify the mounted schema in
390 two different ways, "inline" or "shared-schema".
392 The mounted schema is determined at run time: every instance of the
393 mount point that exists in the operational state MUST contain a copy
394 of YANG library data that defines the mounted schema exactly as for a
395 top-level schema. A client is expected to retrieve this data from
396 the instance tree. In the "inline" case, instances of the same mount
397 point MAY use different mounted schemas, whereas in the
398 "shared-schema" case, all instances MUST use the same mounted schema.
399 This means that in the "shared-schema" case, all instances of the
400 same mount point MUST have the same YANG library checksum. In the
401 "inline" case, if two instances have the same YANG library checksum
402 it is not guaranteed that the YANG library contents are equal for
403 these instances.
405 3.4. Multiple Levels of Schema Mount
407 YANG modules in a mounted schema MAY again contain mount points under
408 which other schemas can be mounted. Consequently, it is possible to
409 construct data models with an arbitrary number of mounted schemas. A
410 schema for a mount point contained in a mounted module can be
411 specified by implementing "ietf-yang-library" and
412 "ietf-yang-schema-mount" modules in the mounted schema, and
413 specifying the schemas exactly as it is done in the top-level schema.
415 4. Referring to Data Nodes in the Parent Schema
417 A fundamental design principle of schema mount is that the mounted
418 schema works exactly as a top-level schema, i.e., it is confined to
419 the "mount jail". This means that all paths in the mounted schema
420 (in leafrefs, instance-identifiers, XPath expressions, and target
421 nodes of augments) are interpreted with the mount point as the root
422 node. YANG modules of the mounted schema as well as corresponding
423 instance data thus cannot refer to schema nodes or instance data
424 outside the mount jail.
426 However, this restriction is sometimes too severe. A typical example
427 is network instances (NI) [I-D.ietf-rtgwg-ni-model], where each NI
428 has its own routing engine but the list of interfaces is global and
429 shared by all NIs. If we want to model this organization with the NI
430 schema mounted using schema mount, the overall schema tree would look
431 schematically as follows:
433 +--rw interfaces
434 | +--rw interface* [name]
435 | ...
436 +--rw network-instances
437 +--rw network-instance* [name]
438 +--rw name
439 +--rw root
440 +--rw routing
441 ...
443 Here, the "root" node is the mount point for the NI schema. Routing
444 configuration inside an NI often needs to refer to interfaces (at
445 least those that are assigned to the NI), which is impossible unless
446 such a reference can point to a node in the parent schema (interface
447 name).
449 Therefore, schema mount also allows for such references. For every
450 mount point in the "shared-schema" case, it is possible to specify a
451 leaf-list named "parent-reference" that contains zero or more XPath
452 1.0 expressions. Each expression is evaluated with the node in the
453 parent data tree where the mount point is defined as the context
454 node. The result of this evaluation MUST be a nodeset (see the
455 description of the "parent-reference" node for a complete definition
456 of the evaluation context). For the purposes of evaluating XPath
457 expressions within the mounted data tree, the union of all such
458 nodesets is added to the accessible data tree.
460 It is worth emphasizing that the nodes specified in
461 "parent-reference" leaf-list are available in the mounted schema only
462 for XPath evaluations. In particular, they cannot be accessed there
463 via network management protocols such as NETCONF [RFC6241] or
464 RESTCONF [RFC8040].
466 5. RPC operations and Notifications
468 If a mounted YANG module defines an RPC operation, clients can invoke
469 this operation as if it were defined as an action for the
470 corresponding mount point, see Section 7.15 of [RFC7950]. An example
471 of this is given in Appendix A.4.
473 Similarly, if the server emits a notification defined at the top
474 level of any mounted module, it MUST be represented as if the
475 notification was connected to the mount point, see Section 7.16 of
476 [RFC7950].
478 Note, inline actions and notifications will not work when they are
479 contained within a list node without a "key" statement (see section
480 7.15 and 7.16 of [RFC7950]). Therefore, to be useful, mount points
481 which contain modules with RPCs, actions, and notifications SHOULD
482 NOT have any ancestor node that is a list node without a "key"
483 statement. This requirement applies to the definition of modules
484 using the "mount-point" extension statement.
486 6. Network Management Datastore Architecture (NMDA) Considerations
488 The schema mount solution presented in this document is designed to
489 work both with servers that implement the NMDA [RFC8342], and old
490 servers that don't implement the NMDA.
492 Note to RFC Editor: please update the date YYYY-MM-DD below with the
493 revision of the ietf-yang-library in the published version of draft-
494 ietf-netconf-rfc7895bis, and remove this note.
496 Specifically, a server that doesn't support the NMDA, MAY implement
497 revision 2016-06-21 of "ietf-yang-library" [RFC7895] under a mount
498 point. A server that supports the NMDA, MUST implement at least
499 revision YYYY-MM-DD of "ietf-yang-library"
500 [I-D.ietf-netconf-rfc7895bis] under the mount points.
502 7. Interaction with the Network Configuration Access Control Model
503 (NACM)
505 If NACM [RFC8341] is implemented on a server, it can be used to
506 control access to nodes defined by the mounted schema in the same way
507 as for nodes defined by the top-level schema.
509 For example, suppose the module "ietf-interfaces" is mounted in the
510 "root" container in the "logical-network-element" list defined in
511 [I-D.ietf-rtgwg-lne-model]. Then the following NACM path can be used
512 to control access to the "interfaces" container (where the character
513 '\' is used where a line break has been inserted for formatting
514 reasons):
516
519 /lne:logical-network-elements\
520 /lne:logical-network-element/lne:root/if:interfaces
521
523 8. Implementation Notes
525 Network management of devices that use a data model with schema mount
526 can be implemented in different ways. However, the following
527 implementations options are envisioned as typical:
529 o shared management: instance data of both parent and mounted
530 schemas are accessible within the same management session.
532 o split management: one (master) management session has access to
533 instance data of both parent and mounted schemas but, in addition,
534 an extra session exists for every instance of the mount point,
535 having access only to the mounted data tree.
537 9. Schema Mount YANG Module
539 This module references [RFC6991].
541 file "ietf-yang-schema-mount@2018-04-05"
543 module ietf-yang-schema-mount {
544 yang-version 1.1;
545 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount";
546 prefix yangmnt;
548 import ietf-inet-types {
549 prefix inet;
550 reference
551 "RFC 6991: Common YANG Data Types";
552 }
554 import ietf-yang-types {
555 prefix yang;
556 reference
557 "RFC 6991: Common YANG Data Types";
558 }
560 organization
561 "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
563 contact
564 "WG Web:
565 WG List:
567 Editor: Martin Bjorklund
568
570 Editor: Ladislav Lhotka
571 ";
573 // RFC Ed.: replace XXXX with actual RFC number and
574 // remove this note.
575 description
576 "This module defines a YANG extension statement that can be used
577 to incorporate data models defined in other YANG modules in a
578 module. It also defines operational state data that specify the
579 overall structure of the data model.
581 Copyright (c) 2018 IETF Trust and the persons identified as
582 authors of the code. All rights reserved.
584 Redistribution and use in source and binary forms, with or
585 without modification, is permitted pursuant to, and subject to
586 the license terms contained in, the Simplified BSD License set
587 forth in Section 4.c of the IETF Trust's Legal Provisions
588 Relating to IETF Documents
589 (https://trustee.ietf.org/license-info).
591 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
592 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and
593 'OPTIONAL' in the module text are to be interpreted as described
594 in RFC 2119 (https://tools.ietf.org/html/rfc2119).
596 This version of this YANG module is part of RFC XXXX
597 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for
598 full legal notices.";
600 // RFC Ed.: update the date below with the date of RFC publication
601 // and remove this note.
602 revision 2018-04-05 {
603 description
604 "Initial revision.";
605 reference
606 "RFC XXXX: YANG Schema Mount";
607 }
609 /*
610 * Extensions
611 */
613 extension mount-point {
614 argument label;
615 description
616 "The argument 'label' is a YANG identifier, i.e., it is of the
617 type 'yang:yang-identifier'.
619 The 'mount-point' statement MUST NOT be used in a YANG
620 version 1 module, neither explicitly nor via a 'uses'
621 statement.
623 The 'mount-point' statement MAY be present as a substatement
624 of 'container' and 'list', and MUST NOT be present elsewhere.
625 There MUST NOT be more than one 'mount-point' statement in a
626 given 'container' or 'list' statement.
628 If a mount point is defined within a grouping, its label is
629 bound to the module where the grouping is used.
631 A mount point defines a place in the node hierarchy where
632 other data models may be attached. A server that implements a
633 module with a mount point populates the
634 /schema-mounts/mount-point list with detailed information on
635 which data models are mounted at each mount point.
637 Note that the 'mount-point' statement does not define a new
638 data node.";
639 }
641 /*
642 * State data nodes
643 */
645 container schema-mounts {
646 config false;
647 description
648 "Contains information about the structure of the overall
649 mounted data model implemented in the server.";
650 list namespace {
651 key "prefix";
652 description
653 "This list provides a mapping of namespace prefixes that are
654 used in XPath expressions of 'parent-reference' leafs to the
655 corresponding namespace URI references.";
656 leaf prefix {
657 type yang:yang-identifier;
658 description
659 "Namespace prefix.";
660 }
661 leaf uri {
662 type inet:uri;
663 description
664 "Namespace URI reference.";
665 }
666 }
667 list mount-point {
668 key "module label";
669 description
670 "Each entry of this list specifies a schema for a particular
671 mount point.
673 Each mount point MUST be defined using the 'mount-point'
674 extension in one of the modules listed in the server's
675 YANG library instance with conformance type 'implement'.";
676 leaf module {
677 type yang:yang-identifier;
678 description
679 "Name of a module containing the mount point.";
680 }
681 leaf label {
682 type yang:yang-identifier;
683 description
684 "Label of the mount point defined using the 'mount-point'
685 extension.";
686 }
687 leaf config {
688 type boolean;
689 default "true";
690 description
691 "If this leaf is set to 'false', then all data nodes in the
692 mounted schema are read-only (config false), regardless of
693 their 'config' property.";
694 }
695 choice schema-ref {
696 mandatory true;
697 description
698 "Alternatives for specifying the schema.";
699 container inline {
700 presence
701 "A complete self-contained schema is mounted at the
702 mount point.";
703 description
704 "This node indicates that the server has mounted
705 'ietf-yang-library' at the mount point, and its
706 instantiation provides the information about the mounted
707 schema.
709 Different instances of the mount point may have
710 different schemas mounted.";
711 }
712 container shared-schema {
713 presence
714 "The mounted schema together with the 'parent-reference'
715 make up the schema for this mount point.";
716 description
717 "This node indicates that the server has mounted
718 'ietf-yang-library' at the mount point, and its
719 instantiation provides the information about the mounted
720 schema. When XPath expressions in the mounted schema
721 are evaluated, the 'parent-reference' leaf-list is taken
722 into account.
724 Different instances of the mount point MUST have the
725 same schema mounted.";
726 leaf-list parent-reference {
727 type yang:xpath1.0;
728 description
729 "Entries of this leaf-list are XPath 1.0 expressions
730 that are evaluated in the following context:
732 - The context node is the node in the parent data tree
733 where the mount-point is defined.
735 - The accessible tree is the parent data tree
736 *without* any nodes defined in modules that are
737 mounted inside the parent schema.
739 - The context position and context size are both equal
740 to 1.
742 - The set of variable bindings is empty.
744 - The function library is the core function library
745 defined in [XPath] and the functions defined in
746 Section 10 of [RFC7950].
748 - The set of namespace declarations is defined by the
749 'namespace' list under 'schema-mounts'.
751 Each XPath expression MUST evaluate to a nodeset
752 (possibly empty). For the purposes of evaluating XPath
753 expressions whose context nodes are defined in the
754 mounted schema, the union of all these nodesets
755 together with ancestor nodes are added to the
756 accessible data tree.
758 Note that in the case 'ietf-yang-schema-mount' is
759 itself mounted, a 'parent-reference' in the mounted
760 module may refer to nodes that were brought into the
761 accessible tree through a 'parent-reference' in the
762 parent schema.";
763 }
764 }
765 }
766 }
767 }
768 }
770
772 10. IANA Considerations
774 This document registers a URI in the IETF XML registry [RFC3688].
775 Following the format in RFC 3688, the following registration is
776 requested to be made.
778 URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
780 Registrant Contact: The IESG.
782 XML: N/A, the requested URI is an XML namespace.
784 This document registers a YANG module in the YANG Module Names
785 registry [RFC6020].
787 name: ietf-yang-schema-mount
788 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
789 prefix: yangmnt
790 reference: RFC XXXX
792 11. Security Considerations
794 YANG module "ietf-yang-schema-mount" specified in this document
795 defines a schema for data that is designed to be accessed via network
796 management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040].
797 The lowest NETCONF layer is the secure transport layer, and the
798 mandatory-to-implement secure transport is Secure Shell (SSH)
799 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-
800 implement secure transport is TLS [RFC5246].
802 The network configuration access control model [RFC8341] provides the
803 means to restrict access for particular NETCONF or RESTCONF users to
804 a preconfigured subset of all available NETCONF or RESTCONF protocol
805 operations and content.
807 Some of the readable data nodes in this YANG module may be considered
808 sensitive or vulnerable in some network environments. It is thus
809 important to control read access (e.g., via get, get-config, or
810 notification) to these data nodes. These are the subtrees and data
811 nodes and their sensitivity/vulnerability:
813 o /schema-mounts: The schema defined by this state data provides
814 detailed information about a server implementation may help an
815 attacker identify the server capabilities and server
816 implementations with known bugs. Server vulnerabilities may be
817 specific to particular modules included in the schema, module
818 revisions, module features, or even module deviations. For
819 example, if a particular operation on a particular data node is
820 known to cause a server to crash or significantly degrade device
821 performance, then the schema information will help an attacker
822 identify server implementations with such a defect, in order to
823 launch a denial-of-service attack on the device.
825 12. Contributors
827 The idea of having some way to combine schemas from different YANG
828 modules into one has been proposed independently by several groups of
829 people: Alexander Clemm, Jan Medved, and Eric Voit
830 ([I-D.clemm-netmod-mount]); and Lou Berger and Christian Hopps:
832 o Lou Berger, LabN Consulting, L.L.C.,
834 o Alexander Clemm, Huawei,
836 o Christian Hopps, Deutsche Telekom,
838 o Jan Medved, Cisco,
840 o Eric Voit, Cisco,
842 13. References
844 13.1. Normative References
846 [I-D.ietf-netconf-rfc7895bis]
847 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
848 and R. Wilton, "YANG Library", draft-ietf-netconf-
849 rfc7895bis-06 (work in progress), April 2018.
851 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
852 Requirement Levels", BCP 14, RFC 2119,
853 DOI 10.17487/RFC2119, March 1997, .
856 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
857 DOI 10.17487/RFC3688, January 2004, .
860 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
861 (TLS) Protocol Version 1.2", RFC 5246,
862 DOI 10.17487/RFC5246, August 2008, .
865 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
866 the Network Configuration Protocol (NETCONF)", RFC 6020,
867 DOI 10.17487/RFC6020, October 2010, .
870 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
871 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
872 .
874 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
875 RFC 6991, DOI 10.17487/RFC6991, July 2013,
876 .
878 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
879 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
880 .
882 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
883 RFC 7950, DOI 10.17487/RFC7950, August 2016,
884 .
886 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
887 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
888 May 2017, .
890 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
891 Access Control Model", STD 91, RFC 8341,
892 DOI 10.17487/RFC8341, March 2018, .
895 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
896 and R. Wilton, "Network Management Datastore Architecture
897 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
898 .
900 13.2. Informative References
902 [I-D.clemm-netmod-mount]
903 Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined
904 Information from Remote Datastores", draft-clemm-netmod-
905 mount-06 (work in progress), March 2017.
907 [I-D.ietf-isis-yang-isis-cfg]
908 Litkowski, S., Yeung, D., Lindem, A., Zhang, Z., and L.
909 Lhotka, "YANG Data Model for IS-IS protocol", draft-ietf-
910 isis-yang-isis-cfg-19 (work in progress), November 2017.
912 [I-D.ietf-rtgwg-device-model]
913 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps,
914 "Network Device YANG Logical Organization", draft-ietf-
915 rtgwg-device-model-02 (work in progress), March 2017.
917 [I-D.ietf-rtgwg-lne-model]
918 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
919 Liu, "YANG Model for Logical Network Elements", draft-
920 ietf-rtgwg-lne-model-10 (work in progress), March 2018.
922 [I-D.ietf-rtgwg-ni-model]
923 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
924 Liu, "YANG Model for Network Instances", draft-ietf-rtgwg-
925 ni-model-12 (work in progress), March 2018.
927 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
928 and A. Bierman, Ed., "Network Configuration Protocol
929 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
930 .
932 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
933 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
934 .
936 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
937 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
938 .
940 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
941 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
942 .
944 Appendix A. Example: Device Model with LNEs and NIs
946 This non-normative example demonstrates an implementation of the
947 device model as specified in Section 2 of
948 [I-D.ietf-rtgwg-device-model], using both logical network elements
949 (LNE) and network instances (NI).
951 In these examples, the character '\' is used where a line break has
952 been inserted for formatting reasons.
954 A.1. Physical Device
956 The data model for the physical device may be described by this YANG
957 library content, assuming the server supports the NMDA:
959 {
960 "ietf-yang-library:yang-library": {
961 "checksum": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899",
962 "module-set": [
963 {
964 "name": "physical-device-modules",
965 "module": [
966 {
967 "name": "ietf-datastores",
968 "revision": "2018-02-14",
969 "namespace":
970 "urn:ietf:params:xml:ns:yang:ietf-datastores"
971 },
972 {
973 "name": "iana-if-type",
974 "revision": "2015-06-12",
975 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type"
976 },
977 {
978 "name": "ietf-interfaces",
979 "revision": "2018-02-20",
980 "feature": ["arbitrary-names", "pre-provisioning" ],
981 "namespace":
982 "urn:ietf:params:xml:ns:yang:ietf-interfaces"
983 },
984 {
985 "name": "ietf-ip",
986 "revision": "2018-02-22",
987 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip"
988 },
989 {
990 "name": "ietf-logical-network-element",
991 "revision": "2016-10-21",
992 "feature": [ "bind-lne-name" ],
993 "namespace":
994 "urn:ietf:params:xml:ns:yang:\
995 ietf-logical-network-element"
996 },
997 {
998 "name": "ietf-yang-library",
999 "revision": "2018-02-21",
1000 "namespace":
1001 "urn:ietf:params:xml:ns:yang:ietf-yang-library"
1002 },
1003 {
1004 "name": "ietf-yang-schema-mount",
1005 "revision": "2018-03-20",
1006 "namespace":
1007 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"
1008 }
1009 ],
1010 "import-only-module": [
1011 {
1012 "name": "ietf-inet-types",
1013 "revision": "2013-07-15",
1014 "namespace":
1015 "urn:ietf:params:xml:ns:yang:ietf-inet-types"
1016 },
1017 {
1018 "name": "ietf-yang-types",
1019 "revision": "2013-07-15",
1020 "namespace":
1021 "urn:ietf:params:xml:ns:yang:ietf-yang-types"
1022 }
1023 ]
1024 }
1025 ],
1026 "schema": [
1027 {
1028 "name": "physical-device-schema",
1029 "module-set": [ "physical-device-modules" ]
1030 }
1031 ],
1032 "datastore": [
1033 {
1034 "name": "ietf-datastores:running",
1035 "schema": "physical-device-schema"
1036 },
1037 {
1038 "name": "ietf-datastores:operational",
1039 "schema": "physical-device-schema"
1041 }
1042 ]
1043 }
1044 }
1046 A.2. Logical Network Elements
1048 Each LNE can have a specific data model that is determined at run
1049 time, so it is appropriate to mount it using the "inline" method,
1050 hence the following "schema-mounts" data:
1052 {
1053 "ietf-yang-schema-mount:schema-mounts": {
1054 "mount-point": [
1055 {
1056 "module": "ietf-logical-network-element",
1057 "label": "root",
1058 "inline": {}
1059 }
1060 ]
1061 }
1062 }
1064 An administrator of the host device has to configure an entry for
1065 each LNE instance, for example,
1066 {
1067 "ietf-interfaces:interfaces": {
1068 "interface": [
1069 {
1070 "name": "eth0",
1071 "type": "iana-if-type:ethernetCsmacd",
1072 "enabled": true,
1073 "ietf-logical-network-element:bind-lne-name": "eth0"
1074 }
1075 ]
1076 },
1077 "ietf-logical-network-element:logical-network-elements": {
1078 "logical-network-element": [
1079 {
1080 "name": "lne-1",
1081 "managed": true,
1082 "description": "LNE with NIs",
1083 "root": {
1084 ...
1085 }
1086 }
1087 ...
1088 ]
1089 }
1090 }
1092 and then also place necessary state data as the contents of the
1093 "root" instance, which should include at least
1095 o YANG library data specifying the LNE's data model, for example,
1096 assuming the server does not implement the NMDA:
1098 {
1099 "ietf-yang-library:modules-state": {
1100 "module-set-id": "9358e11874068c8be06562089e94a89e0a392019",
1101 "module": [
1102 {
1103 "name": "iana-if-type",
1104 "revision": "2014-05-08",
1105 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type",
1106 "conformance-type": "implement"
1107 },
1108 {
1109 "name": "ietf-inet-types",
1110 "revision": "2013-07-15",
1111 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
1112 "conformance-type": "import"
1113 },
1114 {
1115 "name": "ietf-interfaces",
1116 "revision": "2014-05-08",
1117 "feature": [
1118 "arbitrary-names",
1119 "pre-provisioning"
1120 ],
1121 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",
1122 "conformance-type": "implement"
1123 },
1124 {
1125 "name": "ietf-ip",
1126 "revision": "2014-06-16",
1127 "feature": [
1128 "ipv6-privacy-autoconf"
1129 ],
1130 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip",
1131 "conformance-type": "implement"
1132 },
1133 {
1134 "name": "ietf-network-instance",
1135 "revision": "2016-10-27",
1136 "feature": [
1137 "bind-network-instance-name"
1138 ],
1139 "namespace":
1140 "urn:ietf:params:xml:ns:yang:ietf-network-instance",
1141 "conformance-type": "implement"
1142 },
1143 {
1144 "name": "ietf-yang-library",
1145 "revision": "2016-06-21",
1146 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library",
1147 "conformance-type": "implement"
1148 },
1149 {
1150 "name": "ietf-yang-schema-mount",
1151 "revision": "2017-05-16",
1152 "namespace":
1153 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount",
1154 "conformance-type": "implement"
1155 },
1156 {
1157 "name": "ietf-yang-types",
1158 "revision": "2013-07-15",
1159 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
1160 "conformance-type": "import"
1161 }
1163 ]
1164 }
1165 }
1167 o state data for interfaces assigned to the LNE instance (that
1168 effectively become system-controlled interfaces for the LNE), for
1169 example:
1171 {
1172 "ietf-interfaces:interfaces": {
1173 "interface": [
1174 {
1175 "name": "eth0",
1176 "type": "iana-if-type:ethernetCsmacd",
1177 "oper-status": "up",
1178 "statistics": {
1179 "discontinuity-time": "2016-12-16T17:11:27+02:00"
1180 },
1181 "ietf-ip:ipv6": {
1182 "address": [
1183 {
1184 "ip": "fe80::42a8:f0ff:fea8:24fe",
1185 "origin": "link-layer",
1186 "prefix-length": 64
1187 }
1188 ]
1189 }
1190 }
1191 ]
1192 }
1193 }
1195 A.3. Network Instances
1197 Assuming that network instances share the same data model, it can be
1198 mounted using the "shared-schema" method as follows:
1200 {
1201 "ietf-yang-schema-mount:schema-mounts": {
1202 "namespace": [
1203 {
1204 "prefix": "if",
1205 "uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces"
1206 },
1207 {
1208 "prefix": "ni",
1209 "uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance"
1210 }
1211 ],
1212 "mount-point": [
1213 {
1214 "module": "ietf-network-instance",
1215 "label": "root",
1216 "shared-schema": {
1217 "parent-reference": [
1218 "/if:interfaces/if:interface[\
1219 ni:bind-network-instance-name = current()/../ni:name]"
1220 ]
1221 }
1222 }
1223 ]
1224 }
1225 }
1227 Note also that the "ietf-interfaces" module appears in the
1228 "parent-reference" leaf-list for the mounted NI schema. This means
1229 that references to LNE interfaces, such as "outgoing-interface" in
1230 static routes, are valid despite the fact that "ietf-interfaces"
1231 isn't part of the NI schema.
1233 A.4. Invoking an RPC Operation
1235 Assume that the mounted NI data model also implements the "ietf-isis"
1236 module [I-D.ietf-isis-yang-isis-cfg]. An RPC operation defined in
1237 this module, such as "clear-adjacency", can be invoked by a client
1238 session of a LNE's RESTCONF server as an action tied to a the mount
1239 point of a particular network instance using a request URI like this
1240 (all on one line):
1242 POST /restconf/data/ietf-network-instance:network-instances/
1243 network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1
1245 Authors' Addresses
1247 Martin Bjorklund
1248 Tail-f Systems
1250 Email: mbj@tail-f.com
1252 Ladislav Lhotka
1253 CZ.NIC
1255 Email: lhotka@nic.cz