tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6095

Experimental
Pages: 75
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: ~lang-code

Extending YANG with Language Abstractions

Part 1 of 4, p. 1 to 14
None       Next RFC Part

 


Top       ToC       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.

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       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       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       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       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       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       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       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       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       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       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       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       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 RFC Part