idnits 2.17.1 draft-ietf-netmod-schema-mount-08.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 500 has weird spacing: '... prefix yan...' == Line 524 has weird spacing: '...evision uni...' == Line 525 has weird spacing: '...ce-type enu...' == Line 528 has weird spacing: '...evision uni...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 21, 2017) is 2371 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) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-42) exists of draft-ietf-isis-yang-isis-cfg-17 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-01 == Outdated reference: A later version (-10) exists of draft-ietf-rtgwg-lne-model-03 == Outdated reference: A later version (-12) exists of draft-ietf-rtgwg-ni-model-03 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 10 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 24, 2018 CZ.NIC 6 October 21, 2017 8 YANG Schema Mount 9 draft-ietf-netmod-schema-mount-08 11 Abstract 13 This document defines a mechanism to combine YANG modules into the 14 schema defined in other YANG modules. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on April 24, 2018. 33 Copyright Notice 35 Copyright (c) 2017 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 52 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . . 6 53 2.2. Namespace Prefixes . . . . . . . . . . . . . . . . . . . 6 54 3. Schema Mount . . . . . . . . . . . . . . . . . . . . . . . . 6 55 3.1. Mount Point Definition . . . . . . . . . . . . . . . . . 6 56 3.2. Specification of the Mounted Schema . . . . . . . . . . . 7 57 3.3. Multiple Levels of Schema Mount . . . . . . . . . . . . . 9 58 4. Referring to Data Nodes in the Parent Schema . . . . . . . . 9 59 5. RPC operations and Notifications . . . . . . . . . . . . . . 10 60 6. Implementation Notes . . . . . . . . . . . . . . . . . . . . 11 61 7. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 11 62 8. Schema Mount YANG Module . . . . . . . . . . . . . . . . . . 13 63 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 64 10. Security Considerations . . . . . . . . . . . . . . . . . . . 19 65 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 19 66 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 67 12.1. Normative References . . . . . . . . . . . . . . . . . . 19 68 12.2. Informative References . . . . . . . . . . . . . . . . . 20 69 Appendix A. Example: Device Model with LNEs and NIs . . . . . . 21 70 A.1. Physical Device . . . . . . . . . . . . . . . . . . . . . 21 71 A.2. Logical Network Elements . . . . . . . . . . . . . . . . 22 72 A.3. Network Instances . . . . . . . . . . . . . . . . . . . . 25 73 A.4. Invoking an RPC Operation . . . . . . . . . . . . . . . . 27 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 76 1. Introduction 78 Modularity and extensibility were among the leading design principles 79 of the YANG data modeling language. As a result, the same YANG 80 module can be combined with various sets of other modules and thus 81 form a data model that is tailored to meet the requirements of a 82 specific use case. Server implementors are only required to specify 83 all YANG modules comprising the data model (together with their 84 revisions and other optional choices) in the YANG library data 85 ([RFC7895], and Section 5.6.4 of [RFC7950]) implemented by the 86 server. Such YANG modules appear in the data model "side by side", 87 i.e., top-level data nodes of each module - if there are any - are 88 also top-level nodes of the overall data model. 90 Furthermore, YANG has two mechanisms for contributing a schema 91 hierarchy defined elsewhere to the contents of an internal node of 92 the schema tree; these mechanisms are realized through the following 93 YANG statements: 95 o The "uses" statement explicitly incorporates the contents of a 96 grouping defined in the same or another module. See Section 4.2.6 97 of [RFC7950] for more details. 99 o The "augment" statement explicitly adds contents to a target node 100 defined in the same or another module. See Section 4.2.8 of 101 [RFC7950] for more details. 103 With both mechanisms, the source or target YANG module explicitly 104 defines the exact location in the schema tree where the new nodes are 105 placed. 107 In some cases these mechanisms are not sufficient; it is often 108 necessary that an existing module (or a set of modules) is added to 109 the data model starting at a non-root location. For example, YANG 110 modules such as "ietf-interfaces" [RFC7223] are often defined so as 111 to be used in a data model of a physical device. Now suppose we want 112 to model a device that supports multiple logical devices 113 [I-D.ietf-rtgwg-lne-model], each of which has its own instantiation 114 of "ietf-interfaces", and possibly other modules, but, at the same 115 time, we want to be able to manage all these logical devices from the 116 master device. Hence, we would like to have a schema like this: 118 +--rw interfaces 119 | +--rw interface* [name] 120 | ... 121 +--rw logical-device* [name] 122 +--rw name 123 | ... 124 +--rw interfaces 125 +--rw interface* [name] 126 ... 128 With the "uses" approach, the complete schema tree of 129 "ietf-interfaces" would have to be wrapped in a grouping, and then 130 this grouping would have to be used at the top level (for the master 131 device) and then also in the "logical-device" list (for the logical 132 devices). This approach has several disadvantages: 134 o It is not scalable because every time there is a new YANG module 135 that needs to be added to the logical device model, we have to 136 update the model for logical devices with another "uses" statement 137 pulling in contents of the new module. 139 o Absolute references to nodes defined inside a grouping may break 140 if the grouping is used in different locations. 142 o Nodes defined inside a grouping belong to the namespace of the 143 module where it is used, which makes references to such nodes from 144 other modules difficult or even impossible. 146 o It would be difficult for vendors to add proprietary modules when 147 the "uses" statements are defined in a standard module. 149 With the "augment" approach, "ietf-interfaces" would have to augment 150 the "logical-device" list with all its nodes, and at the same time 151 define all its nodes at the top level. The same hierarchy of nodes 152 would thus have to be defined twice, which is clearly not scalable 153 either. 155 This document introduces a new generic mechanism, denoted as schema 156 mount, that allows for mounting one data model consisting of any 157 number of YANG modules at a specified location of another (parent) 158 schema. Unlike the "uses" and "augment" approaches discussed above, 159 the mounted modules needn't be specially prepared for mounting and, 160 consequently, existing modules such as "ietf-interfaces" can be 161 mounted without any modifications. 163 The basic idea of schema mount is to label a data node in the parent 164 schema as the mount point, and then define a complete data model to 165 be attached to the mount point so that the labeled data node 166 effectively becomes the root node of the mounted data model. 168 In principle, the mounted schema can be specified at three different 169 phases of the data model life cycle: 171 1. Design-time: the mounted schema is defined along with the mount 172 point in the parent YANG module. In this case, the mounted 173 schema has to be the same for every implementation of the parent 174 module. 176 2. Implementation-time: the mounted schema is defined by a server 177 implementor and is as stable as YANG library information, i.e., 178 it may change after an upgrade of server software but not after 179 rebooting the server. Also, a client can learn the entire schema 180 together with YANG library data. 182 3. Run-time: the mounted schema is defined by instance data that is 183 part of the mounted data model. If there are multiple instances 184 of the same mount point (e.g., in multiple entries of a list), 185 the mounted data model may be different for each instance. 187 The schema mount mechanism defined in this document provides support 188 only for the latter two cases. Design-time mounts are outside the 189 scope of this document, and could be possibly dealt with in a future 190 revision of the YANG data modeling language. 192 Schema mount applies to the data model, and specifically does not 193 assume anything about the source of instance data for the mounted 194 schemas. It may be implemented using the same instrumentation as the 195 rest of the system, or it may be implemented by querying some other 196 system. Future specifications may define mechanisms to control or 197 monitor the implementation of specific mount points. 199 This document allows mounting of complete data models only. Other 200 specifications may extend this model by defining additional 201 mechanisms such as mounting sub-hierarchies of a module. 203 2. Terminology and Notation 205 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 207 "OPTIONAL" in this document are to be interpreted as described in BCP 208 14, [RFC2119]. 210 The following terms are defined in [RFC6241] and are not redefined 211 here: 213 o client 215 o notification 217 o server 219 The following terms are defined in [RFC7950] and are not redefined 220 here: 222 o action 224 o container 226 o list 228 o operation 230 The following terms are defined in [RFC7223] and are not redefined 231 here: 233 o system-controlled interface 235 Tree diagrams used in this document follow the notation defined in 236 [I-D.ietf-netmod-yang-tree-diagrams]. 238 2.1. Glossary of New Terms 240 o inline schema: a mounted schema whose definition is provided as 241 part of the mounted data, using YANG library [RFC7895]. 243 o mount point: container or list node whose definition contains the 244 "mount-point" extension statement. The argument of the 245 "mount-point" statement defines a label for the mount point. 247 o parent schema (of a particular mounted schema): the schema that 248 contains the mount point for the mounted schema. 250 o top-level schema: a schema according to [RFC7950] in which schema 251 trees of each module (except augments) start at the root node. 253 2.2. Namespace Prefixes 255 In this document, names of data nodes, YANG extensions, actions and 256 other data model objects are often used without a prefix, as long as 257 it is clear from the context in which YANG module each name is 258 defined. Otherwise, names are prefixed using the standard prefix 259 associated with the corresponding YANG module, as shown in Table 1. 261 +---------+------------------------+-----------+ 262 | Prefix | YANG module | Reference | 263 +---------+------------------------+-----------+ 264 | yangmnt | ietf-yang-schema-mount | Section 8 | 265 | inet | ietf-inet-types | [RFC6991] | 266 | yang | ietf-yang-types | [RFC6991] | 267 | yanglib | ietf-yang-library | [RFC7895] | 268 +---------+------------------------+-----------+ 270 Table 1: Namespace Prefixes 272 3. Schema Mount 274 The schema mount mechanism defined in this document provides a new 275 extensibility mechanism for use with YANG 1.1. In contrast to the 276 existing mechanisms described in Section 1, schema mount defines the 277 relationship between the source and target YANG modules outside these 278 modules. The procedure consists of two separate steps that are 279 described in the following subsections. 281 3.1. Mount Point Definition 283 A "container" or "list" node becomes a mount point if the 284 "mount-point" extension (defined in the "ietf-yang-schema-mount" 285 module) is used in its definition. This extension can appear only as 286 a substatement of "container" and "list" statements. 288 The argument of the "mount-point" extension is a YANG identifier that 289 defines a label for the mount point. A module MAY contain multiple 290 "mount-point" statements having the same argument. 292 It is therefore up to the designer of the parent schema to decide 293 about the placement of mount points. A mount point can also be made 294 conditional by placing "if-feature" and/or "when" as substatements of 295 the "container" or "list" statement that represents the mount point. 297 The "mount-point" statement MUST NOT be used in a YANG version 1 298 module. Note, however, that modules written in any YANG version, 299 including version 1, can be mounted under a mount point. 301 Note that the "mount-point" statement does not define a new data 302 node. 304 3.2. Specification of the Mounted Schema 306 Mounted schemas for all mount points in the parent schema are 307 determined from state data in the "yangmnt:schema-mounts" container. 308 Data in this container is intended to be as stable as data in the 309 top-level YANG library [RFC7895]. In particular, it SHOULD NOT 310 change during the same management session. 312 Generally, the modules that are mounted under a mount point have no 313 relation to the modules in the parent schema; specifically, if a 314 module is mounted it may or may not be present in the parent schema 315 and, if present, its data will generally have no relationship to the 316 data of the parent. Exceptions are possible and such needs to be 317 defined in the model defining the exception, e.g., the interface 318 module in [I-D.ietf-rtgwg-lne-model]. 320 The "schema-mounts" container has the "mount-point" list as one of 321 its children. Every entry of this list refers through its key to a 322 mount point and specifies the mounted schema. 324 If a mount point is defined in the parent schema but does not have an 325 entry in the "mount-point" list, then the mounted schema is void, 326 i.e., instances of that mount point MUST NOT contain any data above 327 those that are defined in the parent schema. 329 If multiple mount points with the same name are defined in the same 330 module - either directly or because the mount point is defined in a 331 grouping and the grouping is used multiple times - then the 332 corresponding "mount-point" entry applies equally to all such mount 333 points. 335 The "config" property of mounted schema nodes is overridden and all 336 nodes in the mounted schema are read-only ("config false") if at 337 least one of the following conditions is satisfied for a mount point: 339 o the mount point is itself defined as "config false" 341 o the "config" leaf in the corresponding entry of the "mount-point" 342 list is set to "false". 344 An entry of the "mount-point" list can specify the mounted schema in 345 two different ways: 347 1. by stating that the schema is available inline, i.e., in run-time 348 instance data; or 350 2. by referring to one or more entries of the "schema" list in the 351 same instance of "schema-mounts". 353 In case 1, the mounted schema is determined at run time: every 354 instance of the mount point that exists in the parent tree MUST 355 contain a copy of YANG library data [RFC7895] that defines the 356 mounted schema exactly as for a top-level data model. A client is 357 expected to retrieve this data from the instance tree, possibly after 358 creating the mount point. Instances of the same mount point MAY use 359 different mounted schemas. 361 In case 2, the mounted schema is defined by the combination of all 362 "schema" entries referred to in the "use-schema" list. In this case, 363 the mounted schema is specified as implementation-time data that can 364 be retrieved together with YANG library data for the parent schema, 365 i.e., even before any instances of the mount point exist. However, 366 the mounted schema has to be the same for all instances of the mount 367 point. Note, that in this case a mount point may include a mounted 368 YANG library module and the data contained in the mounted module MUST 369 exactly match the data contained in the "schema" entries associated 370 with the mount point. 372 Each entry of the "schema" list contains: 374 o a list in the YANG library format specifying all YANG modules (and 375 revisions etc.) that are implemented or imported in the mounted 376 schema. Note that this includes modules that solely augment other 377 listed modules; 379 o (optionally) a new "mount-point" list that applies to mount points 380 defined within the mounted schema. 382 3.3. Multiple Levels of Schema Mount 384 YANG modules in a mounted schema MAY again contain mount points under 385 which subschemas can be mounted. Consequently, it is possible to 386 construct data models with an arbitrary number of schema levels. A 387 subschema for a mount point contained in a mounted module can be 388 specified in one of the following ways: 390 o by implementing "ietf-yang-library" and "ietf-yang-schema-mount" 391 modules in the mounted schema, and specifying the subschemas 392 exactly as it is done in the top-level schema 394 o by using the "mount-point" list inside the corresponding "schema" 395 entry. 397 The former method is applicable to both "inline" and "use-schema" 398 cases whereas the latter requires the "use-schema" case. On the 399 other hand, the latter method allows for a compact representation of 400 a multi-level schema the does not rely on the presence of any 401 instance data. 403 4. Referring to Data Nodes in the Parent Schema 405 A fundamental design principle of schema mount is that the mounted 406 data model works exactly as a top-level data model, i.e., it is 407 confined to the "mount jail". This means that all paths in the 408 mounted data model (in leafrefs, instance-identifiers, XPath 409 expressions, and target nodes of augments) are interpreted with the 410 mount point as the root node. YANG modules of the mounted schema as 411 well as corresponding instance data thus cannot refer to schema nodes 412 or instance data outside the mount jail. 414 However, this restriction is sometimes too severe. A typical example 415 is network instances (NI) [I-D.ietf-rtgwg-ni-model], where each NI 416 has its own routing engine but the list of interfaces is global and 417 shared by all NIs. If we want to model this organization with the NI 418 schema mounted using schema mount, the overall schema tree would look 419 schematically as follows: 421 +--rw interfaces 422 | +--rw interface* [name] 423 | ... 424 +--rw network-instances 425 +--rw network-instance* [name] 426 +--rw name 427 +--rw root 428 +--rw routing 429 ... 431 Here, the "root" node is the mount point for the NI schema. Routing 432 configuration inside an NI often needs to refer to interfaces (at 433 least those that are assigned to the NI), which is impossible unless 434 such a reference can point to a node in the parent schema (interface 435 name). 437 Therefore, schema mount also allows for such references. For every 438 schema mounted using the "use-schema" method, it is possible to 439 specify a leaf-list named "parent-reference" that contains zero or 440 more XPath 1.0 expressions. Each expression is evaluated with the 441 node in the parent data tree where the mount point is defined as the 442 context node. The result of this evaluation MUST be a nodeset (see 443 the description of the "parent-reference" node for a complete 444 definition of the evaluation context). For the purposes of 445 evaluating XPath expressions within the mounted data tree, the union 446 of all such nodesets is added to the accessible data tree. 448 It is worth emphasizing that 450 o The nodes specified in "parent-reference" leaf-list are available 451 in the mounted schema only for XPath evaluations. In particular, 452 they cannot be accessed there via network management protocols 453 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. 455 o The mechanism of referencing nodes in the parent schema is not 456 available for schemas mounted using the "inline" method. 458 5. RPC operations and Notifications 460 If a mounted YANG module defines an RPC operation, clients can invoke 461 this operation by representing it as an action defined for the 462 corresponding mount point, see Section 7.15 of ^RFC7950. An example 463 of this is given in Appendix A.4. 465 Similarly, if the server emits a notification defined at the top 466 level of any mounted module, it MUST be represented as if the 467 notification was connected to the mount point, see Section 7.16 of 468 [RFC7950]. 470 Note, inline actions and notifications will not work when they are 471 contained within a list node without a "key" statement (see section 472 7.15 and 7.16 of [RFC7950]). Therefore, to be useful, mount points 473 which contain modules with RPCs, actions, and notifications SHOULD 474 NOT have any ancestor node that is a list node without a "key" 475 statement. This requirement applies to the definition of modules 476 using the "mount-point" extension statement. 478 6. Implementation Notes 480 Network management of devices that use a data model with schema mount 481 can be implemented in different ways. However, the following 482 implementations options are envisioned as typical: 484 o shared management: instance data of both parent and mounted 485 schemas are accessible within the same management session. 487 o split management: one (master) management session has access to 488 instance data of both parent and mounted schemas but, in addition, 489 an extra session exists for every instance of the mount point, 490 having access only to the mounted data tree. 492 7. Data Model 494 This document defines the YANG 1.1 module [RFC7950] 495 "ietf-yang-schema-mount", which has the following structure: 497 module: ietf-yang-schema-mount 498 +--ro schema-mounts 499 +--ro namespace* [prefix] 500 | +--ro prefix yang:yang-identifier 501 | +--ro uri? inet:uri 502 +--ro mount-point* [module label] 503 | +--ro module yang:yang-identifier 504 | +--ro label yang:yang-identifier 505 | +--ro config? boolean 506 | +--ro (schema-ref) 507 | +--:(inline) 508 | | +--ro inline? empty 509 | +--:(use-schema) 510 | +--ro use-schema* [name] 511 | +--ro name 512 | | -> /schema-mounts/schema/name 513 | +--ro parent-reference* yang:xpath1.0 514 +--ro schema* [name] 515 +--ro name string 516 +--ro module* [name revision] 517 | +--ro name yang:yang-identifier 518 | +--ro revision union 519 | +--ro schema? inet:uri 520 | +--ro namespace inet:uri 521 | +--ro feature* yang:yang-identifier 522 | +--ro deviation* [name revision] 523 | | +--ro name yang:yang-identifier 524 | | +--ro revision union 525 | +--ro conformance-type enumeration 526 | +--ro submodule* [name revision] 527 | +--ro name yang:yang-identifier 528 | +--ro revision union 529 | +--ro schema? inet:uri 530 +--ro mount-point* [module label] 531 +--ro module yang:yang-identifier 532 +--ro label yang:yang-identifier 533 +--ro config? boolean 534 +--ro (schema-ref) 535 +--:(inline) 536 | +--ro inline? empty 537 +--:(use-schema) 538 +--ro use-schema* [name] 539 +--ro name 540 | -> /schema-mounts/schema/name 541 +--ro parent-reference* yang:xpath1.0 543 8. Schema Mount YANG Module 545 This module references [RFC6991] and [RFC7895]. 547 file "ietf-yang-schema-mount@2017-10-09.yang" 549 module ietf-yang-schema-mount { 550 yang-version 1.1; 551 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"; 552 prefix yangmnt; 554 import ietf-inet-types { 555 prefix inet; 556 reference 557 "RFC 6991: Common YANG Data Types"; 558 } 560 import ietf-yang-types { 561 prefix yang; 562 reference 563 "RFC 6991: Common YANG Data Types"; 564 } 566 import ietf-yang-library { 567 prefix yanglib; 568 reference 569 "RFC 7895: YANG Module Library"; 570 } 572 organization 573 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 575 contact 576 "WG Web: 577 WG List: 579 Editor: Martin Bjorklund 580 582 Editor: Ladislav Lhotka 583 "; 585 description 586 "This module defines a YANG extension statement that can be used 587 to incorporate data models defined in other YANG modules in a 588 module. It also defines operational state data that specify the 589 overall structure of the data model. 591 Copyright (c) 2017 IETF Trust and the persons identified as 592 authors of the code. All rights reserved. 594 Redistribution and use in source and binary forms, with or 595 without modification, is permitted pursuant to, and subject to 596 the license terms contained in, the Simplified BSD License set 597 forth in Section 4.c of the IETF Trust's Legal Provisions 598 Relating to IETF Documents 599 (https://trustee.ietf.org/license-info). 601 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 602 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 603 'OPTIONAL' in the module text are to be interpreted as described 604 in RFC 2119 (https://tools.ietf.org/html/rfc2119). 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 revision 2017-10-09 { 611 description 612 "Initial revision."; 613 reference 614 "RFC XXXX: YANG Schema Mount"; 615 } 617 /* 618 * Extensions 619 */ 621 extension mount-point { 622 argument label; 623 description 624 "The argument 'label' is a YANG identifier, i.e., it is of the 625 type 'yang:yang-identifier'. 627 The 'mount-point' statement MUST NOT be used in a YANG 628 version 1 module, neither explicitly nor via a 'uses' 629 statement. 631 The 'mount-point' statement MAY be present as a substatement 632 of 'container' and 'list', and MUST NOT be present elsewhere. 633 There MUST NOT be more than one 'mount-point' statement in a 634 given 'container' or 'list' statement. 636 If a mount point is defined within a grouping, its label is 637 bound to the module where the grouping is used. 639 A mount point defines a place in the node hierarchy where 640 other data models may be attached. A server that implements a 641 module with a mount point populates the 642 /schema-mounts/mount-point list with detailed information on 643 which data models are mounted at each mount point. 645 Note that the 'mount-point' statement does not define a new 646 data node."; 647 } 649 /* 650 * Groupings 651 */ 653 grouping mount-point-list { 654 description 655 "This grouping is used inside the 'schema-mounts' container and 656 inside the 'schema' list."; 657 list mount-point { 658 key "module label"; 659 description 660 "Each entry of this list specifies a schema for a particular 661 mount point. 663 Each mount point MUST be defined using the 'mount-point' 664 extension in one of the modules listed in the corresponding 665 YANG library instance with conformance type 'implement'. The 666 corresponding YANG library instance is: 668 - standard YANG library state data as defined in RFC 7895, 669 if the 'mount-point' list is a child of 'schema-mounts', 671 - the contents of the sibling 'yanglib:modules-state' 672 container, if the 'mount-point' list is a child of 673 'schema'."; 674 leaf module { 675 type yang:yang-identifier; 676 description 677 "Name of a module containing the mount point."; 678 } 679 leaf label { 680 type yang:yang-identifier; 681 description 682 "Label of the mount point defined using the 'mount-point' 683 extension."; 684 } 685 leaf config { 686 type boolean; 687 default "true"; 688 description 689 "If this leaf is set to 'false', then all data nodes in the 690 mounted schema are read-only (config false), regardless of 691 their 'config' property."; 692 } 693 choice schema-ref { 694 mandatory true; 695 description 696 "Alternatives for specifying the schema."; 697 leaf inline { 698 type empty; 699 description 700 "This leaf indicates that the server has mounted 701 'ietf-yang-library' and 'ietf-schema-mount' at the mount 702 point, and their instantiation (i.e., state data 703 containers 'yanglib:modules-state' and 'schema-mounts') 704 provides the information about the mounted schema."; 705 } 706 list use-schema { 707 key "name"; 708 min-elements 1; 709 description 710 "Each entry of this list contains a reference to a schema 711 defined in the /schema-mounts/schema list."; 712 leaf name { 713 type leafref { 714 path "/schema-mounts/schema/name"; 715 } 716 description 717 "Name of the referenced schema."; 718 } 719 leaf-list parent-reference { 720 type yang:xpath1.0; 721 description 722 "Entries of this leaf-list are XPath 1.0 expressions 723 that are evaluated in the following context: 725 - The context node is the node in the parent data tree 726 where the mount-point is defined. 728 - The accessible tree is the parent data tree 729 *without* any nodes defined in modules that are 730 mounted inside the parent schema. 732 - The context position and context size are both equal 733 to 1. 735 - The set of variable bindings is empty. 737 - The function library is the core function library 738 defined in [XPath] and the functions defined in 739 Section 10 of [RFC7950]. 741 - The set of namespace declarations is defined by the 742 'namespace' list under 'schema-mounts'. 744 Each XPath expression MUST evaluate to a nodeset 745 (possibly empty). For the purposes of evaluating XPath 746 expressions whose context nodes are defined in the 747 mounted schema, the union of all these nodesets 748 together with ancestor nodes are added to the 749 accessible data tree."; 750 } 751 } 752 } 753 } 754 } 756 /* 757 * State data nodes 758 */ 760 container schema-mounts { 761 config false; 762 description 763 "Contains information about the structure of the overall 764 mounted data model implemented in the server."; 765 list namespace { 766 key "prefix"; 767 description 768 "This list provides a mapping of namespace prefixes that are 769 used in XPath expressions of 'parent-reference' leafs to the 770 corresponding namespace URI references."; 771 leaf prefix { 772 type yang:yang-identifier; 773 description 774 "Namespace prefix."; 775 } 776 leaf uri { 777 type inet:uri; 778 description 779 "Namespace URI reference."; 780 } 781 } 782 uses mount-point-list; 783 list schema { 784 key "name"; 785 description 786 "Each entry specifies a schema that can be mounted at a mount 787 point. The schema information consists of two parts: 789 - an instance of YANG library that defines YANG modules used 790 in the schema, 792 - mount-point list with content identical to the top-level 793 mount-point list (this makes the schema structure 794 recursive)."; 795 leaf name { 796 type string; 797 description 798 "Arbitrary name of the schema entry."; 799 } 800 uses yanglib:module-list; 801 uses mount-point-list; 802 } 803 } 804 } 806 808 9. IANA Considerations 810 This document registers a URI in the IETF XML registry [RFC3688]. 811 Following the format in RFC 3688, the following registration is 812 requested to be made. 814 URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 816 Registrant Contact: The IESG. 818 XML: N/A, the requested URI is an XML namespace. 820 This document registers a YANG module in the YANG Module Names 821 registry [RFC6020]. 823 name: ietf-yang-schema-mount 824 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 825 prefix: yangmnt 826 reference: RFC XXXX 828 10. Security Considerations 830 This document defines a mechanism for combining schemas from 831 different YANG modules into a single schema, and as such doesn't 832 introduce new security issues. 834 11. Contributors 836 The idea of having some way to combine schemas from different YANG 837 modules into one has been proposed independently by several groups of 838 people: Alexander Clemm, Jan Medved, and Eric Voit 839 ([I-D.clemm-netmod-mount]); and Lou Berger and Christian Hopps: 841 o Lou Berger, LabN Consulting, L.L.C., 843 o Alexander Clemm, Huawei, 845 o Christian Hopps, Deutsche Telekom, 847 o Jan Medved, Cisco, 849 o Eric Voit, Cisco, 851 12. References 853 12.1. Normative References 855 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 856 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 857 RFC2119, March 1997, 858 . 860 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 861 DOI 10.17487/RFC3688, January 2004, 862 . 864 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 865 the Network Configuration Protocol (NETCONF)", RFC 6020, 866 DOI 10.17487/RFC6020, October 2010, 867 . 869 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 870 6991, DOI 10.17487/RFC6991, July 2013, 871 . 873 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 874 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 875 . 877 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 878 RFC 7950, DOI 10.17487/RFC7950, August 2016, 879 . 881 12.2. Informative References 883 [I-D.clemm-netmod-mount] 884 Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined 885 Information from Remote Datastores", draft-clemm-netmod- 886 mount-06 (work in progress), March 2017. 888 [I-D.ietf-isis-yang-isis-cfg] 889 Litkowski, S., Yeung, D., Lindem, A., Zhang, Z., and L. 890 Lhotka, "YANG Data Model for IS-IS protocol", draft-ietf- 891 isis-yang-isis-cfg-17 (work in progress), March 2017. 893 [I-D.ietf-netmod-yang-tree-diagrams] 894 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 895 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 896 2017. 898 [I-D.ietf-rtgwg-device-model] 899 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 900 "Network Device YANG Logical Organization", draft-ietf- 901 rtgwg-device-model-02 (work in progress), March 2017. 903 [I-D.ietf-rtgwg-lne-model] 904 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 905 Liu, "YANG Logical Network Elements", draft-ietf-rtgwg- 906 lne-model-03 (work in progress), July 2017. 908 [I-D.ietf-rtgwg-ni-model] 909 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 910 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 911 model-03 (work in progress), July 2017. 913 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 914 and A. Bierman, Ed., "Network Configuration Protocol 915 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 916 . 918 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 919 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 920 . 922 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 923 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 924 . 926 Appendix A. Example: Device Model with LNEs and NIs 928 This non-normative example demonstrates an implementation of the 929 device model as specified in Section 2 of 930 [I-D.ietf-rtgwg-device-model], using both logical network elements 931 (LNE) and network instances (NI). 933 A.1. Physical Device 935 The data model for the physical device may be described by this YANG 936 library content: 938 "ietf-yang-library:modules-state": { 939 "module-set-id": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899", 940 "module": [ 941 { 942 "name": "iana-if-type", 943 "revision": "2014-05-08", 944 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 945 "conformance-type": "implement" 946 }, 947 { 948 "name": "ietf-inet-types", 949 "revision": "2013-07-15", 950 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 951 "conformance-type": "import" 952 }, 953 { 954 "name": "ietf-interfaces", 955 "revision": "2014-05-08", 956 "feature": [ 957 "arbitrary-names", 958 "pre-provisioning" 959 ], 960 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 961 "conformance-type": "implement" 962 }, 963 { 964 "name": "ietf-ip", 965 "revision": "2014-06-16", 966 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 967 "conformance-type": "implement" 968 }, 969 { 970 "name": "ietf-logical-network-element", 971 "revision": "2016-10-21", 972 "feature": [ 973 "bind-lne-name" 975 ], 976 "namespace": 977 "urn:ietf:params:xml:ns:yang:ietf-logical-network-element", 978 "conformance-type": "implement" 979 }, 980 { 981 "name": "ietf-yang-library", 982 "revision": "2016-06-21", 983 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 984 "conformance-type": "implement" 985 }, 986 { 987 "name": "ietf-yang-schema-mount", 988 "revision": "2017-05-16", 989 "namespace": 990 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 991 "conformance-type": "implement" 992 }, 993 { 994 "name": "ietf-yang-types", 995 "revision": "2013-07-15", 996 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 997 "conformance-type": "import" 998 } 999 ] 1000 } 1002 A.2. Logical Network Elements 1004 Each LNE can have a specific data model that is determined at run 1005 time, so it is appropriate to mount it using the "inline" method, 1006 hence the following "schema-mounts" data: 1008 "ietf-yang-schema-mount:schema-mounts": { 1009 "mount-point": [ 1010 { 1011 "module": "ietf-logical-network-element", 1012 "label": "root", 1013 "inline": [null] 1014 } 1015 ] 1016 } 1018 An administrator of the host device has to configure an entry for 1019 each LNE instance, for example, 1020 { 1021 "ietf-interfaces:interfaces": { 1022 "interface": [ 1023 { 1024 "name": "eth0", 1025 "type": "iana-if-type:ethernetCsmacd", 1026 "enabled": true, 1027 "ietf-logical-network-element:bind-lne-name": "eth0" 1028 } 1029 ] 1030 }, 1031 "ietf-logical-network-element:logical-network-elements": { 1032 "logical-network-element": [ 1033 { 1034 "name": "lne-1", 1035 "managed": true, 1036 "description": "LNE with NIs", 1037 "root": { 1038 ... 1039 } 1040 }, 1041 ... 1042 ] 1043 } 1044 } 1046 and then also place necessary state data as the contents of the 1047 "root" instance, which should include at least 1049 o YANG library data specifying the LNE's data model, for example: 1051 "ietf-yang-library:modules-state": { 1052 "module-set-id": "9358e11874068c8be06562089e94a89e0a392019", 1053 "module": [ 1054 { 1055 "name": "iana-if-type", 1056 "revision": "2014-05-08", 1057 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 1058 "conformance-type": "implement" 1059 }, 1060 { 1061 "name": "ietf-inet-types", 1062 "revision": "2013-07-15", 1063 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1064 "conformance-type": "import" 1065 }, 1066 { 1067 "name": "ietf-interfaces", 1068 "revision": "2014-05-08", 1069 "feature": [ 1070 "arbitrary-names", 1071 "pre-provisioning" 1072 ], 1073 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 1074 "conformance-type": "implement" 1075 }, 1076 { 1077 "name": "ietf-ip", 1078 "revision": "2014-06-16", 1079 "feature": [ 1080 "ipv6-privacy-autoconf" 1081 ], 1082 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 1083 "conformance-type": "implement" 1084 }, 1085 { 1086 "name": "ietf-network-instance", 1087 "revision": "2016-10-27", 1088 "feature": [ 1089 "bind-network-instance-name" 1090 ], 1091 "namespace": 1092 "urn:ietf:params:xml:ns:yang:ietf-network-instance", 1093 "conformance-type": "implement" 1094 }, 1095 { 1096 "name": "ietf-yang-library", 1097 "revision": "2016-06-21", 1098 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 1099 "conformance-type": "implement" 1100 }, 1101 { 1102 "name": "ietf-yang-schema-mount", 1103 "revision": "2017-05-16", 1104 "namespace": 1105 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 1106 "conformance-type": "implement" 1107 }, 1108 { 1109 "name": "ietf-yang-types", 1110 "revision": "2013-07-15", 1111 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1112 "conformance-type": "import" 1113 } 1114 ] 1115 } 1116 o state data for interfaces assigned to the LNE instance (that 1117 effectively become system-controlled interfaces for the LNE), for 1118 example: 1120 "ietf-interfaces:interfaces-state": { 1121 "interface": [ 1122 { 1123 "name": "eth0", 1124 "type": "iana-if-type:ethernetCsmacd", 1125 "oper-status": "up", 1126 "statistics": { 1127 "discontinuity-time": "2016-12-16T17:11:27+02:00" 1128 }, 1129 "ietf-ip:ipv6": { 1130 "address": [ 1131 { 1132 "ip": "fe80::42a8:f0ff:fea8:24fe", 1133 "origin": "link-layer", 1134 "prefix-length": 64 1135 } 1136 ] 1137 } 1138 }, 1139 ... 1140 ] 1141 } 1143 A.3. Network Instances 1145 Assuming that network instances share the same data model, it can be 1146 mounted using the "use-schema" method as follows: 1148 "ietf-yang-schema-mount:schema-mounts": { 1149 "namespace": [ 1150 { 1151 "prefix": "if", 1152 "uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces" 1153 }, 1154 { 1155 "prefix": "ni", 1156 "uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance" 1157 } 1158 ], 1159 "mount-point": [ 1160 { 1161 "module": "ietf-network-instance", 1162 "label": "root", 1163 "use-schema": [ 1164 { 1165 "name": "ni-schema", 1166 "parent-reference": [ 1167 "/if:interfaces/if:interface[ 1168 ni:bind-network-instance-name = current()/../ni:name]" 1169 ] 1170 } 1171 ] 1172 } 1173 ], 1174 "schema": [ 1175 { 1176 "name": "ni-schema", 1177 "module": [ 1178 { 1179 "name": "ietf-ipv4-unicast-routing", 1180 "revision": "2016-11-04", 1181 "namespace": 1182 "urn:ietf:params:xml:ns:yang:ietf-ipv4-unicast-routing", 1183 "conformance-type": "implement" 1184 }, 1185 { 1186 "name": "ietf-ipv6-unicast-routing", 1187 "revision": "2016-11-04", 1188 "namespace": 1189 "urn:ietf:params:xml:ns:yang:ietf-ipv6-unicast-routing", 1190 "conformance-type": "implement" 1191 }, 1192 { 1193 "name": "ietf-routing", 1194 "revision": "2016-11-04", 1195 "feature": [ 1196 "multiple-ribs", 1197 "router-id" 1198 ], 1199 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing", 1200 "conformance-type": "implement" 1201 } 1202 ] 1203 } 1204 ] 1205 } 1207 Note also that the "ietf-interfaces" module appears in the 1208 "parent-reference" leaf-list for the mounted NI schema. This means 1209 that references to LNE interfaces, such as "outgoing-interface" in 1210 static routes, are valid despite the fact that "ietf-interfaces" 1211 isn't part of the NI schema. 1213 A.4. Invoking an RPC Operation 1215 Assume that the mounted NI data model also implements the "ietf-isis" 1216 module [I-D.ietf-isis-yang-isis-cfg]. An RPC operation defined in 1217 this module, such as "clear-adjacency", can be invoked by a client 1218 session of a LNE's RESTCONF server as an action tied to a the mount 1219 point of a particular network instance using a request URI like this 1220 (all on one line): 1222 POST /restconf/data/ietf-network-instance:network-instances/ 1223 network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1 1225 Authors' Addresses 1227 Martin Bjorklund 1228 Tail-f Systems 1230 Email: mbj@tail-f.com 1232 Ladislav Lhotka 1233 CZ.NIC 1235 Email: lhotka@nic.cz