Network Working Group B. Linowski Internet-Draft TCS/Nokia Siemens Networks Intended status: Standards Track M. Ersue Expires: September 9, 2010 Nokia Siemens Networks S. Kuryla Jacobs University Bremen March 8, 2010 Extending YANG with Language Abstractions draft-linowski-netmod-yang-abstract-02 Abstract YANG - the 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 to enhance YANG with supplementary modeling features and language abstractions with the aim to improve the model extensibility and reuse. Status of This Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 9, 2010. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. Linowski, et al. Expires September 9, 2010 [Page 1] Internet-Draft YANG Language Abstractions March 2010 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 BSD License. Linowski, et al. Expires September 9, 2010 [Page 2] Internet-Draft YANG Language Abstractions March 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Modeling Improvements with Language Abstractions . . . . . 5 1.4. Design Approach . . . . . . . . . . . . . . . . . . . . . 6 2. Complex Types . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2. complex-type extension statement . . . . . . . . . . . . . 7 2.3. instance extension statement . . . . . . . . . . . . . . . 9 2.4. instance-list extension statement . . . . . . . . . . . . 9 2.5. extends extension statement . . . . . . . . . . . . . . . 10 2.6. abstract extension statement . . . . . . . . . . . . . . . 11 2.7. XML Encoding Rules . . . . . . . . . . . . . . . . . . . . 11 2.8. Type Encoding Rules . . . . . . . . . . . . . . . . . . . 11 2.9. Extension and Feature Definition Module . . . . . . . . . 12 2.10. Model Example . . . . . . . . . . . . . . . . . . . . . . 14 2.11. NETCONF Payload Example . . . . . . . . . . . . . . . . . 16 2.12. Update Rules for Modules Using Complex Types . . . . . . . 16 2.13. Using Complex Types . . . . . . . . . . . . . . . . . . . 17 2.13.1. Overriding Complex Types Data Nodes . . . . . . . . . 17 2.13.2. Augmenting Complex Types . . . . . . . . . . . . . . 18 2.13.3. Controlling the Use of Complex Types . . . . . . . . 19 3. Typed Instance Identifier . . . . . . . . . . . . . . . . . . 19 3.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 19 3.2. instance-type extension statement . . . . . . . . . . . . 20 3.3. Typed Instance Identifier Example . . . . . . . . . . . . 20 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 5. Security Considerations . . . . . . . . . . . . . . . . . . . 22 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 22 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 7.1. Normative References . . . . . . . . . . . . . . . . . . . 22 7.2. Informative References . . . . . . . . . . . . . . . . . . 23 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . . 23 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 23 B.1. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 23 B.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Appendix C. Example Model . . . . . . . . . . . . . . . . . . . . 24 C.1. Modeling Improvements for the IPFIX/PSAMP Model with Complex types and Typed instance identifiers . . . . . . . 24 C.2. IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers . . . . . . . . . . . . . . . . . . . 25 Linowski, et al. Expires September 9, 2010 [Page 3] Internet-Draft YANG Language Abstractions March 2010 1. Introduction YANG - the 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 document suggests to extend YANG with supplementary modeling features and language abstractions with the aim to improve the model extensibility and reuse. Comments are solicited and should be addressed to the working group's mailing list at netmod@ietf.org and/or the authors. 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 o Many systems today have a management information base 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 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 agent MIB and in the NETCONF payload. o An agent 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 network elements. Such an agent would then look for entities that are of this specific type. It becomes beneficial that reusable named types indicate the type of the concept the particular data structure represents. 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 module artifacts. In order to realize such a system, it is worth to model abstract entities to be able to define concrete refinements of that abstract entity. Linowski, et al. Expires September 9, 2010 [Page 4] Internet-Draft YANG Language Abstractions March 2010 o As particular network elements have specific type 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 explicitely 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 object level or integrating an object hierarchy into an existing information model. Extending YANG with modeling language abstractions can simplify the adoption of IETF resource models by other SDOs and facilitate the alignment with other SDO's resource models (e.g. TM Forum SID). The challenges listed above mainly address issues, where it is beneficial to use language abstractions for modeling. This memo proposes additional modeling features for the YANG language in the area of resource typing, referring to typed entities as well as typed, structured model extensions and discusses how these new features can improve the modeling capabilities of YANG. 1.3. Modeling Improvements with Language Abstractions Complex Types and Typed Instance Identifiers provide various technical improvements on modelling level: o In case the model of a system that should be managed with NETCONF is using inheritance (e.g. TM Forum SID), 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. This avoids to refer to a particular location in the MIB, which is not mandated by the domain model. o Complex types allow to define fully complete, self contained type definitions. It is not necessary to explicitly add a key statement to containers that otherwise only use a grouping, which provides 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 Linowski, et al. Expires September 9, 2010 [Page 5] Internet-Draft YANG Language Abstractions March 2010 complex branches. o Abstract complex types ensure correct usage of abstract concepts by enforcing the refinement of common set of properties before instantiation. o Complex types allow to define recursive structures. This enables to represent complex structures of arbitrary depth by nesting instances of basic complex types that may contain themselves. o Complex types avoid introducing meta-data types (e.g. type code enumerations) and meta-data 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 to explicitly rule out illegal use of sub-type specific properties in generic containers. o Complex type instances include the type information in the NETCONF payload, which allows to determine the actual type of an instance during the NETCONF payload parsing and avoids the use of additional leafs in the model providing 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 C: Example 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 IPFIX/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 then 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 are valid with respect to the YANG specification [YANG]. 2. Complex Types Linowski, et al. Expires September 9, 2010 [Page 6] Internet-Draft YANG Language Abstractions March 2010 2.1. Definition YANG type concept is currently restricted to define simple types, e.g. restrictions of primitive types, enumerations or union of simple types. Complex types are types with a rich internal structure, which may be composed of substatements defined in Table 1 (e.g. lists, leafs, containers, choices). A new complex type may extend an existing complex type. This allows to provide type-safe extensions to existing YANG models as instances of the new type. Complex types have the following characteristics: o Introduction of new types, as a named, formal description of a concrete manageable resource as well as abstract concepts. o Types can be extended, i.e. new types can be defined by specializing existing types adding new features. Instances of such an extended type can be used wherever instances of the base type may appear. o The type information is made part of the NETCONF payload in case a derived type substitutes a base type. This enables easy and efficient consumption of payload elements representing complex type instances. 2.2. complex-type extension statement The extension statement "complex-type" is introduced that accepts an arbitrary number of node tree defining statements among other common YANG statements ("YANG Statements", [YANG] section 7.). Linowski, et al. Expires September 9, 2010 [Page 7] Internet-Draft YANG Language Abstractions March 2010 +---------------+-------------+ | substatement | cardinality | +---------------+-------------+ | abstract | 0..1 | | anyxml | 0..n | | choice | 0..n | | container | 0..n | | description | 0..1 | | instance | 0..n | | instance-list | 0..n | | extends | 0..1 | | grouping | 0..n | | if-feature | 0..n | | key | 0..1 | | leaf | 0..n | | leaf-list | 0..n | | list | 0..n | | must | 0..n | | ordered-by | 0..n | | reference | 0..1 | | refine | 0..n | | status | 0..1 | | typedef | 0..n | | uses | 0..n | +---------------+-------------+ Table 1: complex-type's substatements Complex type definitions may appear at every place, where a grouping may be defined. That includes the module, submodule, rpc, input, output, notification, container and list statements. Complex type names populate a distinct namespace. As with YANG groupings it is possible to have a complex type definition and a data node definition (e.g. leaf, list, instance statements) with the same name in the same scope. All complex type names defined within a parent node or at the top-level of the module or its submodules share the same type identifier namespace. This namespace is scoped to the parent node or module. A complex type MAY have an instance key. An instance key is either defined with the "key" statement as part of the complex type or is inherited from the base complex type. It is not allowed to define an additional key if the base complex type or one of its ancestors already defines a key. Complex-type definitions do not create nodes in the management information tree. Linowski, et al. Expires September 9, 2010 [Page 8] Internet-Draft YANG Language Abstractions March 2010 2.3. instance extension statement The "instance" extension statement is used to instantiate a complex type by creating a subtree in the management information node tree. The instance statement takes one argument that is the identifier of the complex type instance. It is followed by a block of substatements. The type of the instance is specified with the mandatory "type" substatement. The type of an instance MUST be a complex type. Common YANG statements may be used as substatements of the "instance" statement. An instance is by default optional. To make an instance mandatory, "mandatory true" has to be applied as substatement. +--------------+-------------+ | substatement | cardinality | +--------------+-------------+ | description | 0..1 | | config | 0..1 | | if-feature | 0..n | | mandatory | 0..1 | | must | 0..n | | reference | 0..1 | | status | 0..1 | | type | 1 | | when | 0..1 | +--------------+-------------+ Table 2: instance's substatements The "instance" and "instance-list" extension statements (see chapter below) are similar to the existing "leaf" and "leaf-list" statements, with the exception that the content is composed of subordinate elements according to the instantiated complex type. 2.4. instance-list extension statement The "instance-list" extension statement is used to instantiate a complex type by defining a sequence of subtrees in the management information node tree. Also the "instance-list" statement takes one argument that is the identifier of the complex type instances. It is followed by a block of substatements. The type of the instance is specified with the mandatory "type" substatement. In addition it can be defined how often an instance may appear in the management information tree by using the min- elements and max-elements substatements. Common YANG statements may be used as substatements of the "element" statement. Linowski, et al. Expires September 9, 2010 [Page 9] Internet-Draft YANG Language Abstractions March 2010 +---------------+-------------+ | substatementc | cardinality | +---------------+-------------+ | description | 0..1 | | config | 0..1 | | if-feature | 0..n | | max-elements | 0..1 | | min-elements | 0..1 | | must | 0..n | | ordered-by | 0..1 | | reference | 0..1 | | status | 0..1 | | type | 1 | | when | 0..1 | +---------------+-------------+ Table 3: instance-list's substatements In case the instance list represents configuration, the used complex type of an element MUST have an element key. Instances as well as instance lists may appear as arguments of the "deviate" statement. 2.5. extends extension statement A complex type MAY extend exactly one existing base complex type by using the "extends" extension statement. The keyword "extends" MAY occur as substatement of the "complex-type" extension statement. The base complex type is referred to in the single argument via its scoped name. In case a complex type represents configuration data (the default), it MUST have a key, otherwise it MAY have a key. A key is either defined with the key statement as part of the complex type or is inherited from the base complex type. +--------------+-------------+ | substatement | cardinality | +--------------+-------------+ | description | 0..1 | | reference | 0..1 | | status | 0..1 | +--------------+-------------+ Table 4: extends' substatements Linowski, et al. Expires September 9, 2010 [Page 10] Internet-Draft YANG Language Abstractions March 2010 2.6. abstract extension statement Complex types may be declared to be abstract by using the "abstract" extension statement. An abstract complex type cannot be instantiated, meaning it cannot appear as most specific type of an instance in NETCONF payload. In case an abstract type extends a base type, the base complex type MUST be also abstract. By default, complex types are not abstract. The complex type serves only as a base type for derived concrete complex types and cannot be used as a type for an instance in NETCONF payload. The "abstract" extension statement takes a single string argument, which is either "true" or "false". In case a "complex-type" statement does not contain an "abstract" statement as substatement, the default is "false". The "abstract" statement does not support any substatements. 2.7. XML Encoding Rules An "instance" node is encoded as an XML element, where an "instance- list" node is encoded as a series of XML elements. The XML element name is the "instance" respectively "instance-list" identifier, and its XML namespace is the module's XML namespace. The instance key nodes are encoded as subelements to the instance identifier XML element, in the same order as they are defined within the "key" statement of the instances complex type. The rest of the instance child nodes are encoded as subelements to the instance XML element, after the key elements, in the same order as they are defined within the complex type statement. Child nodes of an extending complex type precede the child nodes of the extended complex type. As such, the XML encoding of lists is very similar to the encoding of containers and lists. The only exception is the encoding of the type of actual complex type instance, described in the following section. 2.8. Type Encoding Rules In order to encode the type of an instance in NETCONF payload, XML elements named "type" belonging to the XML namespace "urn:ietf:params:xml:ns:yang:complex-type-instance" are added to the serialized form of instance and instance-list instances. The suggested namespace prefix is "ct". The "ct:type" XML elements are inserted before the serialized form of all (non-key) members that have been declared in the according complex type definition. The "ct:type" element is inserted for each type in the extension chain from the type specified in the "instance" or "instance-list" statement to the actual type of the instance in reverse order (most Linowski, et al. Expires September 9, 2010 [Page 11] Internet-Draft YANG Language Abstractions March 2010 specific first). Each type name includes its corresponding namespace. The type of a complex type instance MUST be encoded in the reply to NETCONF and operations, and also in the payload of NETCONF operation if the operation is "create" or "replace". The type of the instance MUST also be specified in case is used to export a configuration to a resource addressed with an URI. Also the type of the instance has to be specified in user defined RPC's. The type of the instance MAY be specified in case the operation is "merge" (either because this is explicitly specified or no operation attribute is provided). In case the node already exists in the target configuration and the type attribute (type of a complex type instance) is specified but differs from the data in the target, an element is returned with an value of "wrong-type". In case no such element is present in the target configuration but the type attribute is missing in the configuration data, an element is returned with an value of "missing-type". The type MUST NOT be specified in case the operation is "delete". 2.9. Extension and Feature Definition Module The module below contains all YANG extension definitions for complex types and typed instance identifiers. In addition a "complex-type" feature is defined, which may be used to provide conditional or alternative modelling for depending on the support status of complex types in a NETCONF agent. An agent that supports the complex types modelling features and the XML encoding for complex types as defined in this document MUST advertise this as a feature. This is done by including the feature name "complex-types" into the feature parameter list as part of the NETCONF message as described in section 5.6.4 in [YANG]. module complex-types { namespace "urn:ietf:params:xml:ns:yang:complex-types"; prefix "ct"; organization "NETMOD WG"; Linowski, et al. Expires September 9, 2010 [Page 12] Internet-Draft YANG Language Abstractions March 2010 contact "bernd.linowski@ext.nsn.com"; description "This module defines extensions to model complex types and typed instance identifiers."; revision 2009-09-29 { description "Initial revision."; } extension complex-type { description "Defines a complex-type."; reference "chapter 2.2., complex-type extension statement"; argument type-identifier { yin-element true; } } extension extends { description "Defines the base type of a complex-type."; reference "chapter 2.5., extends extension statement"; argument base-type-identifier { yin-element true; } } extension abstract { description "Makes the complex-type abstract."; reference "chapter 2.6., complex-type extension statement"; argument status; } extension instance { description "Declares an instance of the given complex type."; reference "chapter 2.3., instance extension statement"; argument ct-instance-identifier { yin-element true; } } extension instance-list { description "Declares a list of instances of the given Linowski, et al. Expires September 9, 2010 [Page 13] Internet-Draft YANG Language Abstractions March 2010 complex type"; reference "chapter 2.4., instance-list extension statement"; argument ct-instance-identifier { yin-element true; } } extension instance-type { description "Tells to which type instance the instance identifier refers to."; reference "chapter 3.2., instance-type extension statement"; argument target-type-identifier { yin-element true; } } feature complex-types { description "This feature indicates that the agent supports complex types and instance identifiers."; } } 2.10. Model Example The example below shows how complex types can be used to represent physical equipment in a vendor independent, abstract way. module hw { namespace "urn:org:example:xml:ct:hw"; prefix "hw"; import complex-types {prefix "ct"; } ct:complex-type ManagedHardware { ct:abstract true; key object-id; leaf objectId { type string { length "1..32"; } } leaf serialNumber { type string; config false; } leaf commonName { type string; } Linowski, et al. Expires September 9, 2010 [Page 14] Internet-Draft YANG Language Abstractions March 2010 } ct:complex-type Equipment { ct:extends ManagedHardware; ct:abstract true; leaf installed {type boolean; config false; } leaf version { type string; } leaf redundancy {type uint16; } } ct:complex-type EquipmentHolder { ct:extends ManagedHardware; ct:abstract true; ct:instance-list equipment { type Equipment; } ct:instance-list holder { type EquipmentHolder; } } // Holder types ct:complex-type Slot { ct:extends EquipmentHolder; leaf slotNumber { type uint16; config false; } } ct:complex-type Chassis { ct:extends EquipmentHolder; leaf numberOfSlots { type uint16; config false; } } // Equipment types ct:complex-type Card { ct:extends Equipment; leaf usedSlots { type uint16; mandatory true; } } // Root Element ct:instance hardware { type ManagedHardware; } } // hw module Linowski, et al. Expires September 9, 2010 [Page 15] Internet-Draft YANG Language Abstractions March 2010 2.11. NETCONF Payload Example Following example shows the payload of a reply to a NETCONF command. The actual type of managed hardware instances is indicated with the "ct:type" elements as required by the type encoding rules. The containment hierarchy in the NETCONF XML payload reflects the containment hierarchy of hardware instances. This makes filtering based on the containment hierarchy possible without having to deal with values of key-ref leafs that represent the tree structure in a flattened hierarchy. R31r1 hw:Chassis 6 hw:EquipmentHolder R31s2 hw:Slot 1 hw:EquipmentHolder ATM-45252 hw:Card 1 hw:Equipment true A2 1 A-778911-b ATM-ADM 2 T-K4733890x45 CU-Slot hw:ManagedHardware R-US-3276279a Rack R322-1 // ... 2.12. Update Rules for Modules Using Complex Types In addition to the module update rules specified in chapter 10 of [YANG], modules that define complex-types, instances of complex types and typed instance identifiers must obey following rules: Linowski, et al. Expires September 9, 2010 [Page 16] Internet-Draft YANG Language Abstractions March 2010 o New complex types MAY be added. o A new complex type MAY extend an existing complex type. o New data definition statements MAY be added to a complex type only if: * they are not mandatory and * they are not conditionally dependent on a new feature (i.e., have a "if-feature" statement, which refers to a new feature). o The type referred to by the instance-type statement may be changed to a type that derives from the original type only if the original type does not represent configuration data. 2.13. Using Complex Types All data nodes defined inside a complex type reside in the namespace, in which the complex type is defined. 2.13.1. Overriding Complex Types Data Nodes One the one hand, it is not allowed to override a data node inherited from a base type. I.e. it is an error if a type "base" with a leaf named "foo" is extended by another complex type ("derived") with a leaf named "foo" in the same module. In case they are derived in different modules, there are two distinct "foo" nodes residing in different namespaces. On the other hand a complex type that extends a basic complex type may use the "refine" statement in order to improve an inherited data node. The target node identifier must be qualified by the module prefix to indicate clearly, which inherited node is refined. The following refinements can be done: o A leaf or choice node may have a default value, or a new default value if it already had one o Any node may have a different "description" or "reference" string. o A leaf, anyxml, or choice node may have a "mandatory true" statement. But it is not allowed to change from "mandatory true" to "mandatory false". o A leaf, leaf-list, list, container, or anyxml node may have additional "must" expressions. Linowski, et al. Expires September 9, 2010 [Page 17] Internet-Draft YANG Language Abstractions March 2010 o A list, leaf-list, instance or instance-list node may have a "min- elements" statement, if the base type does not have one or one with a value that is greater than the minimum value of the base type. o A list, leaf-list, instance or instance-list node may have a "max- elements" statement, if the base type does not have one or one with a value that is smaller than the maximum value of the base type. It is not allowed to refine complex-type nodes inside instance or instance-list statements. 2.13.2. Augmenting Complex Types Augmenting complex types can only be done when a complex type is instantiated in an "instance" or "instance-list" statement. This confines the effect of the augmentation to the location in the schema tree, where the augmentation is done. The argument of the "augment" statement MUST be in the descendant form (as defined by the rule "descendant-schema-nodeid" in Section 12 of [YANG]). The schema node identifier "." (current node) may be used to augment data nodes directly into the instance or instance-list node. ct:complex-type Chassis { ct:extends EquipmentHolder; container chassisInfo { config false; leaf numberOfSlots { type uint16; } leaf occupiedSlots { type uint16; } leaf height {type uint16;} leaf width {type unit16;} } } ct:instance-list chassis { type Chassis; augment "chassisInfo" { leaf modelId { type string; } } } When augmenting a complex type, only the "container", "leaf", "list", "leaf-list", "choice", "instance", "instance-list" and "if-feature" statements may be used within the "augment" statement. The nodes added by the augmentation MUST NOT be mandatory nodes. One or many augment statements may not cause the creation of multiple nodes with Linowski, et al. Expires September 9, 2010 [Page 18] Internet-Draft YANG Language Abstractions March 2010 the same name from the same namespace in the target node. 2.13.3. Controlling the Use of Complex Types A module might not want to support all complex types derived from a base class defined in another module. This issue can be addressed with YANG features as follows: o Features are defined that are used inside complex type definitions (by using "if-feature" as substatement) to make them optional. In this case such complex types may only be instantiated if the feature is supported (advertized as capability in the NETCONF message). o The "deviation" statement may be applied to node trees, which are created by "instance" and "instance-list" statements. In this case only the substatement "deviate not-supported" is allowed. o It is not allowed to apply the deviation statement to node tree elements that may occur because of the recursive use of a complex type. Other forms of deviations ("deviate add", "deviate replace", "deviate delete") are NOT supported inside node trees spanned by "instance" or "instance-list". As complex type definitions do not contribute by itself to the data node tree, data node declarations inside complex types cannot be a target of deviations. In the example below, client applications are informed that the leaf "occupiedSlots" is not supported in the top-level chassis (see also previous example). But if a chassis contains another chassis, the contained chassis may support the leaf informing about the number of occupied slots. deviation "/chassis/chassisSpec/occupiedSlots" { deviate not-supported; } 3. Typed Instance Identifier 3.1. Definition Typed instance identifier relationships are an addition to the relationship types already defined in YANG, where the leafref relationship is location dependent, and the instance-identifier is not type-safe. Linowski, et al. Expires September 9, 2010 [Page 19] Internet-Draft YANG Language Abstractions March 2010 Typed instance identifiers represent references to instances of a complex type without being restricted to a particular location in the containment tree. This is done by using the extension statement "instance-type" as a substatement of the existing "type instance identifier" statement. Typed instance identifiers allow referring to instances of complex types that may be located anywhere in the management information tree. The "type" statement plays the role of a restriction that must be fulfilled by the target node, which is referred to with the instance identifier. The target node MUST be of a particular complex type, either the type itself or any type that extends this complex type. 3.2. instance-type extension statement The "instance-type" extension statement defines, which complex type must be instantiated by the instance the identifier points to, or any complex type that extends the referred complex type. The instance complex type is identified by the single argument via its scoped name. The referred complex type MUST have a key. This extension statement MUST be used as a substatement of the instance-identifier statement. The "instance-type" extension statement does not support any substatements. 3.3. Typed Instance Identifier Example In the example below, a physical link connects an arbitrary number of physical ports. Here typed instance identifiers are used to denote, which "PhysicalPort" instances (anywhere in the data tree) are connected by a "PhysicalLink". Linowski, et al. Expires September 9, 2010 [Page 20] Internet-Draft YANG Language Abstractions March 2010 // Extended version of type Card ct:complex-type Card { ct:extends Equipment; leaf usedSlot { type uint16; mandatory true; } ct:instance-list port { type PhysicalPort; } } ct:complex-type PhysicalPort { ct:extends ManagedHardware; leaf portNumber { type int32; mandatory true; } } ct:complex-type PhysicalLink { ct:extends ManagedHardware; leaf media { type string; } leaf-list connectedPort { type instance-identifier { ct:instance-type PhysicalPort; } min-elements 2; } } The XML encoding of an element named "link" of type "PhysicalLink" appears as below: FTCL-771 Fiber /hw:hardware[objectId='R-11'] /hw:equipment[objectId='AT22']/hw:port[objectId='P12'] /hw:hardware[objectId='R-42] /hw:equipment[objectId='AT30']/hw:port[objectId='P3'] F-7786828 FibCon 7 4. IANA Considerations This document registers two URIs in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registrations are requested: Linowski, et al. Expires September 9, 2010 [Page 21] Internet-Draft YANG Language Abstractions March 2010 URI: urn:ietf:params:xml:ns:yang:complex-types URI: urn:ietf:params:xml:ns:yang:complex-type-instance Registrant Contact: The NETCONF WG of the IETF. XML: N/A, the requested URIs are XML namespaces. In the registry "IETF YANG Modules", the following YANG module shall be recorded (after IETF review as defined in [RFC5226]): YANG Module XML namespace Reference ------------- ----------------------------------------- --------- complex-types urn:ietf:params:xml:ns:yang:complex-types RFC XXXX RFC Ed.: Please replace XXXX with actual RFC number and remove this note. 5. Security Considerations Complex-types and Typed Instance Identifiers themselves do not have any security impact on the Internet. The security considerations described throughout [YANG] apply here as well. 6. Acknowledgements The authors would like to thank to Martin Bjorklund, Balazs Lengyel, Gerhard Muenz, Juergen Schoenwaelder and Martin Storch for their valuable review and comments. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", January 2004. [RFC5226] Narten, T., "Guidelines for Writing an IANA Considerations Section in RFCs", May 2008. [YANG] Bjorklund, M., "YANG - A data modeling language for NETCONF", draft-ietf-netmod-yang-11 (work in progress), February 2010. Linowski, et al. Expires September 9, 2010 [Page 22] Internet-Draft YANG Language Abstractions March 2010 7.2. Informative References [IPFIXCONF] Muenz, G., "Configuration Data Model for IPFIX and PSAMP", draft-ietf-ipfix-configuration-model-05 (work in progress), March 2009. Appendix A. Open issues o Extension of recursive data structures: Complex Types enable recursive data structures. Complex type augmentations propose the augmentation of complex type instances without recursion. Whether there is a need for augmentation of recursive data structures at all levels needs to be analized. Similar issues exist in the context of deviations and access control for NETCONF. Appendix B. Change Log B.1. 01-02 o It is no longer allowed to use the "config" statement inside a complex type definition. o Complex types can now be defined where a grouping can be defined. o Complex types have their own namespace. o Explicitly specified which kind of refinements can be applied to elements of the base type in the definition of an extending complex type. o Confined the use of deviations for complex types to complex type instantiations. o Defined augmentation of complex types allowing augmentation only during instantiation via an "instance" or "instance-list" statement. o Removed leftovers from substatement tables. o Updates and bug-fixes in the examples. B.2. 00-01 o Transformed proposed new YANG statements to YANG extension statements (complex-type, element, extends, abstract). Linowski, et al. Expires September 9, 2010 [Page 23] Internet-Draft YANG Language Abstractions March 2010 o Renamed statement "element" to the extension statement "instance" in order to avoid confusion with XML payload elements. o Introduced extension statement "instance-type" as allowing the use of the existing "type" statement as substatement in the existing "instance-identifier" statement cannot be done with extensions. o Added the complex type extension statement module. o Updated examples to reflect the changes mentioned above. o Added update rules for complex types. o Updated IANA Considerations section. o Added this change log. Appendix C. Example Model C.1. Modeling Improvements for the IPFIX/PSAMP Model with Complex types and Typed instance identifiers The module below is a variation of the IPFIX/PSAMP configuration model, which uses complex types and typed instance identifiers to model the concept outlined in [IPFIXCONF]. When looking at the YANG module with complex types and typed instance identifiers, various technical improvements on modeling level become apparent. o There is almost a one-to-one mapping between the domain concepts introduced in IPFIX and the complex types in the YANG module o All associations between the concepts (which are not containment) are represented with typed identifiers. That avoids having to refer to a particular location in the tree, which is not mandated by the original model. o It is superfluous to represent concept refinement (class inheritance in the original model) with containment in form of quite big choice-statements with complex branches. Instead, concept refinement is realized by complex types extending a base complex type. o It is not required to make an artificial distinction between IP and file destinations (see list "exportingProcess" in [IPFIXCONF]). Instead an abstract base class is used to capture the commonalities of all destinations. Linowski, et al. Expires September 9, 2010 [Page 24] Internet-Draft YANG Language Abstractions March 2010 o It is unnecessary to introduce metadata types and leafs (e.g. "typedef ipfixTransportProtocol" and "leaf transportProtocol" in "grouping destinationParamters") that just serve the purpose of indicating which concrete sub-type of a generic type (modeled as grouping, which contains the union of all features of all subtypes) is actually represented in the MIB. o Ruling out illegal use of sub-type specific properties (e.g. "leaf templateRefreshTimeout") by using "must" statements that refer to a sub-type discriminator is not necessary (e.g. must "../transportProtocol=udp"). o It is not needed to define properties like the configuration status wherever a so called "parameter grouping" is used. Instead those definitions can be put inside the complex-type definition itself (e.g. "config false" statements). o Declaring the key of a type repeatedly at every place, where a grouping is used becomes superfluous (see use of "grouping optionTemplate"). o Complex types may be declared as optional features. If the type is indicated with an enumeration, which has a literal per type (e.g. "typedef ipfixTransportProtocol"), this is not possible, since "if-feature" is not allowed as a substatement of "enum". C.2. IPFIX/PSAMP Model with Complex Types and Typed Instance Identifiers module ipfix-psamp { namespace "urn:ietf:params:xml:ns:ipfix-psamp-config"; prefix ipfix; import yang-types { prefix yang; } import inet-types { prefix inet; } import complex-types {prefix "ct"; } description "Example IPFIX/PSAMP Configuration Data Model with complex types and typed instance identifiers"; revision 2009-03-02 { description "Version of draft-ietf-ipfix-configuration-model-02 modeled with complex types and typed instance identifiers."; Linowski, et al. Expires September 9, 2010 [Page 25] Internet-Draft YANG Language Abstractions March 2010 } feature exporter { description "If supported, the device can be used as an Exporter. Exporting Processes can be configured."; } feature collector { description "If supported, the device can be used as a Collector. Collecting Processes can be configured."; } feature meter { description "If supported, Observation Points, Selection Processes, and Caches can be configured."; } feature psampSampCountBased { description "If supported, the device supports count-based Sampling. The Selector method sampCountBased can be configured."; } feature psampSampTimeBased { description "If supported, the device supports time-based Sampling. The Selector method sampTimeBased can be configured."; } feature psampSampRandOutOfN { description "If supported, the device supports random n-out-of-N Sampling. The Selector method sampRandOutOfN can be configured."; } feature psampSampUniProb { description "If supported, the device supports uniform probabilistic Sampling. The Selector method sampUniProb can be configured."; } feature psampSampNonUniProb { description "If supported, the device supports non-uniform probabilistic Sampling. The Selector method sampNonUniProb can be configured."; } feature psampSampFlowState { description "If supported, the device supports flow state dependent Sampling. The Selector method sampFlowState can be configured."; } Linowski, et al. Expires September 9, 2010 [Page 26] Internet-Draft YANG Language Abstractions March 2010 feature psampFilterMatch { description "If supported, the device supports property match Filtering. The Selector method filterMatch can be configured."; } feature psampFilterHash { description "If supported, the device supports hash-based Filtering. The Selector method filterHash can be configured."; } feature psampFilterRState { description "If supported, the device supports router state Filtering. The Selector method filterRState can be configured."; } feature udpTransport { description "If supported, the device supports UDP as transport protocol."; } feature tcpTransport { description "If supported, the device supports TCP as transport protocol."; } feature fileReader { description "If supported, the device supports the configuration of Collecting Processes as File Readers."; } feature fileWriter { description "If supported, the device supports the configuration of Exporting Processes as File Writers."; } typedef direction { type enumeration { enum ingress; enum egress; enum both; } description "Direction of packets going through an interface or linecard."; } typedef optionType { type enumeration { Linowski, et al. Expires September 9, 2010 [Page 27] Internet-Draft YANG Language Abstractions March 2010 enum meteringStatistics { description "Metering Process Statistics."; reference "RFC 5101, section 4.1."; } enum meteringReliability { description "Metering Process Reliability Statistics."; reference "RFC 5101, section 4.2."; } enum exportingReliability { description "Exporting Process Reliability Statistics."; reference "RFC 5101, section 4.3."; } enum flowKeys { description "Flow Keys."; reference "RFC 5101, section 4.4."; } enum selectionSequence { description "Selection Sequence and Selector Reports."; reference "draft-ietf-psamp-protocol-09, section 6.5.1 and 6.5.2."; } enum selectionStatistics { description "Selection Sequence Statistics Report."; reference "draft-ietf-psamp-protocol-09, section 6.5.3."; } enum accuracy { description "Accuracy Report."; reference "draft-ietf-psamp-protocol-09, section 6.5.4."; } enum reducingRedundancy { description "Application of ipfix-reducing-redundancy."; reference "draft-ietf-ipfix-reducing-redundancy-04"; } } description "Options Templates specified by IPFIX and PSAMP."; } typedef templateFieldFlags { type bits { bit scope { position 0; } bit flowKey { position 1; } Linowski, et al. Expires September 9, 2010 [Page 28] Internet-Draft YANG Language Abstractions March 2010 } description "Attributes of a field in a Template."; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixTemplateDefinitionFlags)"; } typedef transportSessionStatus { type enumeration { enum inactive; enum active; enum unknown; } description "Status of a Transport Session."; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixTransportSessionStatus)."; } typedef filterRStateFunction { type enumeration { enum other; enum ingressIf; enum egressIf; enum aclViolation; enum rpfFailure; enum noResources; enum noRoute; enum originAS; enum destAS; } description "Filter function applied to router state."; reference "draft-ietf-psamp-mib-06, section 5.2.3."; } typedef exportMemberType { type enumeration { enum primary; enum secondary; enum duplicate; enum loadBalancing; enum unused; } description "This type defines different usages of an export destination among all destinations of an Exporting Process. It corresponds to ipfixExportMemberType in IPFIX-MIB."; reference "draft-ietf-ipfix-mib-05."; } grouping informationElement { Linowski, et al. Expires September 9, 2010 [Page 29] Internet-Draft YANG Language Abstractions March 2010 description "Parameters of an Information Element."; choice nameOrId { mandatory true; description "Name or ID of the Information Element."; reference "RFC5102"; leaf ieName { type string; } leaf ieId { type uint16; } } leaf ieLength { type uint16; description "Length can be omitted if a default length exists for the specified Information Element. A value of 65535 specifies a variable-length Information Element."; reference "RFC5102"; } leaf ieEnterpriseNumber { type uint32; description "If present, this is an enterprise-specific Information Element."; reference "RFC5101, RFC5102"; } } grouping cacheLayoutParameters { description "Fields of a Cache Layout."; list cacheField { key name; min-elements 1; leaf name { type string; } uses informationElement; leaf isFlowKey { type empty; description "If present, this is a flow key."; } } } ct:complex-type Receiver { description "Receiver of a Collecting Process"; ct:abstract true; key name; leaf name { type string; } } ct:complex-type IpReceiver { ct:extends Receiver; ct:abstract true; Linowski, et al. Expires September 9, 2010 [Page 30] Internet-Draft YANG Language Abstractions March 2010 leaf destinationIpAddress { type inet:ip-address; mandatory true; } leaf destinationPort { type inet:port-number; default 4739; } leaf sendBufferSize { type uint32; units bytes; description "Size of the socket send buffer. If not configured, this parameter is set by the monitoring device"; } leaf rateLimit { type uint32; units "bytes per second"; description "Maximum number of bytes per second the Exporting Process may export to the given destination. The number of bytes is calculated from the lengths of the IPFIX Messages exported. If not configured, no rate limiting is performed."; reference "draft-ietf-psamp-protocol-09, section 6.3."; } } ct:complex-type SctpReceiver { ct:extends IpReceiver; description "SCTP receiver"; reference "RFC 4960."; leaf-list localIpAddress { type inet:ip-address; description "List of eligible local IP addresses to be used by the SCTP endpoint. If not configured, all locally assigned IP addresses are used by the local endpoint."; reference "RFC 3758, RFC 4960."; } leaf timedReliability { type yang:timeticks; default 0; description "PR-SCTP lifetime for IPFIX Messages containing Data Sets only. Zero means reliable transport."; reference "RFC 3758, RFC 4960."; } leaf numberOfStreams { type uint16; description "Number of outbound streams requested for the Linowski, et al. Expires September 9, 2010 [Page 31] Internet-Draft YANG Language Abstractions March 2010 SCTP association. If not configured, this parameter is set by the monitoring device."; reference "RFC 3758, RFC 4960."; } leaf orderedDelivery { type boolean; default true; description "Ordered delivery of IPFIX Messages containing Data Sets."; reference "RFC 3758, RFC 4960."; } } ct:complex-type UdpReceiver { if-feature udpTransport; ct:extends IpReceiver; description "UDP receiver."; leaf sourceIpAddress { type inet:ip-address; description "Sets source IP address if UDP is transport protocol. If not configured, the IP address assigned to the outgoing interface is used."; } leaf templateRefreshTimeout { type uint32; units seconds; default 600; description "Sets time after which Templates are resent if UDP is transport protocol."; reference "RFC5101."; } leaf optionTemplateRefreshTimeout { type uint32; units seconds; default 600; description "Sets time after which Options Templates are resent if UDP is transport protocol."; reference "RFC5101."; } leaf templateRefreshPacket { type uint32; units "IPFIX Messages"; description "Sets number of IPFIX Messages after which Templates are resent if UDP is transport protocol. If omitted, Templates are only resent after timeout."; reference "RFC5101."; } Linowski, et al. Expires September 9, 2010 [Page 32] Internet-Draft YANG Language Abstractions March 2010 leaf optionTemplateRefreshPacket { type uint32; units "IPFIX Messages"; description "Sets number of IPFIX Messages after which Options Templates are resent if UDP is transport protocol. If omitted, Templates are only resent after timeout."; reference "RFC5101."; } } ct:complex-type TcpReceiver { if-feature tcpTransport; ct:extends IpReceiver; description "TCP receiver."; } ct:complex-type FileReader { if-feature fileReader; ct:extends Receiver; description "File Reader parameters."; leaf uri { mandatory true; type inet:uri; } } ct:complex-type CollectingProcess { description "A Collecting Process."; key name; leaf name { description "Arbitrary but unique name of the Collecting Process."; type string; } ct:instance-list receiver { description "Receivers of the collection process."; type Receiver; min-elements 1; } leaf-list exportingProcess { description "Export of received records without any modifications. Records are processed by all Exporting Processes in the list."; type instance-identifier { ct:instance-type ExportingProcess; } } ct:instance-list Template { config false; Linowski, et al. Expires September 9, 2010 [Page 33] Internet-Draft YANG Language Abstractions March 2010 type Template; } ct:instance-list transportSession { config false; type TransportSession; } } ct:complex-type ObservationPoint { description "Base Observation Point."; ct:abstract true; key name; leaf name { description "Arbitrary but unique name of the Observation Point."; type string; } leaf observationPointId { description "If omitted, the Observation Point ID is assigned by the monitoring device."; type uint32; } leaf observationDomainId { description "The Observation Domain ID associates the Observation Point to an Observation Domain. Observation Points with identical Observation Domain ID belong to the same Observation Domain."; mandatory true; type uint32; } leaf-list selectionProcess { description "Selection Processes in this list process packets in parallel."; type instance-identifier { ct:instance-type SelectionProcess; } } } ct:complex-type LinecardObservationPoint { ct:extends ObservationPoint; description "Linecard Observation Point."; leaf physicalEntity { description "Instance identifier of the observed linecard"; type instance-identifier {ct :instance-type PhysicalEntity; } } // Note: This modeling assumes that also physical entities are // modeled with complex types. Otherwise a choice // with an index or name needs to be used. Linowski, et al. Expires September 9, 2010 [Page 34] Internet-Draft YANG Language Abstractions March 2010 leaf direction { description "Direction of packets. If not applicable (e.g., in the case of a sniffing interface in promiscuous mode), this parameter is omitted"; type direction; default both; } } ct:complex-type InterfaceObservationPoint { ct:extends ObservationPoint; description "Interface Observation Point."; leaf interface { description "Instance identifier of the observed interface"; type instance-identifier {ct:instance-type Interface;} } // Note: this modeling assumes that also interfaces // are modeled with complex types. Otherwise a choice // with an index or name as to be used. leaf direction { description "Direction of packets. If not applicable (e.g., in the case of a sniffing interface in promiscuous mode), this parameter is omitted"; type direction; default both; } } ct:complex-type Selector { ct:abstract true; description "Abstract Selector."; key name; leaf name { description "Arbitrary but unique name of the Selector."; type string; } leaf selectorId { type uint16; description "The Selector ID must be unique within the Observation Domain. If not configured, this parameter is set by the monitoring device."; reference "draft-ietf-psamp-info-11"; } leaf packetsObserved { type yang:counter64; config false; Linowski, et al. Expires September 9, 2010 [Page 35] Internet-Draft YANG Language Abstractions March 2010 description "Corresponds to ipfixSelectorStatsPacketsObserved in IPFIX-MIB."; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixSelectorStatsPacketsObserved)."; } leaf packetsDropped { type yang:counter64; config false; description "Corresponds to ipfixSelectorStatsPacketsDropped in IPFIX-MIB."; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixSelectorStatsPacketsDropped)."; } } ct:complex-type SelectAll { ct:extends Selector; } ct:complex-type SampCountBased { if-feature psampSampCountBased; ct:extends Selector; leaf interval { type uint32; mandatory true; } leaf spacing { type uint32; mandatory true; } } ct:complex-type SampTimeBased { if-feature psampSampTimeBased; ct:extends Selector; leaf interval { type uint32; mandatory true; } leaf spacing { type uint32; mandatory true; } } ct:complex-type SampRandOutOfN { if-feature psampSampRandOutOfN; ct:extends Selector; Linowski, et al. Expires September 9, 2010 [Page 36] Internet-Draft YANG Language Abstractions March 2010 leaf population { type uint32; mandatory true; } leaf sample { type uint32; mandatory true; } } ct:complex-type SampUniProb { if-feature psampSampUniProb; ct:extends Selector; leaf probability { type uint32; mandatory true; description "The given value must be divided by 4294967295."; } } ct:complex-type SampNonUniProb { if-feature psampSampNonUniProb; ct:extends Selector; leaf function { type yang:object-identifier; mandatory true; } leaf funcParam { type yang:object-identifier; mandatory true; } } ct:complex-type SampFlowState { if-feature psampSampFlowState; ct:extends Selector; leaf function { type yang:object-identifier; mandatory true; } leaf funcParam { type yang:object-identifier; mandatory true; } } ct:complex-type FilterMatch { Linowski, et al. Expires September 9, 2010 [Page 37] Internet-Draft YANG Language Abstractions March 2010 if-feature psampFilterMatch; ct:extends Selector; choice nameOrId { mandatory true; description "Deviating from the PSAMP MIB, the field is specified by either the name or the ID of the Information Element."; leaf ieName { type string; } leaf ieId { type uint16; } } leaf ieEnterpriseNumber { type uint32; description "Deviating from the PSAMP MIB, an enterprise number may be specified to refer to an enterprise-specific Information Element."; } leaf startValue { type string; mandatory true; } leaf stopValue { type string; mandatory true; } leaf mask { type string; description "If not configured, no mask is applied."; } } ct:complex-type FilterHash { if-feature psampFilterHash; ct:extends Selector; leaf addrType { type inet:ip-version; mandatory true; } leaf headerBits { type string { length 40; } mandatory true; description "If addrType is 'ipv4', only the first 20 bytes are used."; Linowski, et al. Expires September 9, 2010 [Page 38] Internet-Draft YANG Language Abstractions March 2010 } leaf payloadBytes { type uint32; default 0; } leaf payloadBits { type string; description "If not configured, all bits included in the payload section defined by payloadBytes are used."; } leaf function { type yang:object-identifier; mandatory true; } leaf funcParam { type yang:object-identifier; mandatory true; } leaf inputBits { type uint32; mandatory true; } leaf outputBits { type uint32; mandatory true; } leaf outputMask { type string; mandatory true; } leaf selection { type string; mandatory true; } } ct:complex-type FilterRState { if-feature psampFilterRState; ct:extends Selector; leaf function { type filterRStateFunction; mandatory true; } leaf negate { type boolean; default false; } leaf ifIndex { Linowski, et al. Expires September 9, 2010 [Page 39] Internet-Draft YANG Language Abstractions March 2010 type uint32; mandatory true; description "Index of the interface as stored in the ifTable of IF-MIB."; reference "RFC 2863."; } leaf startAS { type inet:autonomous-system-number; must "../function=originAS or ../function=destAS"; } leaf stopAS { type inet:autonomous-system-number; must "../function=originAS or ../function=destAS"; } leaf vendorFunc { type yang:object-identifier; must "../function=other"; } } ct:complex-type SelectionProcess { description "A Selection Process."; key name; leaf name { description "Arbitrary but unique name of the Selection Process."; type string; } leaf selectionSequenceId { description "The Selection Sequence ID must be unique within the Observation Domain. If not configured, this parameter is set by the monitoring device."; reference "draft-ietf-psamp-info-11"; type uint64; } ct:instance-list selector { description "List of Selectors that define the action of the Selection Process on a single packet. The Selectors are serially invoked in the same order as they appear in this list."; min-elements 1; ordered-by user; type Selector; } leaf-list selectionProcess { description "A Selection Process may pass selected packets to further Selection Processes."; Linowski, et al. Expires September 9, 2010 [Page 40] Internet-Draft YANG Language Abstractions March 2010 type instance-identifier { ct:instance-type SelectionProcess; } } leaf-list cache { description "Caches in this list receive the selected packets in parallel."; type instance-identifier { ct:instance-type Cache; } } } typedef cacheType { type enumeration { enum immediate { description "Flow expiration after the first packet, generation of Packet Records."; } enum timeout { description "Flow expiration after active and inactive timeout, generation of Flow Records."; } enum permanent { description "No flow expiration, periodical export after active timeout, generation of Flow Records."; } } description "Cache Type specifies the Flow expiration policy of a Cache."; } ct:complex-type Cache { if-feature meter; description "A Cache"; key name; leaf name { type string; } leaf cacheType { description "Actual cache type. May be changed at run time."; type cacheType; mandatory true; } leaf maxRecords { type uint32; description "If not configured, this parameter is set by the Monitoring Device."; } leaf activeTimeout { type uint32; units seconds; must "../cacheType!=immediate"; Linowski, et al. Expires September 9, 2010 [Page 41] Internet-Draft YANG Language Abstractions March 2010 description "If not configured, this parameter is set by the Monitoring Device."; } leaf inactiveTimeout { type uint32; units seconds; must "../cacheType!=permanent"; description "If not configured, this parameter is set by the Monitoring Device."; } container cacheLayout { uses cacheLayoutParameters; } leaf-list exportingProcess { type leafref { path "/ipfix/exportingProcess/name"; } description "Records are exported by all Exporting Processes in the list."; } leaf activeFlows { type uint32; units flows; config false; description "Corresponds to ipfixMeteringProcessCacheActiveFlows in IPFIX-MIB."; reference "ietf-draft-ipfix-mib-05, section 7 (ipfixMeteringProcessCacheActiveFlows)"; } leaf inactiveFlows { type uint32; units flows; config false; description "Corresponds to ipfixMeteringProcessCacheInactiveFlows in IPFIX-MIB."; reference "ietf-draft-ipfix-mib-0, section 7 (ipfixMeteringProcessCacheInactiveFlows)"; } leaf dataRecords { type yang:counter64; units "Data Records"; config false; description "Corresponds to ipfixMeteringProcessDataRecords in IPFIX-MIB."; reference "ietf-draft-ipfix-mib-0, section 7 (ipfixMeteringProcessDataRecords)"; } } ct:complex-type Destination { ct:abstract true; key name; Linowski, et al. Expires September 9, 2010 [Page 42] Internet-Draft YANG Language Abstractions March 2010 leaf name { type string; } leaf type { type exportMemberType; } ct:instance-list option { type Option; } } ct:complex-type IpDestination { ct:extends Destination; ct:abstract true; leaf destinationIpAddress { type inet:ip-address; mandatory true; } leaf destinationPort { type inet:port-number; default 4739; } leaf sendBufferSize { type uint32; } leaf rateLimit { description "Maximum number of bytes per second the Exporting Process may export to the given destination. The number of bytes is calculated from the lengths of the IPFIX Messages exported."; reference "draft-ietf-psamp-protocol-09, section 6.3."; type uint32; } } ct:complex-type SctpExport { ct:extends IpDestination; description "SCTP export parameters."; reference "RFC 3758, RFC 4960."; leaf-list sourceIpAddress { description "List of eligible local IP addresses to be used by the SCTP endpoint. If omitted, all locally assigned IP addresses are used by the local endpoint."; type inet:ip-address; } leaf timedReliability { description "PR-SCTP lifetime for IPFIX Messages containing Data Sets only."; type yang:timeticks; default 0; Linowski, et al. Expires September 9, 2010 [Page 43] Internet-Draft YANG Language Abstractions March 2010 } leaf numberOfStreams { description "Number of outbound streams requested for the SCTP association."; type uint16; } leaf orderedDelivery { description "Ordered delivery of IPFIX Messages containing Data Sets."; type boolean; default "true"; } } ct:complex-type UdpExport { if-feature udpTransport; ct:extends IpDestination; description "UDP export parameters."; leaf sourceIpAddress { description "Source IP address. If omitted, the address assigned to the outgoing interface is used."; type inet:ip-address; } leaf templateRefreshTimeout { type uint32; units seconds; default 600; description "Sets time after which Templates are resent if UDP is transport protocol."; reference "RFC5101."; } leaf optionTemplateRefreshTimeout { type uint32; units seconds; default 600; description "Sets time after which Options Templates are resent if UDP is transport protocol."; reference "RFC5101."; } leaf templateRefreshPacket { type uint32; units "IPFIX Messages"; description "Sets number of IPFIX Messages after which Templates are resent if UDP is transport protocol. If omitted, Templates are only resent after timeout."; reference "RFC5101."; } Linowski, et al. Expires September 9, 2010 [Page 44] Internet-Draft YANG Language Abstractions March 2010 leaf optionTemplateRefreshPacket { type uint32; units "IPFIX Messages"; description "Sets number of IPFIX Messages after which Options Templates are resent if UDP is transport protocol. If omitted, Templates are only resent after timeout."; reference "RFC5101."; } } ct:complex-type TcpExport { if-feature tcpTransport; description "TCP export parameters."; ct:extends IpDestination; } ct:complex-type FileWriter { if-feature fileWriter; ct:extends Destination; description "File Writer."; leaf uri { type inet:uri; mandatory true; description "URI specifying the location of the file."; } must "current().type!=loadBalancing"; } ct:complex-type Option { description "Specification of the data to export using an Options Template."; key name; leaf name { type string; } leaf type { type optionType; mandatory true; } leaf timeout { type yang:timeticks; default 0; description "Time interval for exporting options data. If set to zero, the options data is sent once."; } container optionTemplate { description "If no Options Template is specified, the Exporter defines a template according to options type and available options data."; Linowski, et al. Expires September 9, 2010 [Page 45] Internet-Draft YANG Language Abstractions March 2010 list optionField { key name; ordered-by user; leaf name { type string; } uses informationElement; leaf isScope { type empty; description "If present, this is a scope field."; } } } } ct:complex-type Template { description "A Template used by an Exporting Process or received by a Collecting Process. Parameter names and semantics correspond to the managed objects in IPFIX- MIB"; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixTemplateEntry, ipfixTemplateDefinitionEntry, ipfixTemplateStatsEntry)"; leaf observationDomainId { type uint32; } leaf templateId { type uint16; } leaf setId { type uint16; } leaf accessTime { type yang:date-and-time; } leaf dataRecords { type yang:counter64; } list field { leaf ieId { type uint16; } leaf ieLength { type uint16; } leaf enterprise { type uint32; } leaf flags { type templateFieldFlags; } } } ct:complex-type TransportSession { description "State of a Transport Session originating from an Exporting or terminating at a Collecting Process. Parameter names and semantics correspond to the managed objects in IPFIX-MIB"; reference "draft-ietf-ipfix-mib-05, section 7 (ipfixTransportSessionEntry, ipfixTransportSessionStatsEntry)"; leaf index { type int32; } leaf sourceAddress { type inet:ip-address; } leaf destinationAddress { type inet:ip-address; } leaf sourcePort { type inet:port-number; } leaf destinationPort { type inet:port-number; } Linowski, et al. Expires September 9, 2010 [Page 46] Internet-Draft YANG Language Abstractions March 2010 leaf sctpAssocId { type uint32; } leaf templateRefreshTimeout { type uint32; units seconds; } leaf optionTemplateRefreshTimeout { type uint32; units seconds; } leaf templateRefreshPacket { type uint32; units "IPFIX Messages"; } leaf optionTemplateRefreshPacket { type uint32; units "IPFIX Messages"; } leaf status { type transportSessionStatus; } leaf rate { type int32; units "bytes per second"; } leaf packets { type yang:counter64; units packets; } leaf bytes { type yang:counter64; units bytes; } leaf messages { type yang:counter64; units "IPFIX Messages"; } leaf discardedMessages { type yang:counter64; units "IPFIX Messages"; } leaf records { type yang:counter64; units "Data Records"; } leaf templates { type yang:counter32; units "Templates"; } leaf optionTemplates { type yang:counter32; Linowski, et al. Expires September 9, 2010 [Page 47] Internet-Draft YANG Language Abstractions March 2010 units "Options Templates"; } } ct:complex-type ExportingProcess { description "An Exporting Process."; key name; leaf name { description "Arbitrary but unique name of the Exporting Process."; type string; } leaf exportingProcessId { description "If omitted, the Exporting Process ID is assigned by the monitoring device."; type uint32; } ct:instance-list destination { type Destination; } ct:instance-list options { type Option; } ct:instance-list Template { config false; type Template; } ct:instance-list transportSession { config false; type TransportSession; } } container ipfix { ct:instance-list collectingProcess { if-feature collector; type CollectingProcess; } ct:instance-list observationPoint { if-feature meter; type ObservationPoint; } ct:instance-list selectionProcess { if-feature meter; Linowski, et al. Expires September 9, 2010 [Page 48] Internet-Draft YANG Language Abstractions March 2010 type SelectionProcess; } ct:instance-list cache { if-feature meter; type Cache; } ct:instance-list exportingProcess { if-feature exporter; type ExportingProcess; } } } Authors' Addresses Bernd Linowski TCS/Nokia Siemens Networks Heltorfer Strasse 1 Duesseldorf 40472 Germany EMail: bernd.linowski@ext.nsn.com Mehmet Ersue Nokia Siemens Networks St.-Martin-Strasse 53 Munich 81541 Germany EMail: mehmet.ersue@nsn.com Siarhei Kuryla Jacobs University Bremen Campus Ring 1 Bremen 28725 Germany EMail: s.kuryla@jacobs-university.de Linowski, et al. Expires September 9, 2010 [Page 49]