idnits 2.17.1 draft-ietf-netmod-schema-mount-05.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 (May 16, 2017) is 2530 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 (-10) exists of draft-ietf-rtgwg-lne-model-02 == Outdated reference: A later version (-12) exists of draft-ietf-rtgwg-ni-model-02 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 1 error (**), 0 flaws (~~), 9 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: November 17, 2017 CZ.NIC 6 May 16, 2017 8 YANG Schema Mount 9 draft-ietf-netmod-schema-mount-05 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 November 17, 2017. 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. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 6 54 2.3. Namespace Prefixes . . . . . . . . . . . . . . . . . . . 6 55 3. Schema Mount . . . . . . . . . . . . . . . . . . . . . . . . 7 56 3.1. Mount Point Definition . . . . . . . . . . . . . . . . . 7 57 3.2. Specification of the Mounted Schema . . . . . . . . . . . 7 58 3.3. Multiple Levels of Schema Mount . . . . . . . . . . . . . 9 59 4. Referring to Data Nodes in the Parent Schema . . . . . . . . 9 60 5. RPC operations and Notifications . . . . . . . . . . . . . . 10 61 6. Implementation Notes . . . . . . . . . . . . . . . . . . . . 11 62 7. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 8. Schema Mount YANG Module . . . . . . . . . . . . . . . . . . 13 64 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 65 10. Security Considerations . . . . . . . . . . . . . . . . . . . 18 66 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 67 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 68 12.1. Normative References . . . . . . . . . . . . . . . . . . 19 69 12.2. Informative References . . . . . . . . . . . . . . . . . 19 70 Appendix A. Example: Device Model with LNEs and NIs . . . . . . 20 71 A.1. Physical Device . . . . . . . . . . . . . . . . . . . . . 20 72 A.2. Logical Network Elements . . . . . . . . . . . . . . . . 22 73 A.3. Network Instances . . . . . . . . . . . . . . . . . . . . 25 74 A.4. Invoking an RPC Operation . . . . . . . . . . . . . . . . 27 75 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 27 76 B.1. RPC Operations and Notifications in Mounted Modules . . . 27 77 B.2. Tree Representation . . . . . . . . . . . . . . . . . . . 27 78 B.3. Design-Time Mounts . . . . . . . . . . . . . . . . . . . 28 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], and Section 5.6.4 of [RFC7950]) implemented by the 91 server. Such YANG modules appear in the data model "side by side", 92 i.e., top-level data nodes of each module - if there are any - are 93 also top-level nodes of the overall data model. 95 Furthermore, YANG has two mechanisms for contributing a schema 96 hierarchy defined elsewhere to the contents of an internal node of 97 the schema tree; these mechanisms are realized through the following 98 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 source or target YANG module explicitly 109 defines the exact location in the schema tree where the new nodes are 110 placed. 112 In some cases these mechanisms are not sufficient; it is often 113 necessary that an existing module (or a set of modules) is added to 114 the data model starting at a non-root location. For example, YANG 115 modules such as "ietf-interfaces" [RFC7223] are often defined so as 116 to be used in a data model of a physical device. Now suppose we want 117 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 like this: 123 +--rw interfaces 124 | +--rw interface* [name] 125 | ... 126 +--rw logical-device* [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-device" list (for the logical 137 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-device" list with all its nodes, and at the same time 156 define all its nodes at the top level. The same hierarchy of nodes 157 would thus have to be defined twice, which is clearly not scalable 158 either. 160 This document introduces a new generic mechanism, denoted as schema 161 mount, that allows for mounting one data model consisting of any 162 number of YANG modules at a specified location of another (parent) 163 schema. Unlike the "uses" and "augment" approaches discussed above, 164 the 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 module. In this case, the mounted schema has 178 to be the same for every implementation of the parent module. 180 2. Implementation-time: the mounted schema is defined by a server 181 implementor and is as stable as YANG library information, i.e., 182 it may change after an upgrade of server software but not after 183 rebooting the server. Also, a client can learn the entire schema 184 together with YANG library data. 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 because design-time definition of the 193 mounted schema doesn't play well with the existing YANG modularity 194 mechanisms. For example, it would be impossible to augment the 195 mounted data model. 197 Schema mount applies to the data model, and specifically does not 198 assume anything about the source of instance data for the mounted 199 schemas. It may be implemented using the same instrumentation as the 200 rest of the system, or it may be implemented by querying some other 201 system. Future specifications may define mechanisms to control or 202 monitor the implementation of specific mount points. 204 This document allows mounting of complete data models only. Other 205 specifications may extend this model by defining additional 206 mechanisms such as mounting sub-hierarchies of a module. 208 2. Terminology and Notation 210 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 211 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 212 "OPTIONAL" in this document are to be interpreted as described in BCP 213 14, [RFC2119]. 215 The following terms are defined in [RFC6241] and are not redefined 216 here: 218 o client 220 o notification 222 o server 224 The following terms are defined in [RFC7950] and are not redefined 225 here: 227 o action 229 o configuration data 231 o container 233 o list 235 o operation 237 The following terms are defined in [RFC7223] and are not redefined 238 here: 240 o system-controlled interface 242 2.1. Glossary of New Terms 244 o inline schema: a mounted schema whose definition is provided as 245 part of the mounted data, using YANG library [RFC7895]. 247 o mount point: container or list node whose definition contains the 248 "mount-point" extension statement. The argument of the 249 "mount-point" statement defines the name of the mount point. 251 o parent schema (of a particular mounted schema): the schema that 252 contains the mount point for the mounted schema. 254 o top-level schema: a schema according to [RFC7950] in which schema 255 trees of each module (except augments) start at the root node. 257 2.2. Tree Diagrams 259 A simplified graphical representation of the data model is used in 260 this document. The meaning of the symbols in these diagrams is as 261 follows: 263 o Brackets "[" and "]" enclose list keys. 265 o Abbreviations before data node names: "rw" means configuration 266 data (read-write) and "ro" state data (read-only). 268 o Symbols after data node names: "?" means an optional node, "!" 269 means a presence container, and "*" denotes a list and leaf-list. 271 o Parentheses enclose choice and case nodes, and case nodes are also 272 marked with a colon (":"). 274 o Ellipsis ("...") stands for contents of subtrees that are not 275 shown. 277 2.3. Namespace Prefixes 279 In this document, names of data nodes, YANG extensions, actions and 280 other data model objects are often used without a prefix, as long as 281 it is clear from the context in which YANG module each name is 282 defined. Otherwise, names are prefixed using the standard prefix 283 associated with the corresponding YANG module, as shown in Table 1. 285 +---------+------------------------+-----------+ 286 | Prefix | YANG module | Reference | 287 +---------+------------------------+-----------+ 288 | yangmnt | ietf-yang-schema-mount | Section 8 | 289 | inet | ietf-inet-types | [RFC6991] | 290 | yang | ietf-yang-types | [RFC6991] | 291 | yanglib | ietf-yang-library | [RFC7895] | 292 +---------+------------------------+-----------+ 294 Table 1: Namespace Prefixes 296 3. Schema Mount 298 The schema mount mechanism defined in this document provides a new 299 extensibility mechanism for use with YANG 1.1. In contrast to the 300 existing mechanisms described in Section 1, schema mount defines the 301 relationship between the source and target YANG modules outside these 302 modules. The procedure consists of two separate steps that are 303 described in the following subsections. 305 3.1. Mount Point Definition 307 A "container" or "list" node becomes a mount point if the 308 "mount-point" extension (defined in the "ietf-yang-schema-mount" 309 module) is used in its definition. This extension can appear only as 310 a substatement of "container" and "list" statements. 312 The argument of the "mount-point" extension is a YANG identifier that 313 defines the name of the mount point. A module MAY contain multiple 314 "mount-point" statements having the same argument. 316 It is therefore up to the designer of the parent schema to decide 317 about the placement of mount points. A mount point can also be made 318 conditional by placing "if-feature" and/or "when" as substatements of 319 the "container" or "list" statement that represents the mount point. 321 The "mount-point" statement MUST NOT be used in a YANG version 1 322 module. Note, however, that modules written in any YANG version, 323 including version 1, can be mounted under a mount point. 325 3.2. Specification of the Mounted Schema 327 Mounted schemas for all mount points in the parent schema are 328 determined from state data in the "yangmnt:schema-mounts" container. 329 Data in this container is intended to be as stable as data in the 330 top-level YANG library [RFC7895]. In particular, it SHOULD NOT 331 change during the same management session. 333 The "schema-mounts" container has the "mount-point" list as one of 334 its children. Every entry of this list refers through its key to a 335 mount point and specifies the mounted schema. 337 If a mount point is defined in the parent schema but does not have an 338 entry in the "mount-point" list, then the mounted schema is void, 339 i.e., instances of that mount point MUST NOT contain any data above 340 those that are defined in the parent schema. 342 If multiple mount points with the same name are defined in the same 343 module - either directly or because the mount point is defined in a 344 grouping and the grouping is used multiple times - then the 345 corresponding "mount-point" entry applies equally to all such mount 346 points. 348 The "config" property of mounted schema nodes is overridden and all 349 nodes in the mounted schema are read-only ("config false") if at 350 least one of the following conditions is satisfied for a mount point: 352 o the mount point is itself defined as "config false" 354 o the "config" leaf in the corresponding entry of the "mount-point" 355 list is set to "false". 357 An entry of the "mount-point" list can specify the mounted schema in 358 two different ways: 360 1. by stating that the schema is available inline, i.e., in run-time 361 instance data; or 363 2. by referring to one or more entries of the "schema" list in the 364 same instance of "schema-mounts". 366 In case 1, the mounted schema is determined at run time: every 367 instance of the mount point that exists in the parent tree MUST 368 contain a copy of YANG library data [RFC7895] that defines the 369 mounted schema exactly as for a top-level data model. A client is 370 expected to retrieve this data from the instance tree, possibly after 371 creating the mount point. Instances of the same mount point MAY use 372 different mounted schemas. 374 In case 2, the mounted schema is defined by the combination of all 375 "schema" entries referred to in the "use-schema" list. In this case, 376 the mounted schema is specified as implementation-time data that can 377 be retrieved together with YANG library data for the parent schema, 378 i.e., even before any instances of the mount point exist. However, 379 the mounted schema has to be the same for all instances of the mount 380 point. 382 Each entry of the "schema" list contains 384 o a list in the YANG library format specifying all YANG modules (and 385 revisions etc.) that are implemented or imported in the mounted 386 schema; 388 o (optionally) a new "mount-point" list that applies to mount points 389 defined within the mounted schema. 391 3.3. Multiple Levels of Schema Mount 393 YANG modules in a mounted schema MAY again contain mount points under 394 which subschemas can be mounted. Consequently, it is possible to 395 construct data models with an arbitrary number of schema levels. A 396 subschema for a mount point contained in a mounted module can be 397 specified in one of the following ways: 399 o by implementing "ietf-yang-library" and "ietf-yang-schema-mount" 400 modules in the mounted schema, and specifying the subschemas 401 exactly as it is done in the top-level schema 403 o by using the "mount-point" list inside the corresponding "schema" 404 entry. 406 The former method is applicable to both "inline" and "use-schema" 407 cases whereas the latter requires the "use-schema" case. On the 408 other hand, the latter method allows for a compact representation of 409 a multi-level schema the does not rely on the presence of any 410 instance data. 412 4. Referring to Data Nodes in the Parent Schema 414 A fundamental design principle of schema mount is that the mounted 415 data model works exactly as a top-level data model, i.e., it is 416 confined to the "mount jail". This means that all paths in the 417 mounted data model (in leafrefs, instance-identifiers, XPath 418 expressions, and target nodes of augments) are interpreted with the 419 mount point as the root node. YANG modules of the mounted schema as 420 well as corresponding instance data thus cannot refer to schema nodes 421 or instance data outside the mount jail. 423 However, this restriction is sometimes too severe. A typical example 424 is network instances (NI) [I-D.ietf-rtgwg-ni-model], where each NI 425 has its own routing engine but the list of interfaces is global and 426 shared by all NIs. If we want to model this organization with the NI 427 schema mounted using schema mount, the overall schema tree would look 428 schematically as follows: 430 +--rw interfaces 431 | +--rw interface* [name] 432 | ... 433 +--rw network-instances 434 +--rw network-instance* [name] 435 +--rw name 436 +--rw root 437 +--rw routing 438 ... 440 Here, the "root" node is the mount point for the NI schema. Routing 441 configuration inside an NI often needs to refer to interfaces (at 442 least those that are assigned to the NI), which is impossible unless 443 such a reference can point to a node in the parent schema (interface 444 name). 446 Therefore, schema mount also allows for such references. For every 447 schema mounted using the "use-schema" method, it is possible to 448 specify a leaf-list named "parent-reference" that contains zero or 449 more XPath 1.0 expressions. Each expression is evaluated with the 450 root of the parent data tree as the context node and the result MUST 451 be a nodeset (see the description of the "parent-reference" node for 452 a complete definition of the evaluation context). For the purposes 453 of evaluating XPath expressions within the mounted data tree, the 454 union of all such nodesets is added to the accessible data tree. 456 It is worth emphasizing that 458 o The nodes specified in "parent-reference" leaf-list are available 459 in the mounted schema only for XPath evaluations. In particular, 460 they cannot be accessed there via network management protocols 461 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. 463 o The mechanism of referencing nodes in the parent schema is not 464 available for schemas mounted using the "inline" method. 466 5. RPC operations and Notifications 468 If a mounted YANG module defines an RPC operation, clients can invoke 469 this operation by representing it as an action defined 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 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 ns-uri? inet:uri 502 +--ro mount-point* [module name] 503 | +--ro module yang:yang-identifier 504 | +--ro name 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 name] 531 +--ro module yang:yang-identifier 532 +--ro name 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-05-16.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-05-16 { 611 description 612 "Initial revision."; 613 reference 614 "RFC XXXX: YANG Schema Mount"; 615 } 617 /* 618 * Extensions 619 */ 621 extension mount-point { 622 argument name; 623 description 624 "The argument 'name' 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. 634 If a mount point is defined in a grouping, its name is bound 635 to the module where the grouping is used. 637 A mount point defines a place in the node hierarchy where 638 other data models may be attached. A server that implements a 639 module with a mount point populates the 640 /schema-mounts/mount-point list with detailed information on 641 which data models are mounted at each mount point."; 642 } 644 /* 645 * Groupings 646 */ 648 grouping mount-point-list { 649 description 650 "This grouping is used inside the 'schema-mounts' container and 651 inside the 'schema' list."; 652 list mount-point { 653 key "module name"; 654 description 655 "Each entry of this list specifies a schema for a particular 656 mount point. 658 Each mount point MUST be defined using the 'mount-point' 659 extension in one of the modules listed in the corresponding 660 YANG library instance with conformance type 'implement'. The 661 corresponding YANG library instance is: 663 - standard YANG library state data as defined in RFC 7895, 664 if the 'mount-point' list is a child of 'schema-mounts', 666 - the contents of the sibling 'yanglib:modules-state' 667 container, if the 'mount-point' list is a child of 668 'schema'."; 669 leaf module { 670 type yang:yang-identifier; 671 description 672 "Name of a module containing the mount point."; 673 } 674 leaf name { 675 type yang:yang-identifier; 676 description 677 "Name of the mount point defined using the 'mount-point' 678 extension."; 679 } 680 leaf config { 681 type boolean; 682 default "true"; 683 description 684 "If this leaf is set to 'false', then all data nodes in the 685 mounted schema are read-only (config false), regardless of 686 their 'config' property."; 688 } 689 choice schema-ref { 690 description 691 "Alternatives for specifying the schema."; 692 leaf inline { 693 type empty; 694 description 695 "This leaf indicates that the server has mounted 696 'ietf-yang-library' and 'ietf-schema-mount' at the mount 697 point, and their instantiation (i.e., state data 698 containers 'yanglib:modules-state' and 'schema-mounts') 699 provides the information about the mounted schema."; 700 } 701 list use-schema { 702 key "name"; 703 description 704 "Each entry of this list contains a reference to a schema 705 defined in the /schema-mounts/schema list."; 706 leaf name { 707 type leafref { 708 path "/schema-mounts/schema/name"; 709 } 710 description 711 "Name of the referenced schema."; 712 } 713 leaf-list parent-reference { 714 type yang:xpath1.0; 715 description 716 "Entries of this leaf-list are XPath 1.0 expressions 717 that are evaluated in the following context: 719 - The context node is the root node of the parent data 720 tree. 722 - The accessible tree is the parent data tree 723 *without* any nodes defined in modules that are 724 mounted inside the parent schema. 726 - The context position and context size are both equal 727 to 1. 729 - The set of variable bindings is empty. 731 - The function library is the core function library 732 defined in [XPath] and the functions defined in 733 Section 10 of [RFC7950]. 735 - The set of namespace declarations is defined by the 736 'namespace' list under 'schema-mounts'. 738 Each XPath expression MUST evaluate to a nodeset 739 (possibly empty). For the purposes of evaluating XPath 740 expressions whose context nodes are defined in the 741 mounted schema, the union of all these nodesets 742 together with ancestor nodes are added to the 743 accessible data tree."; 744 } 745 } 746 } 747 } 748 } 750 /* 751 * State data nodes 752 */ 754 container schema-mounts { 755 config false; 756 description 757 "Contains information about the structure of the overall 758 mounted data model implemented in the server."; 759 list namespace { 760 key "prefix"; 761 description 762 "This list provides a mapping of namespace prefixes that are 763 used in XPath expressions of 'parent-reference' leafs to the 764 corresponding namespace URI references."; 765 leaf prefix { 766 type yang:yang-identifier; 767 description 768 "Namespace prefix."; 769 } 770 leaf ns-uri { 771 type inet:uri; 772 description 773 "Namespace URI reference."; 774 } 775 } 776 uses mount-point-list; 777 list schema { 778 key "name"; 779 description 780 "Each entry specifies a schema that can be mounted at a mount 781 point. The schema information consists of two parts: 783 - an instance of YANG library that defines YANG modules used 784 in the schema, 786 - mount-point list with content identical to the top-level 787 mount-point list (this makes the schema structure 788 recursive)."; 789 leaf name { 790 type string; 791 description 792 "Arbitrary name of the schema entry."; 793 } 794 uses yanglib:module-list; 795 uses mount-point-list; 796 } 797 } 798 } 800 802 9. IANA Considerations 804 This document registers a URI in the IETF XML registry [RFC3688]. 805 Following the format in RFC 3688, the following registration is 806 requested to be made. 808 URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 810 Registrant Contact: The IESG. 812 XML: N/A, the requested URI is an XML namespace. 814 This document registers a YANG module in the YANG Module Names 815 registry [RFC6020]. 817 name: ietf-yang-schema-mount 818 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 819 prefix: yangmnt 820 reference: RFC XXXX 822 10. Security Considerations 824 TBD 826 11. Contributors 828 The idea of having some way to combine schemas from different YANG 829 modules into one has been proposed independently by several groups of 830 people: Alexander Clemm, Jan Medved, and Eric Voit 831 ([I-D.clemm-netmod-mount]); and Lou Berger and Christian Hopps: 833 o Lou Berger, LabN Consulting, L.L.C., 835 o Alexander Clemm, Huawei, 837 o Christian Hopps, Deutsche Telekom, 839 o Jan Medved, Cisco, 841 o Eric Voit, Cisco, 843 12. References 845 12.1. Normative References 847 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 848 Requirement Levels", BCP 14, RFC 2119, 849 DOI 10.17487/RFC2119, March 1997, 850 . 852 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 853 DOI 10.17487/RFC3688, January 2004, 854 . 856 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 857 the Network Configuration Protocol (NETCONF)", RFC 6020, 858 DOI 10.17487/RFC6020, October 2010, 859 . 861 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 862 RFC 6991, DOI 10.17487/RFC6991, July 2013, 863 . 865 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 866 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 867 . 869 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 870 RFC 7950, DOI 10.17487/RFC7950, August 2016, 871 . 873 12.2. Informative References 875 [I-D.clemm-netmod-mount] 876 Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined 877 Information from Remote Datastores", draft-clemm-netmod- 878 mount-06 (work in progress), March 2017. 880 [I-D.ietf-isis-yang-isis-cfg] 881 Litkowski, S., Yeung, D., Lindem, A., Zhang, Z., and L. 882 Lhotka, "YANG Data Model for IS-IS protocol", draft-ietf- 883 isis-yang-isis-cfg-17 (work in progress), March 2017. 885 [I-D.ietf-rtgwg-device-model] 886 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 887 "Network Device YANG Logical Organization", draft-ietf- 888 rtgwg-device-model-02 (work in progress), March 2017. 890 [I-D.ietf-rtgwg-lne-model] 891 Berger, L., Hopps, C., Lindem, A., and D. Bogdanovic, 892 "YANG Logical Network Elements", draft-ietf-rtgwg-lne- 893 model-02 (work in progress), March 2017. 895 [I-D.ietf-rtgwg-ni-model] 896 Berger, L., Hopps, C., Lindem, A., and D. Bogdanovic, 897 "YANG Network Instances", draft-ietf-rtgwg-ni-model-02 898 (work in progress), March 2017. 900 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 901 and A. Bierman, Ed., "Network Configuration Protocol 902 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 903 . 905 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 906 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 907 . 909 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 910 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 911 . 913 Appendix A. Example: Device Model with LNEs and NIs 915 This non-normative example demonstrates an implementation of the 916 device model as specified in Section 2 of 917 [I-D.ietf-rtgwg-device-model], using both logical network elements 918 (LNE) and network instances (NI). 920 A.1. Physical Device 922 The data model for the physical device may be described by this YANG 923 library content: 925 "ietf-yang-library:modules-state": { 926 "module-set-id": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899", 927 "module": [ 928 { 929 "name": "iana-if-type", 930 "revision": "2014-05-08", 931 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 932 "conformance-type": "implement" 933 }, 934 { 935 "name": "ietf-inet-types", 936 "revision": "2013-07-15", 937 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 938 "conformance-type": "import" 939 }, 940 { 941 "name": "ietf-interfaces", 942 "revision": "2014-05-08", 943 "feature": [ 944 "arbitrary-names", 945 "pre-provisioning" 946 ], 947 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 948 "conformance-type": "implement" 949 }, 950 { 951 "name": "ietf-ip", 952 "revision": "2014-06-16", 953 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 954 "conformance-type": "implement" 955 }, 956 { 957 "name": "ietf-logical-network-element", 958 "revision": "2016-10-21", 959 "feature": [ 960 "bind-lne-name" 961 ], 962 "namespace": 963 "urn:ietf:params:xml:ns:yang:ietf-logical-network-element", 964 "conformance-type": "implement" 965 }, 966 { 967 "name": "ietf-yang-library", 968 "revision": "2016-06-21", 969 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 970 "conformance-type": "implement" 971 }, 972 { 973 "name": "ietf-yang-schema-mount", 974 "revision": "2017-05-16", 975 "namespace": 977 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 978 "conformance-type": "implement" 979 }, 980 { 981 "name": "ietf-yang-types", 982 "revision": "2013-07-15", 983 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 984 "conformance-type": "import" 985 } 986 ] 987 } 989 A.2. Logical Network Elements 991 Each LNE can have a specific data model that is determined at run 992 time, so it is appropriate to mount it using the "inline" method, 993 hence the following "schema-mounts" data: 995 "ietf-yang-schema-mount:schema-mounts": { 996 "mount-point": [ 997 { 998 "module": "ietf-logical-network-element", 999 "name": "root", 1000 "inline": [null] 1001 } 1002 ] 1003 } 1005 An administrator of the host device has to configure an entry for 1006 each LNE instance, for example, 1007 { 1008 "ietf-interfaces:interfaces": { 1009 "interface": [ 1010 { 1011 "name": "eth0", 1012 "type": "iana-if-type:ethernetCsmacd", 1013 "enabled": true, 1014 "ietf-logical-network-element:bind-lne-name": "eth0" 1015 } 1016 ] 1017 }, 1018 "ietf-logical-network-element:logical-network-elements": { 1019 "logical-network-element": [ 1020 { 1021 "name": "lne-1", 1022 "managed": true, 1023 "description": "LNE with NIs", 1024 "root": { 1025 ... 1026 } 1027 }, 1028 ... 1029 ] 1030 } 1031 } 1033 and then also place necessary state data as the contents of the 1034 "root" instance, which should include at least 1036 o YANG library data specifying the LNE's data model, for example: 1038 "ietf-yang-library:modules-state": { 1039 "module-set-id": "9358e11874068c8be06562089e94a89e0a392019", 1040 "module": [ 1041 { 1042 "name": "iana-if-type", 1043 "revision": "2014-05-08", 1044 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 1045 "conformance-type": "implement" 1046 }, 1047 { 1048 "name": "ietf-inet-types", 1049 "revision": "2013-07-15", 1050 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1051 "conformance-type": "import" 1052 }, 1053 { 1054 "name": "ietf-interfaces", 1055 "revision": "2014-05-08", 1056 "feature": [ 1057 "arbitrary-names", 1058 "pre-provisioning" 1059 ], 1060 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 1061 "conformance-type": "implement" 1062 }, 1063 { 1064 "name": "ietf-ip", 1065 "revision": "2014-06-16", 1066 "feature": [ 1067 "ipv6-privacy-autoconf" 1068 ], 1069 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 1070 "conformance-type": "implement" 1071 }, 1072 { 1073 "name": "ietf-network-instance", 1074 "revision": "2016-10-27", 1075 "feature": [ 1076 "bind-network-instance-name" 1077 ], 1078 "namespace": 1079 "urn:ietf:params:xml:ns:yang:ietf-network-instance", 1080 "conformance-type": "implement" 1081 }, 1082 { 1083 "name": "ietf-yang-library", 1084 "revision": "2016-06-21", 1085 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 1086 "conformance-type": "implement" 1087 }, 1088 { 1089 "name": "ietf-yang-schema-mount", 1090 "revision": "2017-05-16", 1091 "namespace": 1092 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 1093 "conformance-type": "implement" 1094 }, 1095 { 1096 "name": "ietf-yang-types", 1097 "revision": "2013-07-15", 1098 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1099 "conformance-type": "import" 1100 } 1101 ] 1102 } 1104 o state data for interfaces assigned to the LNE instance (that 1105 effectively become system-controlled interfaces for the LNE), for 1106 example: 1108 "ietf-interfaces:interfaces-state": { 1109 "interface": [ 1110 { 1111 "name": "eth0", 1112 "type": "iana-if-type:ethernetCsmacd", 1113 "oper-status": "up", 1114 "statistics": { 1115 "discontinuity-time": "2016-12-16T17:11:27+02:00" 1116 }, 1117 "ietf-ip:ipv6": { 1118 "address": [ 1119 { 1120 "ip": "fe80::42a8:f0ff:fea8:24fe", 1121 "origin": "link-layer", 1122 "prefix-length": 64 1123 } 1124 ] 1125 } 1126 }, 1127 ... 1128 ] 1129 } 1131 A.3. Network Instances 1133 Assuming that network instances share the same data model, it can be 1134 mounted using the "use-schema" method as follows: 1136 "ietf-yang-schema-mount:schema-mounts": { 1137 "mount-point": [ 1138 { 1139 "module": "ietf-network-instance", 1140 "name": "root", 1141 "parent-reference": ["ietf-interfaces"], 1142 "use-schema": [ 1143 { 1144 "name": "ni-schema" 1145 } 1146 ] 1147 } 1148 ], 1149 "schema": [ 1150 { 1151 "name": "ni-schema", 1152 "module": [ 1153 { 1154 "name": "ietf-ipv4-unicast-routing", 1155 "revision": "2016-11-04", 1156 "namespace": 1157 "urn:ietf:params:xml:ns:yang:ietf-ipv4-unicast-routing", 1158 "conformance-type": "implement" 1159 }, 1160 { 1161 "name": "ietf-ipv6-unicast-routing", 1162 "revision": "2016-11-04", 1163 "namespace": 1164 "urn:ietf:params:xml:ns:yang:ietf-ipv6-unicast-routing", 1165 "conformance-type": "implement" 1166 }, 1167 { 1168 "name": "ietf-routing", 1169 "revision": "2016-11-04", 1170 "feature": [ 1171 "multiple-ribs", 1172 "router-id" 1173 ], 1174 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing", 1175 "conformance-type": "implement" 1176 } 1177 ] 1178 } 1179 ] 1180 } 1182 Note also that the "ietf-interfaces" module appears in the 1183 "parent-reference" leaf-list for the mounted NI schema. This means 1184 that references to LNE interfaces, such as "outgoing-interface" in 1185 static routes, are valid despite the fact that "ietf-interfaces" 1186 isn't part of the NI schema. 1188 A.4. Invoking an RPC Operation 1190 Assume that the mounted NI data model also implements the "ietf-isis" 1191 module [I-D.ietf-isis-yang-isis-cfg]. An RPC operation defined in 1192 this module, such as "clear-adjacency", can be invoked by a client 1193 session of a LNE's RESTCONF server as an action tied to a the mount 1194 point of a particular network instance using a request URI like this 1195 (all on one line): 1197 POST /restconf/data/ietf-network-instance:network-instances/ 1198 network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1 1200 Appendix B. Open Issues 1202 B.1. RPC Operations and Notifications in Mounted Modules 1204 Turning RPC operations defined in mounted modules into actions tied 1205 to the corresponding mount point (see Section 5, and similarly for 1206 notifications) is not possible if the path to the mount point in the 1207 parent schema contains a keyless list (Section 7.15 of [RFC7950]). 1208 The solutions for this corner case are possible: 1210 1. any mount point MUST NOT have a keyless list among its ancestors 1212 2. any mounted module MUST NOT contain RPC operations and/or 1213 notifications 1215 3. specifically for each mount point, at least one of the above 1216 conditions MUST be satisfied. 1218 4. treat such actions and notifications as non-existing, i.e., 1219 ignore them. 1221 The first two requirements seem rather restrictive. On the other 1222 hand, the last one is difficult to guarantee - for example, things 1223 can break after an augment within the mounted schema. 1225 B.2. Tree Representation 1227 Need to decide how/if mount points are represented in trees. 1229 B.3. Design-Time Mounts 1231 The document currently doesn't provide explicit support for design- 1232 time mounts. Design-time mounts have been identified as possibly for 1233 multiple cases, and it may be worthwhile to identify a minimum or 1234 complete set of modules that must be supported under a mount point. 1235 This could be used in service modules that want to allow for 1236 configuration of device-specific information. One option could be to 1237 add an extension that specify that a certain module is required to be 1238 mounted. 1240 Also, if design-time mounts are supported, it could be possible to 1241 represent both mounts points and their required modules in tree 1242 representations and support for such would need to be defined. 1244 Authors' Addresses 1246 Martin Bjorklund 1247 Tail-f Systems 1249 Email: mbj@tail-f.com 1251 Ladislav Lhotka 1252 CZ.NIC 1254 Email: lhotka@nic.cz