Tech-invite3GPPspecsSIPRFCs
898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100

in Index   Prev   Next

RFC 6095

Extending YANG with Language Abstractions

Pages: 75
Experimental
Part 1 of 4 – Pages 1 to 14
None   None   Next

Top   ToC   RFC6095 - Page 1
Internet Engineering Task Force (IETF)                       B. Linowski
Request for Comments: 6095                    TCS/Nokia Siemens Networks
Category: Experimental                                          M. Ersue
ISSN: 2070-1721                                   Nokia Siemens Networks
                                                               S. Kuryla
                                                    360 Treasury Systems
                                                              March 2011


               Extending YANG with Language Abstractions

Abstract

YANG -- the Network Configuration Protocol (NETCONF) Data Modeling Language -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This memo suggests enhancing YANG with supplementary modeling features and language abstractions with the aim to improve the model extensibility and reuse. Status of This Memo This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation. This document defines an Experimental Protocol for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc6095.
Top   ToC   RFC6095 - Page 2
Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Modeling Improvements with Language Abstractions . . . . . 5 1.4. Design Approach . . . . . . . . . . . . . . . . . . . . . 6 1.5. Modeling Resource Models with YANG . . . . . . . . . . . . 6 1.5.1. Example of a Physical Network Resource Model . . . . . 6 1.5.2. Modeling Entity MIB Entries as Physical Resources . . 12 2. Complex Types . . . . . . . . . . . . . . . . . . . . . . . . 15 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2. complex-type Extension Statement . . . . . . . . . . . . . 15 2.3. instance Extension Statement . . . . . . . . . . . . . . . 17 2.4. instance-list Extension Statement . . . . . . . . . . . . 18 2.5. extends Extension Statement . . . . . . . . . . . . . . . 19 2.6. abstract Extension Statement . . . . . . . . . . . . . . . 19 2.7. XML Encoding Rules . . . . . . . . . . . . . . . . . . . . 20 2.8. Type Encoding Rules . . . . . . . . . . . . . . . . . . . 20 2.9. Extension and Feature Definition Module . . . . . . . . . 21 2.10. Example Model for Complex Types . . . . . . . . . . . . . 24 2.11. NETCONF Payload Example . . . . . . . . . . . . . . . . . 25 2.12. Update Rules for Modules Using Complex Types . . . . . . . 26 2.13. Using Complex Types . . . . . . . . . . . . . . . . . . . 26 2.13.1. Overriding Complex Type Data Nodes . . . . . . . . . . 26 2.13.2. Augmenting Complex Types . . . . . . . . . . . . . . . 27 2.13.3. Controlling the Use of Complex Types . . . . . . . . . 28 3. Typed Instance Identifier . . . . . . . . . . . . . . . . . . 29 3.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 29 3.2. instance-type Extension Statement . . . . . . . . . . . . 29 3.3. Typed Instance Identifier Example . . . . . . . . . . . . 30 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 5. Security Considerations . . . . . . . . . . . . . . . . . . . 31
Top   ToC   RFC6095 - Page 3
   6.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 32
     7.1.  Normative References . . . . . . . . . . . . . . . . . . . 32
     7.2.  Informative References . . . . . . . . . . . . . . . . . . 32
   Appendix A.  YANG Modules for Physical Network Resource Model
                and Hardware Entities Model . . . . . . . . . . . . . 34
   Appendix B.  Example YANG Module for the IPFIX/PSAMP Model . . . . 40
     B.1.  Modeling Improvements for the IPFIX/PSAMP Model with
           Complex Types and Typed Instance Identifiers . . . . . . . 40
     B.2.  IPFIX/PSAMP Model with Complex Types and Typed
           Instance Identifiers . . . . . . . . . . . . . . . . . . . 41

1. Introduction

YANG -- the NETCONF Data Modeling Language [RFC6020] -- supports modeling of a tree of data elements that represent the configuration and runtime status of a particular network element managed via NETCONF. This document defines extensions for the modeling language YANG as new language statements, which introduce language abstractions to improve the model extensibility and reuse. The document reports from modeling experience in the telecommunication industry and gives model examples from an actual network management system to highlight the value of proposed language extensions, especially class inheritance and recursiveness. The language extensions defined in this document have been implemented with two open source tools. These tools have been used to validate the model examples through the document. If this experimental specification results in successful usage, it is possible that the language extensions defined herein could be updated to incorporate implementation and deployment experience, then pursued on the Standards Track, possibly as part of a future version of YANG.

1.1. Key Words

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].

1.2. Motivation

Following are non-exhaustive motivation examples highlighting usage scenarios for language abstractions. o Many systems today have a Management Information Base (MIB) that in effect is organized as a tree build of recursively nested container nodes. For example, the physical resources in the ENTITY-MIB conceptually form a containment tree. The index
Top   ToC   RFC6095 - Page 4
      entPhysicalContainedIn points to the containing entity in a flat
      list.  The ability to represent nested, recursive data structures
      of arbitrary depth would enable the representation of the primary
      containment hierarchy of physical entities as a node tree in the
      server MIB and in the NETCONF payload.

   o  A manager scanning the network in order to update the state of an
      inventory management system might be only interested in data
      structures that represent a specific type of hardware.  Such a
      manager would then look for entities that are of this specific
      type, including those that are an extension or specialization of
      this type.  To support this use case, it is helpful to bear the
      corresponding type information within the data structures, which
      describe the network element hardware.

   o  A system that is managing network elements is concerned, e.g.,
      with managed objects of type "plug-in modules" that have a name, a
      version, and an activation state.  In this context, it is useful
      to define the "plug-in module" as a concept that is supposed to be
      further detailed and extended by additional concrete model
      elements.  In order to realize such a system, it is worthwhile to
      model abstract entities, which enable reuse and ease concrete
      refinements of that abstract entity in a second step.

   o  As particular network elements have specific types of components
      that need to be managed (OS images, plug-in modules, equipment,
      etc.), it should be possible to define concrete types, which
      describe the managed object precisely.  By using type-safe
      extensions of basic concepts, a system in the manager role can
      safely and explicitly determine that e.g., the "equipment" is
      actually of type "network card".

   o  Currently, different SDOs are working on the harmonization of
      their management information models.  Often, a model mapping or
      transformation between systems becomes necessary.  The
      harmonization of the models is done e.g., by mapping of the two
      models on the object level or integrating an object hierarchy into
      an existing information model.  On the one hand, extending YANG
      with language abstractions can simplify the adoption of IETF
      resource models by other SDOs and facilitate the alignment with
      other SDOs' resource models (e.g., TM Forum SID [SID_V8]).  On the
      other hand, the proposed YANG extensions can enable the
      utilization of the YANG modeling language in other SDOs, which
      usually model complex management systems in a top-down manner and
      use high-level language features frequently.
Top   ToC   RFC6095 - Page 5
   This memo specifies additional modeling features for the YANG
   language in the area of structured model abstractions, typed
   references, as well as recursive data structures, and it discusses
   how these new features can improve the modeling capabilities of YANG.

   Section 1.5.1 contains a physical resource model that deals with some
   of the modeling challenges illustrated above.  Section 1.5.2 gives an
   example that uses the base classes defined in the physical resource
   model and derives a model for physical entities defined in the Entity
   MIB.

1.3. Modeling Improvements with Language Abstractions

As an enhancement to YANG 1.0, complex types and typed instance identifiers provide different technical improvements on the modeling level: o In case the model of a system that should be managed with NETCONF makes use of inheritance, complex types enable an almost one-to- one mapping between the classes in the original model and the YANG module. o Typed instance identifiers allow representing associations between the concepts in a type-safe way to prevent type errors caused by referring to data nodes of incompatible types. This avoids referring to a particular location in the MIB. Referring to a particular location in the MIB is not mandated by the domain model. o Complex types allow defining complete, self-contained type definitions. It is not necessary to explicitly add a key statement to lists, which use a grouping that defines the data nodes. o Complex types simplify concept refinement by extending a base complex type and make it superfluous to represent concept refinements with workarounds such as huge choice-statements with complex branches. o Abstract complex types ensure correct usage of abstract concepts by enforcing the refinement of a common set of properties before instantiation. o Complex types allow defining recursive structures. This enables representing complex structures of arbitrary depth by nesting instances of basic complex types that may contain themselves.
Top   ToC   RFC6095 - Page 6
   o  Complex types avoid introducing metadata types (e.g., type code
      enumerations) and metadata leafs (e.g., leafs containing a type
      code) to indicate which concrete type of object is actually
      represented by a generic container in the MIB.  This also avoids
      explicitly ruling out illegal use of subtype-specific properties
      in generic containers.

   o  Complex type instances include the type information in the NETCONF
      payload.  This allows determining the actual type of an instance
      during the NETCONF payload parsing and avoids the use in the model
      of additional leafs, which provide the type information as
      content.

   o  Complex types may be declared explicitly as optional features,
      which is not possible when the actual type of an entity
      represented by a generic container is indicated with a type code
      enumeration.

   Appendix B, "Example YANG Module for the IPFIX/PSAMP Model", lists
   technical improvements for modeling with complex types and typed
   instance identifiers and exemplifies the usage of the proposed YANG
   extensions based on the IP Flow Information Export (IPFIX) / Packet
   Sampling (PSAMP) configuration model in [IPFIXCONF].

1.4. Design Approach

The proposed additional features for YANG in this memo are designed to reuse existing YANG statements whenever possible. Additional semantics is expressed by an extension that is supposed to be used as a substatement of an existing statement. The proposed features don't change the semantics of models that is valid with respect to the YANG specification [RFC6020].

1.5. Modeling Resource Models with YANG

1.5.1. Example of a Physical Network Resource Model

The diagram below depicts a portion of an information model for manageable network resources used in an actual network management system. Note: The referenced model (UDM, Unified Data Model) is based on key resource modeling concepts from [SID_V8] and is compliant with selected parts of SID Resource Abstract Business Entities domain [UDM].
Top   ToC   RFC6095 - Page 7
   The class diagram in Figure 1 and the corresponding YANG module
   excerpt focus on basic resource ("Resource" and the distinction
   between logical and physical resources) and hardware abstractions
   ("Hardware", "Equipment", and "EquipmentHolder").  Class attributes
   were omitted to achieve decent readability.
Top   ToC   RFC6095 - Page 8
+--------+
|Resource|
+--------+
 /\   /\
 --   --
 |    |
 |  +---------------+
 |  |LogicalResource|
 |  +---------------+
 |
 | +--------+
 | |Physical|      +-----------+
 '-|Resource|<|-+-|PhysicalLink|
   +---- ---+   | +------------+
                |     |0..* physicalLink
                |     |                                       equipment
                |     |                                       Holder
                |     |                                       0..*
                |     |                                       +-------+
                |     |0..* hardware                          |       |
                | +--------+     +---------------+     +---------+    |
                '-|Hardware|<|-+-|ManagedHardware|<|-+-|Equipment|<>--+
                  +--------+   | +---------------+   | | Holder  |0..1
                      <>       |                     | +---------+
                  0..1|        |                     |   <>
                      |        |                     |   |0..* equipment
                      |        |                     |   |     Holder
                      |        |                     |   |
                      |        |                     |   |0..* equipment
                      |        |                     |   |
                      |        |                     |   |    equipment
                      |        |                     |   |    0..*
                      |        |                     |   |    +-------+
                      |        |                     |   |    |       |
                      |        |                     | +---------+    |
                      |        |                     '-|Equipment|<>--+
                      |        |                       +---------+0..1
                      |        |                    compositeEquipment
                      |        |
                      |        | +-----------------+
                      |        '-|PhysicalConnector|----+0..* source
                      '----------+-----------------+    |     Physical
           physicalConnector 0..*           |           |     Connector
                                            |           |
                                            +-----------+
                                            0..* targetPhysicalConnector

                 Figure 1: Physical Network Resource Model
Top   ToC   RFC6095 - Page 9
   Since this model is an abstraction of network-element-specific MIB
   topologies, modeling it with YANG creates some challenges.  Some of
   these challenges and how they can be addressed with complex types are
   explained below:

   o  Modeling of abstract concepts: Classes like "Resource" represent
      concepts that primarily serve as a base class for derived classes.
      With complex types, such an abstract concept could be represented
      by an abstract complex type (see "complex-type extension
      statement" and "abstract extension statement").

   o  Class Inheritance: Information models for complex management
      domains often use class inheritance to create specialized classes
      like "PhysicalConnector" from a more generic base class (here,
      "Hardware"), which itself might inherit from another base class
      ("PhysicalResource"), etc.  Complex types allow creating enhanced
      versions of an existing (abstract or concrete) base type via an
      extension (see "extends extension statement").

   o  Recursive containment: In order to specify containment
      hierarchies, models frequently contain different aggregation
      associations, in which the target (contained element) is either
      the containing class itself or a base class of the containing
      class.  In the model above, the recursive containment of
      "EquipmentHolder" is an example of such a relationship (see the
      description for the "complex-type EquipmentHolder" in the example
      model "udmcore" below).

   o  Complex types support such a containment by using a complex type
      (or one of its ancestor types) as the type of an instance or
      instance list that is part of its definition (see "instance(-list)
      extension statement").

   o  Reference relationships: A key requirement on large models for
      network domains with many related managed objects is the ability
      to define inter-class associations that represent essential
      relationships between instances of such a class.  For example, the
      relationship between "PhysicalLink" and "Hardware" tells which
      physical link is connecting which hardware resources.  It is
      important to notice that this kind of relationship does not
      mandate any particular location of the two connected hardware
      instances in any MIB module.  Such containment-agnostic
      relationships can be represented by a typed instance identifier
      that embodies one direction of such an association (see Section 3,
      "Typed Instance Identifier").
Top   ToC   RFC6095 - Page 10
   The YANG module excerpt below shows how the challenges listed above
   can be addressed by the Complex Types extension (module import prefix
   "ct:").  The complete YANG module for the physical resource model in
   Figure 1 can be found in Appendix A, "YANG Modules for Physical
   Network Resource Model and Hardware Entities Model".

   Note: The YANG extensions proposed in this document have been
   implemented as the open source tools "Pyang Extension for Complex
   Types" [Pyang-ct], [Pyang], and "Libsmi Extension for Complex Types"
   [Libsmi].  All model examples in the document have been validated
   with the tools Pyang-ct and Libsmi.

<CODE BEGINS>

module udmcore {

   namespace "http://example.com/udmcore";
   prefix "udm";

   import ietf-complex-types {prefix "ct"; }

        // Basic complex types...

   ct:complex-type PhysicalResource {
      ct:extends Resource;
        ct:abstract true;
        // ...
        leaf serialNumber {
         type string;
         description "'Manufacturer-allocated part number' as
           defined in SID, e.g., the part number of a fiber link
           cable.";
      }
   }


   ct:complex-type Hardware {
      ct:extends PhysicalResource;
        ct:abstract true;
        // ...
       leaf-list physicalLink {
          type instance-identifier {ct:instance-type PhysicalLink;}
       }
       ct:instance-list containedHardware {
       ct:instance-type Hardware;
}
       ct:instance-list physicalConnector {
       ct:instance-type PhysicalConnector;
Top   ToC   RFC6095 - Page 11
}
   }


   ct:complex-type PhysicalLink {
       ct:extends PhysicalResource;
       // ...
       leaf-list hardware {
          type instance-identifier {ct:instance-type Hardware;}
       }
   }


   ct:complex-type ManagedHardware {
      ct:extends Hardware;
        ct:abstract true;
        // ...
   }


   ct:complex-type PhysicalConnector {
      ct:extends Hardware;
        leaf location {type string;}
        // ...
      leaf-list sourcePhysicalConnector {
         type instance-identifier {ct:instance-type PhysicalConnector;}
      }
      leaf-list targetPhysicalConnector {
         type instance-identifier {ct:instance-type PhysicalConnector;}
      }
   }


   ct:complex-type Equipment {
      ct:extends ManagedHardware;
        // ...
      ct:instance-list equipment {
    ct:instance-type Equipment;
}
   }


   ct:complex-type EquipmentHolder {
      ct:extends ManagedHardware;
      description "In the SID V8 definition, this is a class based on
        the M.3100 specification.  A base class that represents physical
        objects that are both manageable as well as able to host,
        hold, or contain other physical objects.  Examples of physical
Top   ToC   RFC6095 - Page 12
        objects that can be represented by instances of this object
        class are Racks, Chassis, Cards, and Slots.
        A piece of equipment with the primary purpose of containing
        other equipment.";
        leaf vendorName {type string;}
        // ...
      ct:instance-list equipment {
       ct:instance-type Equipment;
        }
      ct:instance-list equipmentHolder {
       ct:instance-type EquipmentHolder;
       }
   }
   // ...
}

<CODE ENDS>

1.5.2. Modeling Entity MIB Entries as Physical Resources

The physical resource module described above can now be used to model physical entities as defined in the Entity MIB [RFC4133]. For each physical entity class listed in the "PhysicalClass" enumeration, a complex type is defined. Each of these complex types extends the most specific complex type already available in the physical resource module. For example, the type "HWModule" extends the complex type "Equipment" as a hardware module. Physical entity properties that should be included in a physical entity complex type are combined in a grouping, which is then used in each complex type definition of an entity. This approach has following benefits: o The definition of the complex types for hardware entities becomes compact as many of the features can be reused from the basic complex type definition. o Physical entities are modeled in a consistent manner as predefined concepts are extended. o Entity-MIB-specific attributes as well as vendor-specific attributes can be added without having to define separate extension data nodes.
Top   ToC   RFC6095 - Page 13
                            Module udmcore  :  Module hardware-entities
                                            :
                                equipment   :
                                Holder      :
                                0..*        :
                                +-------+   :
                                |       |   :
   +---------------+     +---------+    |   :
   |ManagedHardware|<|-+-|Equipment|<>--+   :
   +---------------+   | | Holder  |0..1    :     +-------+
                       | |         |<|---------+--|Chassis|
                       | +---------+        :  |  +-------+
                       |   <>               :  |
                       |   |0..* equipment  :  |  +---------+
                       |   |     Holder     :  '--|Container|
                       |   |                :     +---------+
                       |   |0..* equipment  :
                       |   |                :
                       |   |    equipment   :
                       |   |    0..*        :
                       |   |    +-------+   :
                       |   |    |       |   :
                       | +---------+    |   :
                       '-|Equipment|<>--+   :     +--------+
                         |         |<|---------+--|HWModule|
                         +---------+        :  |  +--------+
                      compositeEquipment    :  |
                                            :  |  +---------+
                                            :  |--|Backplane|
                                            :     +---------+

                     Figure 2: Hardware Entities Model

   Below is an excerpt of the corresponding YANG module using complex
   types to model hardware entities.  The complete YANG module for the
   Hardware Entities model in Figure 2 can be found in Appendix A, "YANG
   Modules for Physical Network Resource Model and Hardware Entities
   Model".
Top   ToC   RFC6095 - Page 14
<CODE BEGINS>

module hardware-entities {


   namespace "http://example.com/hardware-entities";
   prefix "hwe";

   import ietf-yang-types {prefix "yt";}
   import ietf-complex-types {prefix "ct";}
   import udmcore {prefix "uc";}


   grouping PhysicalEntityProperties {
      // ...
      leaf mfgDate {type yang:date-and-time; }
      leaf-list uris {type string; }
   }


   // Physical entities representing equipment

   ct:complex-type HWModule {
      ct:extends uc:Equipment;
      description "Complex type representing module entries
                   (entPhysicalClass = module(9)) in entPhysicalTable";
      uses PhysicalEntityProperties;
   }

   // ...

   // Physical entities representing equipment holders

   ct:complex-type Chassis {
      ct:extends uc:EquipmentHolder;
      description "Complex type representing chassis entries
                   (entPhysicalClass = chassis(3)) in entPhysicalTable";
      uses PhysicalEntityProperties;
   }

   // ...
}

<CODE ENDS>


(next page on part 2)

Next Section