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