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