RFC 8528

YANG Schema Mount

📅 published March 2019, from ietf

📜 RFC 8528: YANG Schema Mount, but make it bestie-approved 🎀

okay so bestie, let's get the title block sorted first 💅. This one is an Internet Standards Track document ✨, so it's a real, official spec, not a draft vibe. It was written by M. Bjorklund (Tail-f Systems) and L. Lhotka (CZ.NIC) 🧚, and it was published in March 2019 🌸. It's identified as ISSN: 2070-1721 and doesn't obsolete or update any other RFCs, so it's a clean fresh start 🦋.

This document is literally the one that adds a whole schema tree from a set of YANG modules onto a mount point in another YANG module. 💖

1. Introduction ✨

okay so modularity and extensibility are, like, the core design principles of YANG 💅. The same YANG module can get mixed with different sets of other modules to build a data model that fits one specific use case 🌈. Server implementors only have to list all the YANG modules in their data model (plus their revisions and other optional choices) in the YANG library data, which is covered by [RFC7895], [RFC8525], and Section 5.6.4 of [RFC7950] 🎀. These modules sit side by side, so the top-level data nodes of each module are also top-level nodes of the whole data model 🫶.

YANG has two ways to bring a schema hierarchy from somewhere else into an internal node of the schema tree 🔥. Those are the uses and augment statements:

  • The uses statement pulls in the contents of a grouping defined in the same module or another one. See Section 4.2.6 of [RFC7950] for more details 💜.
  • The augment statement adds contents to a target node defined in the same module or another one. See Section 4.2.8 of [RFC7950] for more details 🍓.

With both of these, the module that has the uses or augment statement says exactly where the new nodes go in the schema tree 🦋.

Now here's the thing 🙈: sometimes those two mechanisms just aren't enough. Sometimes an existing module (or a whole set of them) needs to be added to the data model at places other than the root 😭. For example, modules like "ietf-interfaces" [RFC8343] are written to be used in the data model of a physical device 🌸. Now imagine we want to model a device that supports multiple logical devices [RFC8530], and each one has its own copy of "ietf-interfaces" plus maybe other modules too 💅. At the same time, we want to manage all those logical devices from the master device ✨. So we'd love a schema tree that looks like this:

  +--rw interfaces
  |  +--rw interface* [name]
  |     ...
  +--rw logical-network-element* [name]
     +--rw name
     |   ...
     +--rw interfaces
       +--rw interface* [name]
          ...

With the uses approach, the whole schema tree of "ietf-interfaces" would have to get wrapped in a grouping 🎀. Then that grouping would be used at the top level (for the master device) and also inside the "logical-network-element" list (for the logical devices) 💀. This approach has a few problems, babe:

  • It doesn't scale 😭. Every time a new YANG module needs to be added to the logical device model, we'd have to update that model with yet another uses statement pulling in the new module's contents 💔.
  • Absolute references to nodes defined inside a grouping may break if the grouping gets used in different locations 🙈.
  • Nodes defined inside a grouping belong to the namespace of the module where it's used. That makes references to those nodes from other modules difficult, or even impossible 🥺.
  • It would be hard for vendors to add proprietary modules when the uses statements live in a standard module 😤.

With the augment approach, "ietf-interfaces" would have to augment the "logical-network-element" list with all of its nodes, and at the same time define all of its nodes at the top level 🌀. That means the same hierarchy of nodes gets defined twice, which is clearly not scalable either 🥴.

So this document introduces a brand new mechanism called "schema mount" 🦋✨. It lets you mount a data model made of any number of YANG modules at a specified location of another (parent) schema 💖. Unlike the uses and augment approaches, the mounted modules don't need to be specially prepared for mounting 🧚. That means existing modules like "ietf-interfaces" can be mounted without any modifications at all 🙌.

The basic idea is to label a data node in the parent schema as the mount point, and then attach a complete data model to that mount point so the labeled node effectively becomes the root node of the mounted data model 🌈.

In principle, the mounted schema can be specified at three different phases of the data model life cycle 🎀:

  1. Design time: The mounted schema is defined along with the mount point in the parent YANG module. In this case, the mounted schema has to be the same for every implementation of the parent module 💅.
  2. Implementation time: The mounted schema is defined by a server implementor and is as stable as the YANG library information of the server 🫶.
  3. Run time: The mounted schema is defined by instance data that is part of the mounted data model. If there are multiple instances of the same mount point (for example, in multiple entries of a list), the mounted data model may be different for each instance 🔥.

The schema mount mechanism in this document only supports the latter two cases. 💜 Design-time mounts are outside the scope of this document 🙈 and could possibly be dealt with in a future revision of the YANG data modeling language 🌸.

Schema mount applies to the data model, and it specifically does not assume anything about where the instance data for the mounted schemas comes from 🦋. It may be implemented using the same instrumentation as the rest of the system, or it may be implemented by querying some other system 💖. Future specifications may define mechanisms to control or monitor the implementation of specific mount points 🧚.

How and when specific mount points get instantiated by the server is out of scope for this document 🎀. Such mechanisms may be defined in future specifications 💅.

This document allows mounting of complete data models only ✨. Other specifications may extend this model by defining additional mechanisms, such as mounting sub-hierarchies of a module 🌈.

The YANG modules in this document conform to the Network Management Datastore Architecture (NMDA) [RFC8342] 👑.

2. Terminology and Notation 💅

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🎀.

The following terms are defined in [RFC7950] and aren't redefined here 🫶:

  • action
  • container
  • data node
  • list
  • RPC operation
  • schema node
  • schema tree

The following terms are defined in [RFC8342] and aren't redefined here 🦋:

  • client
  • notification
  • operational state
  • server

The following term is defined in [RFC8343] and isn't redefined here 🌸:

  • system-controlled interface

The following term is defined in [RFC8525] and isn't redefined here 💜:

  • YANG library content identifier

The following additional terms are used in this document ✨:

  • mount point: A container or a list node whose definition contains the mount-point extension statement. The argument of the mount-point extension statement defines a label for the mount point 🧚.
  • schema: A collection of schema trees with a common root 🌈.
  • top-level schema: A schema rooted at the root node 👑.
  • mounted schema: A schema rooted at a mount point 🎀.
  • parent schema (of a mounted schema): A schema containing the mount point 💖.
  • schema mount: The mechanism to combine data models defined in this document 🔥.

2.1. Tree Diagrams 🌸

Tree diagrams used in this document follow the notation defined in [RFC8340] 💅.

That's Part 1 done, bestie! 🌈 More parts are coming, so stay tuned 💖✨

2.2. Namespace Prefixes ✨

okay so, names of data nodes, YANG extensions, actions, and other data model objects get used without a prefix a lot in this doc 💅 That's totally fine when the YANG module they live in is obvious from context. When it's not obvious, we slap on the standard prefix for that YANG module, as shown in Table 1. 🎀

     +---------+------------------------+----------------------+
     | Prefix  | YANG module            | Reference            |
     +---------+------------------------+----------------------+
     | yangmnt | ietf-yang-schema-mount | Section 9            |
     | inet    | ietf-inet-types        | [RFC6991]            |
     | yang    | ietf-yang-types        | [RFC6991]            |
     | yanglib | ietf-yang-library      | [RFC7895], [RFC8525] |
     +---------+------------------------+----------------------+

                     Table 1: Namespace Prefixes

3. Schema Mount 🦋

bestie, this is the main event 😭 The schema mount mechanism defined in this document gives us a brand-new extensibility mechanism for use with YANG 1.1 [RFC7950]. Unlike the existing mechanisms from Section 1, schema mount defines the relationship between the source and target YANG modules outside those modules. It's giving modular, it's giving clean 🧚

3.1. Mount Point Definition 🌸

so a container or list node becomes a mount point if the mount-point extension statement (defined in the ietf-yang-schema-mount module) is used in its definition. This extension can only show up as a substatement of container and list statements, so don't try to sneak it anywhere else 🙈

The argument of the mount-point extension statement is a YANG identifier that gives the mount point a label. A module MAY contain multiple mount-point extension statements that have the same argument. Iconic, right? 💜

It's therefore up to the designer of the parent schema to decide where mount points go. 👑 A mount point can also be made conditional by putting if-feature and/or when as substatements of the container or list statement that represents the mount point. Main character decisions, periodt ✨

The mount-point extension statement MUST NOT be used in a YANG version 1 module [RFC6020]. If it's used in a YANG version 1 module, it would not be possible to invoke mounted RPC operations and receive mounted notifications. See Section 5 for the details. Note, however, that modules written in any YANG version, including version 1, can be mounted under a mount point. Lowkey a plot twist 💀

Note that the mount-point extension statement does not define a new data node. Just a label, no new node, no cap 🍓

3.2. Data Model 🎀

This document defines the YANG 1.1 module [RFC7950] ietf-yang-schema-mount, and it has the following structure:

   module: ietf-yang-schema-mount
     +--ro schema-mounts
        +--ro namespace* [prefix]
        |  +--ro prefix    yang:yang-identifier
        |  +--ro uri?      inet:uri
        +--ro mount-point* [module label]
           +--ro module                 yang:yang-identifier
           +--ro label                  yang:yang-identifier
           +--ro config?                boolean
           +--ro (schema-ref)
              +--:(inline)
              |  +--ro inline!
              +--:(shared-schema)
                 +--ro shared-schema!
                    +--ro parent-reference*   yang:xpath1.0

3.3. Specification of the Mounted Schema 🦋

okay this part is so good. The mounted schemas for all mount points in the parent schema are determined from state data in the /schema-mounts container. 🫶

Generally, the modules mounted under a mount point have no relation to the modules in the parent schema. Like, if a module is mounted, it may or may not be present in the parent schema, and if it is present, its data will generally have no relationship to the parent's data. 🙃 Exceptions are possible, but they need to be defined in the model itself. For example, [RFC8530] defines a mechanism to bind interfaces to mounted logical network elements. Ate that for them 🔥

The /schema-mounts container has the mount-point list as one of its children. Every entry in this list refers (through its key) to a mount point and specifies the mounted schema. ✨

If a mount point is defined in the parent schema but does not have an entry in the mount-point list, then the mounted schema is void, i.e., instances of that mount point MUST NOT contain any data except those that are defined in the parent schema. Empty vibes only 🫧

If multiple mount points with the same name are defined in the same module (either directly, or because the mount point is defined in a grouping and that grouping is used multiple times), then the corresponding mount-point entry applies equally to all such mount points. Same name, same rules, no drama 🌈

The config property of mounted schema nodes gets overridden, and all nodes in the mounted schema are read-only (config false) if at least one of the following conditions is satisfied for a mount point:

  • The mount point is itself defined as config false.
  • The config leaf in the corresponding entry of the mount-point list is set to false.

An entry of the mount-point list can specify the mounted schema in two different ways: inline or shared-schema. Two options, pick your fighter 💖

The mounted schema is determined at run time. Every instance of the mount point that exists in the operational state MUST contain a copy of YANG library data that defines the mounted schema in exactly the same way as a top-level schema. A client is expected to retrieve this data from the instance tree. In the inline case, instances of the same mount point MAY use different mounted schemas, whereas in the shared-schema case, all instances MUST use the same mounted schema. This means that in the shared-schema case, all instances of the same mount point MUST have the same YANG library content identifier. In the inline case, if two instances have the same YANG library content identifier, it is not guaranteed that the YANG library contents are equal for those instances. Read that twice, it's a little bit plot-twisty 👀

Examples of inline and shared-schema can be found in Appendix A.2 and Appendix A.3, respectively. Go peek at those, they're cute 🧚

3.4. Multiple Levels of Schema Mount 🌸

YANG modules in a mounted schema MAY again contain mount points, and other schemas can be mounted under those. So yes, it's possible to build data models with an arbitrary number of mounted schemas. Infinite layers, ngl that's iconic ✨ A schema for a mount point contained in a mounted module can be specified by implementing the ietf-yang-library and ietf-yang-schema-mount modules in the mounted schema and specifying the schemas in exactly the same way as the top-level schema. 💅

4. Referring to Data Nodes in the Parent Schema 👑

okay bestie, the fundamental design principle of schema mount is that the mounted schema works exactly like a top-level schema. It's confined to the "mount jail" 🙈 This means that all paths in the mounted schema (in leafrefs, instance-identifiers, XPath [XPATH] expressions, and target nodes of augment statements) are interpreted with the mount point as the root node. So YANG modules of the mounted schema, plus the corresponding instance data, cannot refer to schema nodes or instance data outside the "mount jail." Strict but make it fashion 💖

However, this restriction is sometimes too severe. A typical example is network instances (NIs) [RFC8529], where each NI has its own routing engine but the list of interfaces is global and shared by all NIs. If we want to model this organization with the NI schema mounted using schema mount, the overall schema tree would look schematically like this:

   +--rw interfaces
   |  +--rw interface* [name]
   |     ...
   +--rw network-instances
      +--rw network-instance* [name]
         +--rw name
         +--mp root
            +--rw routing
               ...

So the root container is the mount point for the NI schema. Routing configuration inside an NI often needs to refer to interfaces (at least the ones assigned to that NI), which is impossible unless such a reference can point to a node in the parent schema (interface name). Relatable struggle 😭

Therefore, schema mount also allows for such references. For every mount point in the shared-schema case, it's possible to specify a leaf-list named parent-reference that contains zero or more XPath 1.0 expressions. Each expression is evaluated with the node in the parent data tree where the mount point is defined as the context node. The result of this evaluation MUST be a node-set (see the description of the parent-reference node for a complete definition of the evaluation context). For the purposes of evaluating XPath expressions within the mounted data tree, the union of all such node-sets is added to the accessible data tree. Borrowing from the parent, but make it organized 🧚

It's worth emphasizing that the nodes specified in the parent-reference leaf-list are available in the mounted schema only for XPath evaluations. In particular, they cannot be accessed in the mounted schema via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. So look, but don't touch 🙈

5. RPC Operations and Notifications 📞

if a mounted YANG module defines an RPC operation, clients can invoke it as if it were defined as an action for the corresponding mount point; see Section 7.15 of [RFC7950]. An example of this is given in Appendix A.4. Cute callback energy 🦋

Similarly, if the server emits a notification defined at the top level of any mounted module, it MUST be represented as if the notification was connected to the mount point; see Section 7.16 of [RFC7950]. ✨

Heads up, bestie! Inline actions and notifications will not work when they are contained within a list node without a key statement (see Sections 7.15 and 7.16 of [RFC7950]). So, to be useful, mount points that contain modules with RPCs, actions, and notifications SHOULD NOT have any ancestor node that is a list node without a key statement. This requirement applies to the definition of modules using the mount-point extension statement. 🚨

6. NMDA Considerations 🌈

the schema mount solution in this document is designed to work with both servers that implement the NMDA [RFC8342] and older servers that don't implement the NMDA. Inclusive and iconic 🫶

Specifically, a server that doesn't support the NMDA MAY implement revision 2016-06-21 of ietf-yang-library [RFC7895] under a mount point. A server that supports the NMDA MUST implement at least revision 2019-01-04 of ietf-yang-library [RFC8525] under a mount point. Revision check, bestie 💅

7. Interaction with NACM 🔐

if the Network Configuration Access Control Model (NACM) [RFC8341] is implemented on a server, it's used to control access to nodes defined by the mounted schema, the same way it does for nodes defined by the top-level schema. Same security energy everywhere 💖

For example, suppose the module ietf-interfaces is mounted in the root container in the logical-network-element list defined in [RFC8530]. Then the following NACM path can be used to control access to the interfaces container (where the character \ is used wherever a line break has been inserted for formatting reasons):

   <path xmlns:lne=
           "urn:ietf:params:xml:ns:yang:ietf-logical-network-element"
         xmlns:if="urn:ietf:params:xml:ns:yang:ietf-interfaces">
     /lne:logical-network-elements\
       /lne:logical-network-element/lne:root/if:interfaces
   </path>

8. Implementation Notes ✨

okay so managing devices that use schema mount can be done in different ways 💅 but there are two setups that are literally the typical ones 🫶

  • shared management 🦋: instance data from both the parent and mounted schemas is accessible inside the same management session. one session sees everything, no cap 💖
  • split management 🌸: one (master) management session can access instance data from both the parent and mounted schemas. then there's ALSO an extra session that can only see the mounted data tree, and that session exists for every instance of the mount point 🧚

9. Schema Mount YANG Module 🎀

this module references [RFC6991] and [RFC7950] 🍓

   <CODE BEGINS> file "ietf-yang-schema-mount@2019-01-14.yang"

   module ietf-yang-schema-mount {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount";
     prefix yangmnt;

     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991: Common YANG Data Types";
     }

     import ietf-yang-types {
       prefix yang;
       reference
         "RFC 6991: Common YANG Data Types";
     }

     organization
       "IETF NETMOD (NETCONF Data Modeling Language) Working Group";

     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
        WG List:  <mailto:netmod@ietf.org>

        Editor:   Martin Bjorklund
                  <mailto:mbj@tail-f.com>

        Editor:   Ladislav Lhotka
                  <mailto:lhotka@nic.cz>";

     description
       "This module defines a YANG extension statement that can be used
        to incorporate data models defined in other YANG modules in a
        module.  It also defines operational state data that specify the
        overall structure of the data model.

        The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
        NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
        'MAY', and 'OPTIONAL' in this document are to be interpreted as
        described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
        they appear in all capitals, as shown here.

        Copyright (c) 2019 IETF Trust and the persons identified as
        authors of the code.  All rights reserved.

        Redistribution and use in source and binary forms, with or
        without modification, is permitted pursuant to, and subject to
        the license terms contained in, the Simplified BSD License set
        forth in Section 4.c of the IETF Trust's Legal Provisions
        Relating to IETF Documents
        (https://trustee.ietf.org/license-info).

        This version of this YANG module is part of RFC 8528;
        see the RFC itself for full legal notices.";

     revision 2019-01-14 {
       description
         "Initial revision.";
       reference
         "RFC 8528: YANG Schema Mount";
     }

     /*
      * Extensions
      */

     extension mount-point {
       argument label;
       description
         "The argument 'label' is a YANG identifier, i.e., it is of the
          type 'yang:yang-identifier'.

          The 'mount-point' statement MUST NOT be used in a YANG
          version 1 module, neither explicitly nor via a 'uses'
          statement.

          The 'mount-point' statement MAY be present as a substatement
          of 'container' and 'list' and MUST NOT be present elsewhere.
          There MUST NOT be more than one 'mount-point' statement in a
          given 'container' or 'list' statement.

          If a mount point is defined within a grouping, its label is
          bound to the module where the grouping is used.

          A mount point defines a place in the node hierarchy where
          other data models may be attached.  A server that implements a
          module with a mount point populates the
          '/schema-mounts/mount-point' list with detailed information on
          which data models are mounted at each mount point.

          Note that the 'mount-point' statement does not define a new
          data node.";
     }

     /*
      * State data nodes
      */

     container schema-mounts {
       config false;
       description
         "Contains information about the structure of the overall
          mounted data model implemented in the server.";
       list namespace {
         key "prefix";
         description
           "This list provides a mapping of namespace prefixes that are
            used in XPath expressions of 'parent-reference' leafs to the
            corresponding namespace URI references.";
         leaf prefix {
           type yang:yang-identifier;
           description
             "Namespace prefix.";
         }
         leaf uri {
           type inet:uri;
           description
             "Namespace URI reference.";
         }
       }
       list mount-point {
         key "module label";
         description
           "Each entry of this list specifies a schema for a particular
            mount point.

            Each mount point MUST be defined using the 'mount-point'
            extension in one of the modules listed in the server's
            YANG library instance with conformance type 'implement'.";
         leaf module {
           type yang:yang-identifier;
           description
             "Name of a module containing the mount point.";
         }
         leaf label {
           type yang:yang-identifier;
           description
             "Label of the mount point defined using the 'mount-point'
              extension.";
         }
         leaf config {
           type boolean;
           default "true";
           description
             "If this leaf is set to 'false', then all data nodes in the
              mounted schema are read-only ('config false'), regardless
              of their 'config' property.";
         }
         choice schema-ref {
           mandatory true;
           description
             "Alternatives for specifying the schema.";
           container inline {
             presence
               "A complete self-contained schema is mounted at the
                mount point.";
             description
               "This node indicates that the server has mounted at least
                the module 'ietf-yang-library' at the mount point, and
                its instantiation provides the information about the
                mounted schema.

                Different instances of the mount point may have
                different schemas mounted.";
           }
           container shared-schema {
             presence
               "The mounted schema together with the 'parent-reference'
                make up the schema for this mount point.";

             description
               "This node indicates that the server has mounted at least
                the module 'ietf-yang-library' at the mount point, and
                its instantiation provides the information about the
                mounted schema.  When XPath expressions in the mounted
                schema are evaluated, the 'parent-reference' leaf-list
                is taken into account.

                Different instances of the mount point MUST have the
                same schema mounted.";
             leaf-list parent-reference {
               type yang:xpath1.0;
               description
                 "Entries of this leaf-list are XPath 1.0 expressions
                  that are evaluated in the following context:

                  - The context node is the node in the parent data tree
                    where the mount-point is defined.

                  - The accessible tree is the parent data tree
                    *without* any nodes defined in modules that are
                    mounted inside the parent schema.

                  - The context position and context size are both equal
                    to 1.

                  - The set of variable bindings is empty.

                  - The function library is the core function library
                    defined in the W3C XPath 1.0 document
                    (http://www.w3.org/TR/1999/REC-xpath-19991116) and
                    the functions defined in Section 10 of RFC 7950.

                  - The set of namespace declarations is defined by the
                    'namespace' list under 'schema-mounts'.

                  Each XPath expression MUST evaluate to a node-set
                  (possibly empty).  For the purposes of evaluating
                  XPath expressions whose context nodes are defined in
                  the mounted schema, the union of all these node-sets
                  together with ancestor nodes are added to the
                  accessible data tree.

                  Note that in the case 'ietf-yang-schema-mount' is
                  itself mounted, a 'parent-reference' in the mounted
                  module may refer to nodes that were brought into the
                  accessible tree through a 'parent-reference' in the
                  parent schema.";

             }
           }
         }
       }
     }
   }

   <CODE ENDS>

10. IANA Considerations 🌈

this document registers a URI in the "IETF XML Registry" [RFC3688] 📝

        URI: urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
        Registrant Contact: The IESG.
        XML: N/A, the requested URI is an XML namespace.

this document also registers a YANG module in the "YANG Module Names" registry [RFC6020] 🧾

     name:        ietf-yang-schema-mount
     namespace:   urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount
     prefix:      yangmnt
     reference:   RFC 8528

11. Security Considerations 💀

okay this section is serious bestie 😭 the YANG module in this document defines a schema for data that's meant to be accessed through network management protocols like NETCONF [RFC6241] or RESTCONF [RFC8040]. the lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. the lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446] 🔐

the Network Configuration Access Control Model (NACM) [RFC8341] gives you the tools to restrict particular NETCONF or RESTCONF users to a preconfigured subset of all the available protocol operations and content. main character access control 👑

some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. so it is really important to control read access (for example, via get, get-config, or notification) to these data nodes. these are the subtrees and data nodes and their sensitivity/vulnerability:

  • /schema-mounts 🙈: the schema defined by this state data gives detailed information about a server implementation, which may help an attacker identify the server capabilities and server implementations with known bugs. server vulnerabilities may be specific to particular modules included in the schema, module revisions, module features, or even module deviations. for example, if a particular operation on a particular data node is known to cause a server to crash or significantly degrade device performance, then the schema information will help an attacker identify server implementations with such a defect, in order to launch a denial-of-service attack on the device. yikes 💀

it is important to take into account the security considerations for all nodes in the mounted schemas, and to control access to these nodes by using the mechanism described in Section 7 🫶

care must be taken when the parent-reference XPath expressions are constructed. the result of evaluating these expressions gets added to the accessible tree for any XPath expression found in the mounted schema, so be careful bestie 🚨

12. References 📚

12.1. Normative References

Okay, bestie, these are the docs this RFC leans on for its core stuff 📚 Every one of them is normative, so you genuinely need them to get the full picture 🫶

12.2. Informative References

Now the cozy extras 🧸 These ones are just helpful background reading, not required to implement anything 🌸

  • [DEVICE-YANG] Lindem, A., Ed., Berger, L., Ed., Bogdanovic, D., and C. Hopps, "Network Device YANG Logical Organization", Work in Progress, draft-ietf-rtgwg-device-model-02, March 2017.
  • [IS-IS-YANG] Litkowski, S., Yeung, D., Lindem, A., Zhang, J., and L. Lhotka, "YANG Data Model for IS-IS protocol", Work in Progress, draft-ietf-isis-yang-isis-cfg-34, January 2019.
  • [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.
  • [RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.
  • [RFC8529] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, "YANG Data Model for Network Instances", RFC 8529, DOI 10.17487/RFC8529, March 2019, <https://www.rfc-editor.org/info/rfc8529>.
  • [RFC8530] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, "YANG Model for Logical Network Elements", RFC 8530, DOI 10.17487/RFC8530, March 2019, <https://www.rfc-editor.org/info/rfc8530>.
  • [YANG-MOUNT] Clemm, A., Voit, E., and J. Medved, "Mounting YANG-Defined Information from Remote Datastores", Work in Progress, draft-clemm-netmod-mount-06, March 2017.

Appendix A. Example: Device Model with LNEs and NIs ✨

This non-normative example is a little demo 🎀 of how you'd build the device model from Section 2 of [DEVICE-YANG], using both logical network elements (LNEs) and network instances (NIs) 💅

Heads up, the character \ shows up wherever a line break got added just so things fit on the page 🙈

A.1. Physical Device

Here's the YANG library content that may describe the data model for the physical device, assuming the server supports the NMDA 🦋

   {
      "ietf-yang-library:yang-library": {
        "content-id": "14e2ab5dc325f6d86f743e8d3ade233f1a61a899",
        "module-set": [
          {
            "name": "physical-device-modules",
            "module": [
              {
                "name": "ietf-datastores",
                "revision": "2018-02-14",
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-datastores"
              },
              {
                "name": "iana-if-type",
                "revision": "2015-06-12",
                "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type"
              },
              {
                "name": "ietf-interfaces",
                "revision": "2018-02-20",
                "feature": ["arbitrary-names", "pre-provisioning" ],
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-interfaces"
              },
              {
                "name": "ietf-ip",
                "revision": "2018-02-22",
                "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip"
              },
              {
                "name": "ietf-logical-network-element",
                "revision": "2018-03-20",
                "feature": [ "bind-lne-name" ],
                "namespace":
                  "urn:ietf:params:xml:ns:yang:\
                  ietf-logical-network-element"
              },
              {
                "name": "ietf-yang-library",
                "revision": "2019-01-04",
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-yang-library"
              },
              {
                "name": "ietf-yang-schema-mount",
                "revision": "2019-01-14",
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount"
              }
            ],
            "import-only-module": [
              {
                "name": "ietf-inet-types",
                "revision": "2013-07-15",
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-inet-types"
              },
              {
                "name": "ietf-yang-types",
                "revision": "2013-07-15",
                "namespace":
                  "urn:ietf:params:xml:ns:yang:ietf-yang-types"
              }
            ]
          }
        ],
        "schema": [
          {
            "name": "physical-device-schema",
            "module-set": [ "physical-device-modules" ]
          }
        ],
        "datastore": [
          {
            "name": "ietf-datastores:running",
            "schema": "physical-device-schema"
          },
          {
            "name": "ietf-datastores:operational",
            "schema": "physical-device-schema"
          }

        ]
      }
   }

A.2. Logical Network Elements 🧚

okay so each LNE can have its own data model, and that model gets figured out at run time 💅 which is exactly why the "inline" method is the move. so the schema-mounts data looks like this:

{
  "ietf-yang-schema-mount:schema-mounts": {
    "mount-point": [
      {
        "module": "ietf-logical-network-element",
        "label": "root",
        "inline": {}
      }
    ]
  }
}

next up, the host device's admin has to set up an entry for each LNE instance, like:

{
  "ietf-interfaces:interfaces": {
    "interface": [
      {
        "name": "eth0",
        "type": "iana-if-type:ethernetCsmacd",
        "enabled": true,
        "ietf-logical-network-element:bind-lne-name": "eth0"
      }
    ]
  },
  "ietf-logical-network-element:logical-network-elements": {
    "logical-network-element": [
      {
        "name": "lne-1",
        "managed": true,
        "description": "LNE with NIs",
        "root": {
          ...
        }
      }
      ...
    ]

  }
}

and then you also place the necessary state data as the contents of the "root" instance 🫶 which should include at least:

  • YANG library data specifying the LNE's data model, for example, assuming the server does not implement the NMDA:
{
  "ietf-yang-library:modules-state": {
    "module-set-id": "9358e11874068c8be06562089e94a89e0a392019",
    "module": [
      {
        "name": "iana-if-type",
        "revision": "2014-05-08",
        "namespace": "urn:ietf:params:xml:ns:yang:iana-if-type",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-inet-types",
        "revision": "2013-07-15",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types",
        "conformance-type": "import"
      },
      {
        "name": "ietf-interfaces",
        "revision": "2014-05-08",
        "feature": [
          "arbitrary-names",
          "pre-provisioning"
        ],
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-interfaces",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-ip",
        "revision": "2014-06-16",
        "feature": [
          "ipv6-privacy-autoconf"
        ],
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-network-instance",
        "revision": "2018-03-20",
        "feature": [

          "bind-network-instance-name"
        ],
        "namespace":
          "urn:ietf:params:xml:ns:yang:ietf-network-instance",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-yang-library",
        "revision": "2016-06-21",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-library",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-yang-schema-mount",
        "revision": "2019-01-14",
        "namespace":
          "urn:ietf:params:xml:ns:yang:ietf-yang-schema-mount",
        "conformance-type": "implement"
      },
      {
        "name": "ietf-yang-types",
        "revision": "2013-07-15",
        "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types",
        "conformance-type": "import"
      }
    ]
  }
}
  • state data for interfaces assigned to the LNE instance (that effectively become system-controlled interfaces for the LNE), for example:
{
  "ietf-interfaces:interfaces": {
    "interface": [
      {
        "name": "eth0",
        "type": "iana-if-type:ethernetCsmacd",
        "oper-status": "up",
        "statistics": {
          "discontinuity-time": "2016-12-16T17:11:27+02:00"
        },
        "ietf-ip:ipv6": {
          "address": [
            {
              "ip": "fe80::42a8:f0ff:fea8:24fe",
              "origin": "link-layer",
              "prefix-length": 64
            }
          ]
        }
      }
    ]
  }
}

A.3. Network Instances 🌸

assuming network instances all share the same data model, you can mount it using the "shared-schema" method like so:

{
  "ietf-yang-schema-mount:schema-mounts": {
    "namespace": [
      {
          "prefix": "if",
          "uri": "urn:ietf:params:xml:ns:yang:ietf-interfaces"
      },
      {
          "prefix": "ni",
          "uri": "urn:ietf:params:xml:ns:yang:ietf-network-instance"
      }
    ],
    "mount-point": [
      {
        "module": "ietf-network-instance",
        "label": "root",
          "shared-schema": {
            "parent-reference": [
              "/if:interfaces/if:interface[\
              ni:bind-network-instance-name = current()/../ni:name]"
            ]
          }
      }
    ]
  }
}
⚠️ note also that the "ietf-interfaces" module shows up in the "parent-reference" leaf-list for the mounted NI schema. this means references to LNE interfaces, like "outgoing-interface" in static routes, are valid even though "ietf-interfaces" isn't part of the NI schema. iykyk 🙈

A.4. Invoking an RPC Operation 💖

say the mounted NI data model also implements the "ietf-isis" module [IS-IS-YANG]. an RPC operation defined in this module, like "clear-adjacency", can be invoked by a client session of an LNE's RESTCONF server as an action tied to the mount point of a particular network instance. the request URI looks like this (all on one line):

  POST /restconf/data/ietf-network-instance:network-instances/
      network-instance=rtrA/root/ietf-isis:clear-adjacency HTTP/1.1

Contributors 🎀

the idea of having some way to combine schemas from different YANG modules into one has been proposed independently by others, and these people are literally the reason we have it ✨

  • Authors of [YANG-MOUNT]:
    • Lou Berger, LabN Consulting, L.L.C., <lberger@labn.net>
    • Alexander Clemm, Huawei, <alexander.clemm@huawei.com>
    • Christian Hopps, Deutsche Telekom, <chopps@chopps.org>
  • Jan Medved, Cisco, <jmedved@cisco.com>
  • Eric Voit, Cisco, <evoit@cisco.com>

Authors' Addresses 🦋

Martin Bjorklund
Tail-f Systems

Email: mbj@tail-f.com


Ladislav Lhotka
CZ.NIC

Email: lhotka@nic.cz
📦 where this page comes from