idnits 2.17.1 draft-ietf-netmod-schema-mount-06.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 497 has weird spacing: '... prefix yan...' == Line 521 has weird spacing: '...evision uni...' == Line 522 has weird spacing: '...ce-type enu...' == Line 525 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 (July 5, 2017) is 2486 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: January 6, 2018 CZ.NIC 6 July 5, 2017 8 YANG Schema Mount 9 draft-ietf-netmod-schema-mount-06 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 January 6, 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 . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . 18 65 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 66 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 67 12.1. Normative References . . . . . . . . . . . . . . . . . . 19 68 12.2. Informative References . . . . . . . . . . . . . . . . . 19 69 Appendix A. Example: Device Model with LNEs and NIs . . . . . . 20 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 . . . . . . . . . . . . . . . . 26 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 configuration data 226 o container 228 o list 230 o operation 232 The following terms are defined in [RFC7223] and are not redefined 233 here: 235 o system-controlled interface 236 Tree diagrams used in this document follow the notation defined in 237 [I-D.ietf-netmod-yang-tree-diagrams]. 239 2.1. Glossary of New Terms 241 o inline schema: a mounted schema whose definition is provided as 242 part of the mounted data, using YANG library [RFC7895]. 244 o mount point: container or list node whose definition contains the 245 "mount-point" extension statement. The argument of the 246 "mount-point" statement defines the name of the mount point. 248 o parent schema (of a particular mounted schema): the schema that 249 contains the mount point for the mounted schema. 251 o top-level schema: a schema according to [RFC7950] in which schema 252 trees of each module (except augments) start at the root node. 254 2.2. Namespace Prefixes 256 In this document, names of data nodes, YANG extensions, actions and 257 other data model objects are often used without a prefix, as long as 258 it is clear from the context in which YANG module each name is 259 defined. Otherwise, names are prefixed using the standard prefix 260 associated with the corresponding YANG module, as shown in Table 1. 262 +---------+------------------------+-----------+ 263 | Prefix | YANG module | Reference | 264 +---------+------------------------+-----------+ 265 | yangmnt | ietf-yang-schema-mount | Section 8 | 266 | inet | ietf-inet-types | [RFC6991] | 267 | yang | ietf-yang-types | [RFC6991] | 268 | yanglib | ietf-yang-library | [RFC7895] | 269 +---------+------------------------+-----------+ 271 Table 1: Namespace Prefixes 273 3. Schema Mount 275 The schema mount mechanism defined in this document provides a new 276 extensibility mechanism for use with YANG 1.1. In contrast to the 277 existing mechanisms described in Section 1, schema mount defines the 278 relationship between the source and target YANG modules outside these 279 modules. The procedure consists of two separate steps that are 280 described in the following subsections. 282 3.1. Mount Point Definition 284 A "container" or "list" node becomes a mount point if the 285 "mount-point" extension (defined in the "ietf-yang-schema-mount" 286 module) is used in its definition. This extension can appear only as 287 a substatement of "container" and "list" statements. 289 The argument of the "mount-point" extension is a YANG identifier that 290 defines the name of the mount point. A module MAY contain multiple 291 "mount-point" statements having the same argument. 293 It is therefore up to the designer of the parent schema to decide 294 about the placement of mount points. A mount point can also be made 295 conditional by placing "if-feature" and/or "when" as substatements of 296 the "container" or "list" statement that represents the mount point. 298 The "mount-point" statement MUST NOT be used in a YANG version 1 299 module. Note, however, that modules written in any YANG version, 300 including version 1, can be mounted under a mount point. 302 3.2. Specification of the Mounted Schema 304 Mounted schemas for all mount points in the parent schema are 305 determined from state data in the "yangmnt:schema-mounts" container. 306 Data in this container is intended to be as stable as data in the 307 top-level YANG library [RFC7895]. In particular, it SHOULD NOT 308 change during the same management session. 310 Generally, the modules that are mounted under a mount point have no 311 relation to the modules in the parent schema; specifically, if a 312 module is mounted it may or may not be present in the parent schema 313 and, if present, its data will generally have no relationship to the 314 data of the parent. Exceptions are possible and such needs to be 315 defined in the model defining the exception, e.g., the interface 316 module in [I-D.ietf-rtgwg-lne-model]. 318 The "schema-mounts" container has the "mount-point" list as one of 319 its children. Every entry of this list refers through its key to a 320 mount point and specifies the mounted schema. 322 If a mount point is defined in the parent schema but does not have an 323 entry in the "mount-point" list, then the mounted schema is void, 324 i.e., instances of that mount point MUST NOT contain any data above 325 those that are defined in the parent schema. 327 If multiple mount points with the same name are defined in the same 328 module - either directly or because the mount point is defined in a 329 grouping and the grouping is used multiple times - then the 330 corresponding "mount-point" entry applies equally to all such mount 331 points. 333 The "config" property of mounted schema nodes is overridden and all 334 nodes in the mounted schema are read-only ("config false") if at 335 least one of the following conditions is satisfied for a mount point: 337 o the mount point is itself defined as "config false" 339 o the "config" leaf in the corresponding entry of the "mount-point" 340 list is set to "false". 342 An entry of the "mount-point" list can specify the mounted schema in 343 two different ways: 345 1. by stating that the schema is available inline, i.e., in run-time 346 instance data; or 348 2. by referring to one or more entries of the "schema" list in the 349 same instance of "schema-mounts". 351 In case 1, the mounted schema is determined at run time: every 352 instance of the mount point that exists in the parent tree MUST 353 contain a copy of YANG library data [RFC7895] that defines the 354 mounted schema exactly as for a top-level data model. A client is 355 expected to retrieve this data from the instance tree, possibly after 356 creating the mount point. Instances of the same mount point MAY use 357 different mounted schemas. 359 In case 2, the mounted schema is defined by the combination of all 360 "schema" entries referred to in the "use-schema" list. In this case, 361 the mounted schema is specified as implementation-time data that can 362 be retrieved together with YANG library data for the parent schema, 363 i.e., even before any instances of the mount point exist. However, 364 the mounted schema has to be the same for all instances of the mount 365 point. Note, that in this case a mount point may include a mounted 366 YANG library module and the data contained in the mounted module MUST 367 exactly match the data contained in the "schema" entries associated 368 with the mount point. 370 Each entry of the "schema" list contains: 372 o a list in the YANG library format specifying all YANG modules (and 373 revisions etc.) that are implemented or imported in the mounted 374 schema. Note that this includes modules that solely augment other 375 listed modules; 377 o (optionally) a new "mount-point" list that applies to mount points 378 defined within the mounted schema. 380 3.3. Multiple Levels of Schema Mount 382 YANG modules in a mounted schema MAY again contain mount points under 383 which subschemas can be mounted. Consequently, it is possible to 384 construct data models with an arbitrary number of schema levels. A 385 subschema for a mount point contained in a mounted module can be 386 specified in one of the following ways: 388 o by implementing "ietf-yang-library" and "ietf-yang-schema-mount" 389 modules in the mounted schema, and specifying the subschemas 390 exactly as it is done in the top-level schema 392 o by using the "mount-point" list inside the corresponding "schema" 393 entry. 395 The former method is applicable to both "inline" and "use-schema" 396 cases whereas the latter requires the "use-schema" case. On the 397 other hand, the latter method allows for a compact representation of 398 a multi-level schema the does not rely on the presence of any 399 instance data. 401 4. Referring to Data Nodes in the Parent Schema 403 A fundamental design principle of schema mount is that the mounted 404 data model works exactly as a top-level data model, i.e., it is 405 confined to the "mount jail". This means that all paths in the 406 mounted data model (in leafrefs, instance-identifiers, XPath 407 expressions, and target nodes of augments) are interpreted with the 408 mount point as the root node. YANG modules of the mounted schema as 409 well as corresponding instance data thus cannot refer to schema nodes 410 or instance data outside the mount jail. 412 However, this restriction is sometimes too severe. A typical example 413 is network instances (NI) [I-D.ietf-rtgwg-ni-model], where each NI 414 has its own routing engine but the list of interfaces is global and 415 shared by all NIs. If we want to model this organization with the NI 416 schema mounted using schema mount, the overall schema tree would look 417 schematically as follows: 419 +--rw interfaces 420 | +--rw interface* [name] 421 | ... 422 +--rw network-instances 423 +--rw network-instance* [name] 424 +--rw name 425 +--rw root 426 +--rw routing 427 ... 429 Here, the "root" node is the mount point for the NI schema. Routing 430 configuration inside an NI often needs to refer to interfaces (at 431 least those that are assigned to the NI), which is impossible unless 432 such a reference can point to a node in the parent schema (interface 433 name). 435 Therefore, schema mount also allows for such references. For every 436 schema mounted using the "use-schema" method, it is possible to 437 specify a leaf-list named "parent-reference" that contains zero or 438 more XPath 1.0 expressions. Each expression is evaluated with the 439 root of the parent data tree as the context node and the result MUST 440 be a nodeset (see the description of the "parent-reference" node for 441 a complete definition of the evaluation context). For the purposes 442 of evaluating XPath expressions within the mounted data tree, the 443 union of all such nodesets is added to the accessible data tree. 445 It is worth emphasizing that 447 o The nodes specified in "parent-reference" leaf-list are available 448 in the mounted schema only for XPath evaluations. In particular, 449 they cannot be accessed there via network management protocols 450 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. 452 o The mechanism of referencing nodes in the parent schema is not 453 available for schemas mounted using the "inline" method. 455 5. RPC operations and Notifications 457 If a mounted YANG module defines an RPC operation, clients can invoke 458 this operation by representing it as an action defined for the 459 corresponding mount point, see Section 7.15 of ^RFC7950. An example 460 of this is given in Appendix A.4. 462 Similarly, if the server emits a notification defined at the top 463 level of any mounted module, it MUST be represented as if the 464 notification was connected to the mount point, see Section 7.16 of 465 [RFC7950]. 467 Note, inline actions and notifications will not work when they are 468 contained within a list node without a "key" statement (see section 469 7.15 and 7.16 of [RFC7950]). Therefore, to be useful, mount points 470 which contain modules with RPCs, actions, and notifications SHOULD 471 NOT have any ancestor node that is a list node without a "key" 472 statement. This requirement applies to the definition of modules 473 using the "mount-point" extension statement. 475 6. Implementation Notes 477 Network management of devices that use a data model with schema mount 478 can be implemented in different ways. However, the following 479 implementations options are envisioned as typical: 481 o shared management: instance data of both parent and mounted 482 schemas are accessible within the same management session. 484 o split management: one (master) management session has access to 485 instance data of both parent and mounted schemas but, in addition, 486 an extra session exists for every instance of the mount point, 487 having access only to the mounted data tree. 489 7. Data Model 491 This document defines the YANG 1.1 module [RFC7950] 492 "ietf-yang-schema-mount", which has the following structure: 494 module: ietf-yang-schema-mount 495 +--ro schema-mounts 496 +--ro namespace* [prefix] 497 | +--ro prefix yang:yang-identifier 498 | +--ro uri? inet:uri 499 +--ro mount-point* [module name] 500 | +--ro module yang:yang-identifier 501 | +--ro name yang:yang-identifier 502 | +--ro config? boolean 503 | +--ro (schema-ref)? 504 | +--:(inline) 505 | | +--ro inline? empty 506 | +--:(use-schema) 507 | +--ro use-schema* [name] 508 | +--ro name 509 | | -> /schema-mounts/schema/name 510 | +--ro parent-reference* yang:xpath1.0 511 +--ro schema* [name] 512 +--ro name string 513 +--ro module* [name revision] 514 | +--ro name yang:yang-identifier 515 | +--ro revision union 516 | +--ro schema? inet:uri 517 | +--ro namespace inet:uri 518 | +--ro feature* yang:yang-identifier 519 | +--ro deviation* [name revision] 520 | | +--ro name yang:yang-identifier 521 | | +--ro revision union 522 | +--ro conformance-type enumeration 523 | +--ro submodule* [name revision] 524 | +--ro name yang:yang-identifier 525 | +--ro revision union 526 | +--ro schema? inet:uri 527 +--ro mount-point* [module name] 528 +--ro module yang:yang-identifier 529 +--ro name yang:yang-identifier 530 +--ro config? boolean 531 +--ro (schema-ref)? 532 +--:(inline) 533 | +--ro inline? empty 534 +--:(use-schema) 535 +--ro use-schema* [name] 536 +--ro name 537 | -> /schema-mounts/schema/name 538 +--ro parent-reference* yang:xpath1.0 540 8. Schema Mount YANG Module 542 This module references [RFC6991] and [RFC7895]. 544 file "ietf-yang-schema-mount@2017-06-16.yang" 546 module ietf-yang-schema-mount { 547 yang-version 1.1; 548 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"; 549 prefix yangmnt; 551 import ietf-inet-types { 552 prefix inet; 553 reference 554 "RFC 6991: Common YANG Data Types"; 555 } 557 import ietf-yang-types { 558 prefix yang; 559 reference 560 "RFC 6991: Common YANG Data Types"; 561 } 563 import ietf-yang-library { 564 prefix yanglib; 565 reference 566 "RFC 7895: YANG Module Library"; 567 } 569 organization 570 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 572 contact 573 "WG Web: 574 WG List: 576 Editor: Martin Bjorklund 577 579 Editor: Ladislav Lhotka 580 "; 582 description 583 "This module defines a YANG extension statement that can be used 584 to incorporate data models defined in other YANG modules in a 585 module. It also defines operational state data that specify the 586 overall structure of the data model. 588 Copyright (c) 2017 IETF Trust and the persons identified as 589 authors of the code. All rights reserved. 591 Redistribution and use in source and binary forms, with or 592 without modification, is permitted pursuant to, and subject to 593 the license terms contained in, the Simplified BSD License set 594 forth in Section 4.c of the IETF Trust's Legal Provisions 595 Relating to IETF Documents 596 (https://trustee.ietf.org/license-info). 598 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 599 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 600 'OPTIONAL' in the module text are to be interpreted as described 601 in RFC 2119 (https://tools.ietf.org/html/rfc2119). 603 This version of this YANG module is part of RFC XXXX 604 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 605 full legal notices."; 607 revision 2017-06-16 { 608 description 609 "Initial revision."; 610 reference 611 "RFC XXXX: YANG Schema Mount"; 612 } 614 /* 615 * Extensions 616 */ 618 extension mount-point { 619 argument name; 620 description 621 "The argument 'name' is a YANG identifier, i.e., it is of the 622 type 'yang:yang-identifier'. 624 The 'mount-point' statement MUST NOT be used in a YANG 625 version 1 module, neither explicitly nor via a 'uses' 626 statement. 628 The 'mount-point' statement MAY be present as a substatement 629 of 'container' and 'list', and MUST NOT be present elsewhere. 631 If a mount point is defined in a grouping, its name is bound 632 to the module where the grouping is used. 634 A mount point defines a place in the node hierarchy where 635 other data models may be attached. A server that implements a 636 module with a mount point populates the 637 /schema-mounts/mount-point list with detailed information on 638 which data models are mounted at each mount point."; 639 } 641 /* 642 * Groupings 643 */ 645 grouping mount-point-list { 646 description 647 "This grouping is used inside the 'schema-mounts' container and 648 inside the 'schema' list."; 649 list mount-point { 650 key "module name"; 651 description 652 "Each entry of this list specifies a schema for a particular 653 mount point. 655 Each mount point MUST be defined using the 'mount-point' 656 extension in one of the modules listed in the corresponding 657 YANG library instance with conformance type 'implement'. The 658 corresponding YANG library instance is: 660 - standard YANG library state data as defined in RFC 7895, 661 if the 'mount-point' list is a child of 'schema-mounts', 663 - the contents of the sibling 'yanglib:modules-state' 664 container, if the 'mount-point' list is a child of 665 'schema'."; 666 leaf module { 667 type yang:yang-identifier; 668 description 669 "Name of a module containing the mount point."; 670 } 671 leaf name { 672 type yang:yang-identifier; 673 description 674 "Name of the mount point defined using the 'mount-point' 675 extension."; 676 } 677 leaf config { 678 type boolean; 679 default "true"; 680 description 681 "If this leaf is set to 'false', then all data nodes in the 682 mounted schema are read-only (config false), regardless of 683 their 'config' property."; 685 } 686 choice schema-ref { 687 description 688 "Alternatives for specifying the schema."; 689 leaf inline { 690 type empty; 691 description 692 "This leaf indicates that the server has mounted 693 'ietf-yang-library' and 'ietf-schema-mount' at the mount 694 point, and their instantiation (i.e., state data 695 containers 'yanglib:modules-state' and 'schema-mounts') 696 provides the information about the mounted schema."; 697 } 698 list use-schema { 699 key "name"; 700 description 701 "Each entry of this list contains a reference to a schema 702 defined in the /schema-mounts/schema list."; 703 leaf name { 704 type leafref { 705 path "/schema-mounts/schema/name"; 706 } 707 description 708 "Name of the referenced schema."; 709 } 710 leaf-list parent-reference { 711 type yang:xpath1.0; 712 description 713 "Entries of this leaf-list are XPath 1.0 expressions 714 that are evaluated in the following context: 716 - The context node is the root node of the parent data 717 tree. 719 - The accessible tree is the parent data tree 720 *without* any nodes defined in modules that are 721 mounted inside the parent schema. 723 - The context position and context size are both equal 724 to 1. 726 - The set of variable bindings is empty. 728 - The function library is the core function library 729 defined in [XPath] and the functions defined in 730 Section 10 of [RFC7950]. 732 - The set of namespace declarations is defined by the 733 'namespace' list under 'schema-mounts'. 735 Each XPath expression MUST evaluate to a nodeset 736 (possibly empty). For the purposes of evaluating XPath 737 expressions whose context nodes are defined in the 738 mounted schema, the union of all these nodesets 739 together with ancestor nodes are added to the 740 accessible data tree."; 741 } 742 } 743 } 744 } 745 } 747 /* 748 * State data nodes 749 */ 751 container schema-mounts { 752 config false; 753 description 754 "Contains information about the structure of the overall 755 mounted data model implemented in the server."; 756 list namespace { 757 key "prefix"; 758 description 759 "This list provides a mapping of namespace prefixes that are 760 used in XPath expressions of 'parent-reference' leafs to the 761 corresponding namespace URI references."; 762 leaf prefix { 763 type yang:yang-identifier; 764 description 765 "Namespace prefix."; 766 } 767 leaf uri { 768 type inet:uri; 769 description 770 "Namespace URI reference."; 771 } 772 } 773 uses mount-point-list; 774 list schema { 775 key "name"; 776 description 777 "Each entry specifies a schema that can be mounted at a mount 778 point. The schema information consists of two parts: 780 - an instance of YANG library that defines YANG modules used 781 in the schema, 783 - mount-point list with content identical to the top-level 784 mount-point list (this makes the schema structure 785 recursive)."; 786 leaf name { 787 type string; 788 description 789 "Arbitrary name of the schema entry."; 790 } 791 uses yanglib:module-list; 792 uses mount-point-list; 793 } 794 } 795 } 797 799 9. IANA Considerations 801 This document registers a URI in the IETF XML registry [RFC3688]. 802 Following the format in RFC 3688, the following registration is 803 requested to be made. 805 URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 807 Registrant Contact: The IESG. 809 XML: N/A, the requested URI is an XML namespace. 811 This document registers a YANG module in the YANG Module Names 812 registry [RFC6020]. 814 name: ietf-yang-schema-mount 815 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount 816 prefix: yangmnt 817 reference: RFC XXXX 819 10. Security Considerations 821 TBD 823 11. Contributors 825 The idea of having some way to combine schemas from different YANG 826 modules into one has been proposed independently by several groups of 827 people: Alexander Clemm, Jan Medved, and Eric Voit 828 ([I-D.clemm-netmod-mount]); and Lou Berger and Christian Hopps: 830 o Lou Berger, LabN Consulting, L.L.C., 832 o Alexander Clemm, Huawei, 834 o Christian Hopps, Deutsche Telekom, 836 o Jan Medved, Cisco, 838 o Eric Voit, Cisco, 840 12. References 842 12.1. Normative References 844 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 845 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 846 RFC2119, March 1997, 847 . 849 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 850 DOI 10.17487/RFC3688, January 2004, 851 . 853 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 854 the Network Configuration Protocol (NETCONF)", RFC 6020, 855 DOI 10.17487/RFC6020, October 2010, 856 . 858 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 859 6991, DOI 10.17487/RFC6991, July 2013, 860 . 862 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 863 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 864 . 866 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 867 RFC 7950, DOI 10.17487/RFC7950, August 2016, 868 . 870 12.2. Informative References 872 [I-D.clemm-netmod-mount] 873 Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined 874 Information from Remote Datastores", draft-clemm-netmod- 875 mount-06 (work in progress), March 2017. 877 [I-D.ietf-isis-yang-isis-cfg] 878 Litkowski, S., Yeung, D., Lindem, A., Zhang, Z., and L. 879 Lhotka, "YANG Data Model for IS-IS protocol", draft-ietf- 880 isis-yang-isis-cfg-17 (work in progress), March 2017. 882 [I-D.ietf-netmod-yang-tree-diagrams] 883 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 884 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 885 2017. 887 [I-D.ietf-rtgwg-device-model] 888 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 889 "Network Device YANG Logical Organization", draft-ietf- 890 rtgwg-device-model-02 (work in progress), March 2017. 892 [I-D.ietf-rtgwg-lne-model] 893 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 894 Liu, "YANG Logical Network Elements", draft-ietf-rtgwg- 895 lne-model-03 (work in progress), July 2017. 897 [I-D.ietf-rtgwg-ni-model] 898 Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. 899 Liu, "YANG Network Instances", draft-ietf-rtgwg-ni- 900 model-03 (work in progress), July 2017. 902 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 903 and A. Bierman, Ed., "Network Configuration Protocol 904 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 905 . 907 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 908 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 909 . 911 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 912 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 913 . 915 Appendix A. Example: Device Model with LNEs and NIs 917 This non-normative example demonstrates an implementation of the 918 device model as specified in Section 2 of 919 [I-D.ietf-rtgwg-device-model], using both logical network elements 920 (LNE) and network instances (NI). 922 A.1. Physical Device 924 The data model for the physical device may be described by this YANG 925 library content: 927 "ietf-yang-library:modules-state": { 928 "module-set-id": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899", 929 "module": [ 930 { 931 "name": "iana-if-type", 932 "revision": "2014-05-08", 933 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 934 "conformance-type": "implement" 935 }, 936 { 937 "name": "ietf-inet-types", 938 "revision": "2013-07-15", 939 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 940 "conformance-type": "import" 941 }, 942 { 943 "name": "ietf-interfaces", 944 "revision": "2014-05-08", 945 "feature": [ 946 "arbitrary-names", 947 "pre-provisioning" 948 ], 949 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 950 "conformance-type": "implement" 951 }, 952 { 953 "name": "ietf-ip", 954 "revision": "2014-06-16", 955 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 956 "conformance-type": "implement" 957 }, 958 { 959 "name": "ietf-logical-network-element", 960 "revision": "2016-10-21", 961 "feature": [ 962 "bind-lne-name" 963 ], 964 "namespace": 965 "urn:ietf:params:xml:ns:yang:ietf-logical-network-element", 966 "conformance-type": "implement" 967 }, 968 { 969 "name": "ietf-yang-library", 970 "revision": "2016-06-21", 971 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 972 "conformance-type": "implement" 973 }, 974 { 975 "name": "ietf-yang-schema-mount", 976 "revision": "2017-05-16", 977 "namespace": 978 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 979 "conformance-type": "implement" 980 }, 981 { 982 "name": "ietf-yang-types", 983 "revision": "2013-07-15", 984 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 985 "conformance-type": "import" 986 } 987 ] 988 } 990 A.2. Logical Network Elements 992 Each LNE can have a specific data model that is determined at run 993 time, so it is appropriate to mount it using the "inline" method, 994 hence the following "schema-mounts" data: 996 "ietf-yang-schema-mount:schema-mounts": { 997 "mount-point": [ 998 { 999 "module": "ietf-logical-network-element", 1000 "name": "root", 1001 "inline": [null] 1002 } 1003 ] 1004 } 1006 An administrator of the host device has to configure an entry for 1007 each LNE instance, for example, 1008 { 1009 "ietf-interfaces:interfaces": { 1010 "interface": [ 1011 { 1012 "name": "eth0", 1013 "type": "iana-if-type:ethernetCsmacd", 1014 "enabled": true, 1015 "ietf-logical-network-element:bind-lne-name": "eth0" 1016 } 1017 ] 1018 }, 1019 "ietf-logical-network-element:logical-network-elements": { 1020 "logical-network-element": [ 1021 { 1022 "name": "lne-1", 1023 "managed": true, 1024 "description": "LNE with NIs", 1025 "root": { 1026 ... 1027 } 1028 }, 1029 ... 1030 ] 1031 } 1032 } 1034 and then also place necessary state data as the contents of the 1035 "root" instance, which should include at least 1037 o YANG library data specifying the LNE's data model, for example: 1039 "ietf-yang-library:modules-state": { 1040 "module-set-id": "9358e11874068c8be06562089e94a89e0a392019", 1041 "module": [ 1042 { 1043 "name": "iana-if-type", 1044 "revision": "2014-05-08", 1045 "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type", 1046 "conformance-type": "implement" 1047 }, 1048 { 1049 "name": "ietf-inet-types", 1050 "revision": "2013-07-15", 1051 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types", 1052 "conformance-type": "import" 1053 }, 1054 { 1055 "name": "ietf-interfaces", 1056 "revision": "2014-05-08", 1057 "feature": [ 1058 "arbitrary-names", 1059 "pre-provisioning" 1060 ], 1061 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces", 1062 "conformance-type": "implement" 1063 }, 1064 { 1065 "name": "ietf-ip", 1066 "revision": "2014-06-16", 1067 "feature": [ 1068 "ipv6-privacy-autoconf" 1069 ], 1070 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 1071 "conformance-type": "implement" 1072 }, 1073 { 1074 "name": "ietf-network-instance", 1075 "revision": "2016-10-27", 1076 "feature": [ 1077 "bind-network-instance-name" 1078 ], 1079 "namespace": 1080 "urn:ietf:params:xml:ns:yang:ietf-network-instance", 1081 "conformance-type": "implement" 1082 }, 1083 { 1084 "name": "ietf-yang-library", 1085 "revision": "2016-06-21", 1086 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library", 1087 "conformance-type": "implement" 1088 }, 1089 { 1090 "name": "ietf-yang-schema-mount", 1091 "revision": "2017-05-16", 1092 "namespace": 1093 "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount", 1094 "conformance-type": "implement" 1095 }, 1096 { 1097 "name": "ietf-yang-types", 1098 "revision": "2013-07-15", 1099 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types", 1100 "conformance-type": "import" 1101 } 1102 ] 1103 } 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 "namespace": [ 1138 { 1139 "prefix": "if", 1140 "uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces" 1141 } 1142 ], 1143 "mount-point": [ 1144 { 1145 "module": "ietf-network-instance", 1146 "name": "root", 1147 "use-schema": [ 1148 { 1149 "name": "ni-schema", 1150 "parent-reference": ["/if:interfaces"] 1151 } 1153 ] 1154 } 1155 ], 1156 "schema": [ 1157 { 1158 "name": "ni-schema", 1159 "module": [ 1160 { 1161 "name": "ietf-ipv4-unicast-routing", 1162 "revision": "2016-11-04", 1163 "namespace": 1164 "urn:ietf:params:xml:ns:yang:ietf-ipv4-unicast-routing", 1165 "conformance-type": "implement" 1166 }, 1167 { 1168 "name": "ietf-ipv6-unicast-routing", 1169 "revision": "2016-11-04", 1170 "namespace": 1171 "urn:ietf:params:xml:ns:yang:ietf-ipv6-unicast-routing", 1172 "conformance-type": "implement" 1173 }, 1174 { 1175 "name": "ietf-routing", 1176 "revision": "2016-11-04", 1177 "feature": [ 1178 "multiple-ribs", 1179 "router-id" 1180 ], 1181 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing", 1182 "conformance-type": "implement" 1183 } 1184 ] 1185 } 1186 ] 1187 } 1189 Note also that the "ietf-interfaces" module appears in the 1190 "parent-reference" leaf-list for the mounted NI schema. This means 1191 that references to LNE interfaces, such as "outgoing-interface" in 1192 static routes, are valid despite the fact that "ietf-interfaces" 1193 isn't part of the NI schema. 1195 A.4. Invoking an RPC Operation 1197 Assume that the mounted NI data model also implements the "ietf-isis" 1198 module [I-D.ietf-isis-yang-isis-cfg]. An RPC operation defined in 1199 this module, such as "clear-adjacency", can be invoked by a client 1200 session of a LNE's RESTCONF server as an action tied to a the mount 1201 point of a particular network instance using a request URI like this 1202 (all on one line): 1204 POST /restconf/data/ietf-network-instance:network-instances/ 1205 network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1 1207 Authors' Addresses 1209 Martin Bjorklund 1210 Tail-f Systems 1212 Email: mbj@tail-f.com 1214 Ladislav Lhotka 1215 CZ.NIC 1217 Email: lhotka@nic.cz