Network Working Group B. Linowski
Internet-Draft TCS/Nokia Siemens Networks
Intended status: Experimental M. Ersue
Expires: January 13, 2011 Nokia Siemens Networks
S. Kuryla
Jacobs University Bremen
July 12, 2010
Extending YANG with Language Abstractions
draft-linowski-netmod-yang-abstract-03
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 in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on January 13, 2011.
Copyright Notice
Copyright (c) 2010 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
Linowski, et al. Expires January 13, 2011 [Page 1]
Internet-Draft YANG Language Abstractions July 2010
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.
Linowski, et al. Expires January 13, 2011 [Page 2]
Internet-Draft YANG Language Abstractions July 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 . . . . . . . . . . . . . . . . . . . . . 7
1.5. Modeling Resource Models with YANG . . . . . . . . . . . . 7
1.5.1. Example of a Physical Network Resource Model . . . . . 7
1.5.2. Modeling Entity MIB Entries as Physical Resources . . 11
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 . . . . . . . . . . . . . . . . . . . . 19
2.8. Type Encoding Rules . . . . . . . . . . . . . . . . . . . 20
2.9. Extension and Feature Definition Module . . . . . . . . . 21
2.10. Example Model for Complex Types . . . . . . . . . . . . . 23
2.11. NETCONF Payload Example . . . . . . . . . . . . . . . . . 24
2.12. Update Rules for Modules Using Complex Types . . . . . . . 27
2.13. Using Complex Types . . . . . . . . . . . . . . . . . . . 27
2.13.1. Overriding Complex Type Data Nodes . . . . . . . . . . 27
2.13.2. Augmenting Complex Types . . . . . . . . . . . . . . . 28
2.13.3. Controlling the Use of Complex Types . . . . . . . . . 29
3. Typed Instance Identifier . . . . . . . . . . . . . . . . . . 30
3.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2. instance-type extension statement . . . . . . . . . . . . 30
3.3. Typed Instance Identifier Example . . . . . . . . . . . . 30
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
5. Security Considerations . . . . . . . . . . . . . . . . . . . 32
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.1. Normative References . . . . . . . . . . . . . . . . . . . 32
7.2. Informative References . . . . . . . . . . . . . . . . . . 33
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 33
A.1. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.3. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Appendix B. YANG modules for the Physical Network Resource
Information Model and Hardware Entities . . . . . . . 35
Appendix C. Example YANG Module for the IPFIX/PSAMP Model . . . . 41
C.1. Modeling Improvements for the IPFIX/PSAMP Model with
Complex types and Typed instance identifiers . . . . . . . 42
C.2. IPFIX/PSAMP Model with Complex Types and Typed
Instance Identifiers . . . . . . . . . . . . . . . . . . . 43
Linowski, et al. Expires January 13, 2011 [Page 3]
Internet-Draft YANG Language Abstractions July 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 ([YANG]).
This document defines extensions for the modeling language YANG as
new language statements, which introduce language abstractions to
improve the model extensibility and reuse. A model example from an
actual network management system is given 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.
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
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. 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 model
elements. In order to realize such a system, it is worth to model
Linowski, et al. Expires January 13, 2011 [Page 4]
Internet-Draft YANG Language Abstractions July 2010
abstract entities, which enable reuse and ease concrete
refinements of that abstract entity in a second step.
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 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 object level or integrating an object hierarchy into an
existing information model. Extending YANG with language
abstractions can simplify on the one hand 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 proposed
YANG extensions can on the other hand enable the utilization of
YANG modeling language in other SDOs, which model complex
management systems in a top-down manner and use high-level
language features frequently.
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 discusses how
these new features can improve the modeling capabilities of YANG.
Section 1.5.1 contains a physical resource model, which deals with
some of the modeling challenges illustrated above. Section 1.5.2
gives an example, which uses the base classes defined in the physical
resource model and derives a model for physical entities defined in
Entity MIB".
1.3. Modeling Improvements with Language Abstractions
Complex Types and Typed Instance Identifiers provide various
technical improvements on modeling level:
o In case the model of a system that should be managed with NETCONF
is using 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. This avoids referring to a
Linowski, et al. Expires January 13, 2011 [Page 5]
Internet-Draft YANG Language Abstractions July 2010
particular location in the MIB, which is not mandated by the
domain model.
o Complex types allow defining 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
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 defining 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. This allows to determine the actual type of an instance
during the NETCONF payload parsing and avoids the use of
additional leafs in the model, 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 C '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 IPFIX/PSAMP configuration model in
[IPFIXCONF].
Linowski, et al. Expires January 13, 2011 [Page 6]
Internet-Draft YANG Language Abstractions July 2010
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 are
valid with respect to the YANG specification [YANG].
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 modelling concepts as defined in [SID V8] and is compliant
with selected parts of SID Resource Abstract Business Entities domain
([UDM]).
The class diagram in Figure 1 and the according YANG module excerpt
focus on basic resource ("Resource" and the distinction between
logical- and physical resources) and hardware abstractions
("Hardware", "Equipment", and "EquipmentHolder"). Some class
attributes were omitted to achieve decent readability.
+--------+
|Resource|
+--------+
/\ /\
-- --
| |
| +---------------+
| |LogicalResource|
| +---------------+
|
|
|
| +--------+
| |Physical| +-----------+
'-|Resource|<|-+-|PhysicalLink|
+---- ---+ | +------------+
| |0..* physicalLink
| |
| | equipment
Linowski, et al. Expires January 13, 2011 [Page 7]
Internet-Draft YANG Language Abstractions July 2010
| | 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
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 refined 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
Linowski, et al. Expires January 13, 2011 [Page 8]
Internet-Draft YANG Language Abstractions July 2010
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. Complex types support such a
containment by using a complex type (or one of its ancestor types)
as 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
association between classes that represent an essential
relationship 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 relationships do not mandate
any particular location of the two connected hardware instances in
any MIB. Such containment agnostic relationships can be
represented by a typed instance identifier that embodies one
direction of such an association (see "Typed instance
identifiers").
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 B: 'YANG module for the Physical
Network Resource Model and Hardware Entities'.
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 "urn:com:nsn:udmcore";
prefix "udm";
Linowski, et al. Expires January 13, 2011 [Page 9]
Internet-Draft YANG Language Abstractions July 2010
import complex-types {prefix "ct"; }
// Basic complex types...
ct:complex-type PhysicalResource {
ct:extends Resource;
ct:abstract true;
// ...
leaf serialNumber {type string;}
}
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;
}
}
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;}
// ...
Linowski, et al. Expires January 13, 2011 [Page 10]
Internet-Draft YANG Language Abstractions July 2010
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;
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.
Linowski, et al. Expires January 13, 2011 [Page 11]
Internet-Draft YANG Language Abstractions July 2010
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.
Module umdcore : Module hardware-entities
:
equipment :
Holder :
0..* :
+-------+ :
| | :
+---------------+ +---------+ | :
|ManagedHardware|<|-+-|Equipment|<>--+ :
+---------------+ | | Holder |0..1 : +--------+
| | |<|---------+--|HWModule|
| +---------+ : | +--------+
| <> : |
| |0..* equipment : | +---------+
| | Holder : '--|Backplane|
| | : +---------+
| |0..* equipment :
| | :
| | equipment :
| | 0..* :
| | +-------+ :
| | | | :
| +---------+ | :
'-|Equipment|<>--+ : +-------+
| |<|---------+--|Chassis|
+---------+ : | +-------+
compositeEquipment : |
: | +---------+
: |--|Container|
: +---------+
...
Linowski, et al. Expires January 13, 2011 [Page 12]
Internet-Draft YANG Language Abstractions July 2010
Figure 2: Model for Hardware Entities
Below is an excerpt of the according 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 B: 'YANG
modules for the Physical Network Resource Model and Hardware
Entities'.
Linowski, et al. Expires January 13, 2011 [Page 13]
Internet-Draft YANG Language Abstractions July 2010
<CODE BEGINS>
module hardware-entities {
namespace "urn:com:nsn:hardware-entities";
prefix "hwe";
import yang-types {prefix "yt";}
import complex-types {prefix "ct";}
import udmcore {prefix "uc";}
grouping PhysicalEntityProperties {
// ...
leaf mfgDate {type yt: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>
Linowski, et al. Expires January 13, 2011 [Page 14]
Internet-Draft YANG Language Abstractions July 2010
2. Complex Types
2.1. Definition
YANG type concept is currently restricted to 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 providing 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 January 13, 2011 [Page 15]
Internet-Draft YANG Language Abstractions July 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 define a complex type and a data node
(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 January 13, 2011 [Page 16]
Internet-Draft YANG Language Abstractions July 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 |
| anyxml | 0..n |
| choice | 0..n |
| container | 0..n |
| instance | 0..n |
| instance-list | 0..n |
| leaf | 0..n |
| leaf-list | 0..n |
| list | 0..n |
+---------------+-------------+
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.
It is also possible to add additional data nodes by using the
according leaf, leaf-list, list, and choice statements etc. as sub-
statements of the instance declaration. This is an in-place
augmentation of the used complex type confined to this complex type
instantiation (see also section "Using complex types" for more
Linowski, et al. Expires January 13, 2011 [Page 17]
Internet-Draft YANG Language Abstractions July 2010
details about augmenting complex types).
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. In addition, 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.
+---------------+-------------+
| 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 |
| anyxml | 0..n |
| choice | 0..n |
| container | 0..n |
| instance | 0..n |
| instance-list | 0..n |
| leaf | 0..n |
| leaf-list | 0..n |
| list | 0..n |
+---------------+-------------+
Table 3: instance-list's substatements
In case the instance list represents configuration data, 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.
Linowski, et al. Expires January 13, 2011 [Page 18]
Internet-Draft YANG Language Abstractions July 2010
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
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.
Instance child nodes are encoded as subelements to the instance XML
Linowski, et al. Expires January 13, 2011 [Page 19]
Internet-Draft YANG Language Abstractions July 2010
element, in the same order as they are defined within the complex
type statement. Child nodes of an extending complex type follow the
child nodes of the extended complex type. As such, the XML encoding
of lists is similar to the encoding of containers and lists. .
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, preceding all
other nodes defined in the same complex type. The type of actual
complex type instance is encoded in a type element that is put in
front of all instance child elements as 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 members that have been
declared in the according complex type definition. The "ct:type"
element is inserted for each type in the extension chain to the
actual type of the instance (most specific last). Each type name
includes its corresponding namespace.
The type of a complex type instance MUST be encoded in the reply to
NETCONF <get> and <get-config> operations, and in the payload of
NETCONF <edit-config> operation if the operation is "create" or
"replace". The type of the instance MUST also be specified in case
<copy-config> is used to export a configuration to a resource
addressed with an URI. 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 <rpc-error> element is
returned with an <error-tag> 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 <rpc-error> element is
returned with an <error-tag> value of "missing-type".
The type MUST NOT be specified in case the operation is "delete".
Linowski, et al. Expires January 13, 2011 [Page 20]
Internet-Draft YANG Language Abstractions July 2010
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 modeling for depending on the support status of complex
types in a NETCONF server. A NETCONF server that supports the
complex types modeling 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 <hello> message as
described in section 5.6.4 in [YANG].
<CODE BEGINS>
module complex-types {
namespace "urn:ietf:params:xml:ns:yang:complex-types";
prefix "ct";
organization
"NETMOD WG";
contact
"Editor: Bernd Linowski
<bernd.linowski@ext.nsn.com>
Editor: Mehmet Ersue
<mehmet.ersue@nsn.com>
Editor: Siarhei Kuryla
<s.kuryla@jacobs-university.de>";
description
"YANG extensions for complex types and typed instance
identifiers.
Copyright (c) 2010 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
Linowski, et al. Expires January 13, 2011 [Page 21]
Internet-Draft YANG Language Abstractions July 2010
// RFC Ed.: replace XXXX with actual RFC number and remove this note
revision 2010-07-12 {
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., abstract 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
complex type";
reference "chapter 2.4., instance-list extension statement";
argument ct-instance-identifier {
yin-element true;
Linowski, et al. Expires January 13, 2011 [Page 22]
Internet-Draft YANG Language Abstractions July 2010
}
}
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 server supports
complex types and instance identifiers.";
}
}
<CODE ENDS>
2.10. Example Model for Complex Types
The example model below shows how complex types can be used to
represent physical equipment in a vendor independent, abstract way.
It reuses the complex types defined in the physical resource model in
section 1.5.1.
Linowski, et al. Expires January 13, 2011 [Page 23]
Internet-Draft YANG Language Abstractions July 2010
<CODE BEGINS>
module hw {
namespace "urn:org:example:xml:ct:hw";
prefix "hw";
import complex-types {prefix "ct"; }
import udmcore {prefix "uc"; }
// Holder types
ct:complex-type Slot {
ct:extends uc:EquipmentHolder;
leaf slotNumber { type uint16; config false; }
// ...
}
ct:complex-type Chassis {
ct:extends uc:EquipmentHolder;
leaf numberOfChassisSlots { type uint32; config false; }
// ..
}
// Equipment types
ct:complex-type Card {
ct:extends uc:Equipment;
leaf position { type uint32; mandatory true; }
leaf slotsRequired {type unit32; }
}
// Root Element
ct:instance hardware { type uc:ManagedHardware; }
} // hw module
<CODE ENDS>
2.11. NETCONF Payload Example
Following example shows the payload of a reply to a NETCONF <get>
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
Linowski, et al. Expires January 13, 2011 [Page 24]
Internet-Draft YANG Language Abstractions July 2010
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.
Linowski, et al. Expires January 13, 2011 [Page 25]
Internet-Draft YANG Language Abstractions July 2010
<hardware>
<ct:type>uc:BasicObject</ct:type>
<distinguishedName>/R-T31/CH-2</distinguishedName>
<globalId>6278279001</globalId>
<ct:type>uc:Resource</ct:type>
<ct:type>uc:PhysicalResource</ct:type>
<otherIdentifier>Rack R322-1</otherIdentifier>
<serialNumber>R-US-3276279a</serialNumber>
<ct:type>uc:Hardware</ct:type>
<ct:type>uc:ManagedHardware</ct:type>
<ct:type>hw:EquipmentHolder</ct:type>
<equipmentHolder>
<ct:type>uc:BasicObject</ct:type>
<distinguishedName>/R-T31/CH-2/SL-1</distinguishedName>
<globalId>548872003</globalId>
<ct:type>uc:Resource</ct:type>
<ct:type>uc:PhysicalResource</ct:type>
<otherIdentifier>CU-Slot</otherIdentifier>
<serialNumber>T-K4733890x45</serialNumber>
<ct:type>uc:Hardware</ct:type>
<ct:type>uc:ManagedHardware</ct:type>
<ct:type>uc:EquipmentHolder</ct:type>
<equipment>
<ct:type>uc:BasicObject</ct:type>
<distinguishedName>/R-T31/CH-2/SL-1/C-3</distinguishedName>
<globalId>89772001</globalId>
<ct:type>uc:Resource</ct:type>
<ct:type>uc:PhysicalResource</ct:type>
<otherIdentifier>ATM-45252</otherIdentifier>
<serialNumber>A-778911-b</serialNumber>
<ct:type>uc:Hardware</ct:type>
<ct:type>uc:ManagedHardware</ct:type>
<ct:type>uc:Equipment</ct:type>
<installed>true</installed>
<version>A2</version>
<redundancy>1</redundancy>
<ct:type>hw:Card</ct:type>
<usedSlots>1</usedSlots>
</equipment>
<ct:type>hw:Slot</ct:type>
<slotNumber>1</slotNumber>
</equitmentHolder>
<ct:type>hw:Chassis</ct:type>
<numberOfChassisSlots>6</numberOfChassisSlots>
// ...
</hardware>
Linowski, et al. Expires January 13, 2011 [Page 26]
Internet-Draft YANG Language Abstractions July 2010
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:
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 an "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 Type 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.
Linowski, et al. Expires January 13, 2011 [Page 27]
Internet-Draft YANG Language Abstractions July 2010
o A leaf, anyxml, or choice node may have a "mandatory true"
statement. However, 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.
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 is only allowed if 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]).
ct:complex-type Chassis {
ct:extends EquipmentHolder;
container chassisInfo {
config false;
leaf numberOfSlots { type uint16; }
leaf occupiedSlots { type uint16; }
leaf height {type unit16;}
leaf width {type unit16;}
}
}
ct:instance-list chassis {
type Chassis;
augment "chassisInfo" {
leaf modelId { type string; }
}
}
Linowski, et al. Expires January 13, 2011 [Page 28]
Internet-Draft YANG Language Abstractions July 2010
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
the same name from the same namespace in the target node.
To achieve less complex modeling this document proposes the
augmentation of complex type instances without recursion.
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
<hello> 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
target of deviations.
In the example below, client applications are informed that the leaf
"occupiedSlots" is not supported in the top-level chassis. However,
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;
}
Linowski, et al. Expires January 13, 2011 [Page 29]
Internet-Draft YANG Language Abstractions July 2010
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.
A typed instance identifier represents a reference to an instance 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 specifies the complex type of
the instance referred by the instance-identifier. The referred
instance may also instantiate any complex type that extends the
specified 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 January 13, 2011 [Page 30]
Internet-Draft YANG Language Abstractions July 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;
}
}
Below is the XML encoding of an element named "link" of type
"PhysicalLink":
<link>
<objectId>FTCL-771</objectId>
<media>Fiber</media>
<connectedPort>/hw:hardware[objectId='R-11']
/hw:equipment[objectId='AT22']/hw:port[objectId='P12']
</connectedPort>
<connectedPort>/hw:hardware[objectId='R-42]
/hw:equipment[objectId='AT30']/hw:port[objectId='P3']
</connectedPort>
<serialNumeber>F-7786828</serialNumber>
<commonName>FibCon 7</commonName>
</link>
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 January 13, 2011 [Page 31]
Internet-Draft YANG Language Abstractions July 2010
URI: urn:ietf:params:xml:ns:yang:complex-types
URI: urn:ietf:params:xml:ns:yang:complex-type-instance
Registrant Contact: The NETMOD 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
The YANG module "complex-types" in this memo defines YANG extensions
for Complex-types and Typed Instance Identifiers as new language
statements. As such it does not define data nodes.
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
Linowski, et al. Expires January 13, 2011 [Page 32]
Internet-Draft YANG Language Abstractions July 2010
NETCONF", draft-ietf-netmod-yang-13 (work in progress),
June 2010.
7.2. Informative References
[IPFIXCONF] Muenz, G., "Configuration Data Model for IPFIX and
PSAMP", draft-ietf-ipfix-configuration-model-06 (work in
progress), July 2010.
[Libsmi] Kuryla, S., "Libsmi Extension for Complex Types",
April 2010,
<http://www.ibr.cs.tu-bs.de/projects/libsmi/>.
[Pyang] Bjorklund, M., "An extensible YANG validator and
converter", December 2008,
<http://code.google.com/p/pyang/>.
[Pyang-ct] Kuryla, S., "Pyang Extension for Complex Types",
April 2010, <http://code.google.com/p/pyang-ct/>.
[RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)",
August 2005.
[SID V8] Tele Management Forum, "GB922-Information Framework
(SID) Solution Suite, Release 8.0", July 2008, < http:/
/www.tmforum.org/DocumentsInformation/
GB922InformationFramework/35499/article.html>.
[UDM] NSN, "Unified Data Model SID Compliance Statement",
May 2010, <http://www.tmforum.org/InformationFramework/
NokiaSiemensNetworks/8815/home.html>.
Appendix A. Change Log
A.1. 02-03
o Added an example based on the physical resource modeling concepts
of SID. A simplified class diagram and an excerpt of an according
YANG module were added in the introduction section.
o Changed the example YANG module in the NETCONF payload section to
be based on the physical resource types defined in the added
physical resource model.
o A second example shows how Entity MIB entries can be modeled as
physical resources. The example includes a class diagram and an
according YANG module excerpt.
Linowski, et al. Expires January 13, 2011 [Page 33]
Internet-Draft YANG Language Abstractions July 2010
o The complete YANG modules for both examples were added into the
appendix.
o Changed the complex type encoding rules.
o Updated the NETCONF payload example the changed type encoding
rules and the changed example module.
o Changed the augmentation rules for complex types. Instead of
using "." as argument in the augment statement, instance and
instance-list statement may now contain additional data node
statements. The substatement tables for the instance and
instance-list statements were updated accordingly.
o Minor updates in the text and examples.
A.2. 01-02
o It is no longer allowed to use the "config" statement inside a
complex type definition.
o Complex type can now be defined where a grouping can be defined.
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.
A.3. 00-01
o Transformed proposed new YANG statements to YANG extension
statements (complex-type, element, extends, abstract).
o Renamed statement "element" to the extension statement "instance"
in order to avoid confusion with XML payload elements.
Linowski, et al. Expires January 13, 2011 [Page 34]
Internet-Draft YANG Language Abstractions July 2010
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 B. YANG modules for the Physical Network Resource Information
Model and Hardware Entities
YANG module for the Physical Network Resource Information Model:
<CODE BEGINS>
module udmcore {
namespace "urn:com:nsn:udmcore";
prefix "udm";
import yang-types {prefix "yt";}
import complex-types {prefix "ct";}
ct:complex-type BasicObject {
ct:abstract true;
key "distinguishedName";
leaf globalId {type int64;}
leaf distinguishedName {type string; mandatory true;}
}
ct:complex-type ManagedObject {
ct:extends BasicObject;
ct:abstract true;
leaf instance {type string;}
leaf objectState {type int32;}
leaf release {type string;}
}
ct:complex-type Resource {
Linowski, et al. Expires January 13, 2011 [Page 35]
Internet-Draft YANG Language Abstractions July 2010
ct:extends ManagedObject;
ct:abstract true;
leaf usageState {type int16;}
leaf managementMethodSupported {type string;}
leaf managementMethodCurrent {type string;}
leaf managementInfo {type string;}
leaf managementDomain {type string;}
leaf version {type string;}
leaf entityIdentification {type string;}
leaf desription {type string;}
leaf rootEntityType {type string;}
}
ct:complex-type LogicalResource {
ct:extends Resource;
ct:abstract true;
leaf lrStatus {type int32;}
leaf serviceState {type int32;}
leaf isOperational {type boolean;}
}
ct:complex-type PhysicalResource {
ct:extends Resource;
ct:abstract true;
leaf manufactureDate {type string;}
leaf otherIdentifier {type string;}
leaf powerState {type int32;}
leaf serialNumber {type string;}
leaf versionNumber {type string;}
}
ct:complex-type Hardware {
ct:extends PhysicalResource;
ct:abstract true;
leaf width {type string;}
leaf height {type string;}
leaf depth {type string;}
leaf measurementUnits {type int32;}
leaf weight {type string;}
leaf weightUnits {type int32;}
leaf-list physicalLink {
type instance-identifier {
ct:instance-type PhysicalLink;
}
}
Linowski, et al. Expires January 13, 2011 [Page 36]
Internet-Draft YANG Language Abstractions July 2010
ct:instance-list containedHardware {
ct:instance-type Hardware;
}
ct:instance-list physicalConnector {
ct:instance-type PhysicalConnector;
}
}
ct:complex-type PhysicalLink {
ct:extends PhysicalResource;
leaf isWiereless {type boolean;}
leaf currentLength {type string;}
leaf maximumLength {type string;}
leaf mediaType {type int32;}
leaf-list hardware {
type instance-identifier {
ct:instance-type Hardware;
}
}
}
ct:complex-type ManagedHardware {
ct:extends Hardware;
leaf additionalinfo {type string;}
leaf physicalAlarmReportingEnabled {type boolean;}
leaf pyhsicalAlarmStatus {type int32;}
leaf coolingRequirements {type string;}
leaf hardwarePurpose {type string;}
leaf isPhysicalContainer {type boolean;}
}
ct:complex-type AuxiliaryComponent {
ct:extends ManagedHardware;
ct:abstract true;
}
ct:complex-type PhysicalPort {
ct:extends ManagedHardware;
leaf portNumber {type int32;}
leaf duplexMode {type int32;}
leaf ifType {type int32;}
leaf vendorPortName {type string;}
}
Linowski, et al. Expires January 13, 2011 [Page 37]
Internet-Draft YANG Language Abstractions July 2010
ct:complex-type PhysicalConnector {
ct:extends Hardware;
leaf location {type string;}
leaf cableType {type int32;}
leaf gender {type int32;}
leaf inUse {type boolean;}
leaf pinDescription {type string;}
leaf typeOfConnector {type int32;}
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;
leaf installStatus {type int32;}
leaf expectedEquipmentType {type string;}
leaf installedEquipmentType {type string;}
leaf installedVersion {type string;}
leaf redundancy {type int32;}
leaf vendorName {type string;}
leaf dateOfLastService {type yt:date-and-time;}
leaf interchangeability {type string;}
leaf identificationCode {type string;}
ct:instance-list equipment {
ct:instance-type Equipment;
}
}
ct:complex-type EquipmentHolder {
ct:extends ManagedHardware;
leaf vendorName {type string;}
leaf locationName {type string;}
leaf dateOfLastService {type yt:date-and-time;}
leaf partNumber {type string;}
leaf availabilityStatus {type int16;}
leaf nameFromPlanningSystem {type string;}
leaf modelNumber {type string;}
leaf acceptableEquipmentList {type string;}
Linowski, et al. Expires January 13, 2011 [Page 38]
Internet-Draft YANG Language Abstractions July 2010
leaf isSolitaryHolder {type boolean;}
leaf holderStatus {type int16;}
leaf interchangeability {type string;}
leaf equipmentHolderSpecificType {type string; }
leaf position {type string;}
leaf atomicCompositeType {type int16;}
leaf uniquePhysical {type boolean;}
leaf physicalDescription {type string;}
leaf serviceApproach {type string;}
leaf mountingOptions {type int32;}
leaf cableManagementStrategy {type string;}
leaf isSecureHolder {type boolean;}
ct:instance-list equipment {
ct:instance-type Equipment;
}
ct:instance-list equipmentHolder {
ct:instance-type EquipmentHolder;
}
}
// ... other resource complex types ...
}
<CODE ENDS>
YANG module for Hardware Entities Model:
<CODE BEGINS>
module hardware-entities {
namespace "urn:com:nsn:hardware-entities";
prefix "hwe";
import yang-types {prefix "yt";}
import complex-types {prefix "ct";}
import udmcore {prefix "uc";}
grouping PhysicalEntityProperties {
leaf hardwareRev {type string; }
leaf firmwareRev {type string; }
leaf softwareRev {type string; }
leaf serialNum {type string; }
leaf mfgName {type string; }
Linowski, et al. Expires January 13, 2011 [Page 39]
Internet-Draft YANG Language Abstractions July 2010
leaf modelName {type string; }
leaf alias {type string; }
leaf ssetID{type string; }
leaf isFRU {type boolean; }
leaf mfgDate {type yt:date-and-time; }
leaf-list uris {type string; }
}
// Physical entities representing equipment
ct:complex-type Module {
ct:extends uc:Equipment;
description "Complex type representing module entries
(entPhysicalClass = module(9)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
ct:complex-type Backplane {
ct:extends uc:Equipment;
description "Complex type representing backplane entries
(entPhysicalClass = backplane(4)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
// Physical entities representing auxiliray hardware components
ct:complex-type PowerSupply {
ct:extends uc:AuxiliaryComponent;
description "Complex type representing power supply entries
(entPhysicalClass = powerSupply(6)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
ct:complex-type Fan {
ct:extends uc:AuxiliaryComponent;
description "Complex type representing fan entries
(entPhysicalClass = fan(7)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
ct:complex-type Sensor {
ct:extends uc:AuxiliaryComponent;
description "Complex type representing sensor entries
(entPhysicalClass = sensor(8)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
Linowski, et al. Expires January 13, 2011 [Page 40]
Internet-Draft YANG Language Abstractions July 2010
// 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;
}
ct:complex-type Container {
ct:extends uc:EquipmentHolder;
description "Complex type representing container entries
(entPhysicalClass = container(5)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
ct:complex-type Stack {
ct:extends uc:EquipmentHolder;
description "Complex type representing stack entries
(entPhysicalClass = stack(11)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
// Other kinds of physical entities
ct:complex-type Port {
ct:extends uc:PhysicalPort;
description "Complex type representing port entries
(entPhysicalClass = port(10)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
ct:complex-type CPU {
ct:extends uc:Hardware;
description "Complex type representing cpu entries
(entPhysicalClass = cpu(12)) in entPhysicalTable";
uses PhysicalEntityProperties;
}
}
<CODE ENDS>
Appendix C. Example YANG Module for the IPFIX/PSAMP Model
Linowski, et al. Expires January 13, 2011 [Page 41]
Internet-Draft YANG Language Abstractions July 2010
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.
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).
Linowski, et al. Expires January 13, 2011 [Page 42]
Internet-Draft YANG Language Abstractions July 2010
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
<CODE BEGINS>
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 2010-07-12 {
description "Version of draft-ietf-ipfix-configuration-model-02
modeled with complex types and typed instance
identifiers.";
}
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.";
}
Linowski, et al. Expires January 13, 2011 [Page 43]
Internet-Draft YANG Language Abstractions July 2010
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.";
}
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
Linowski, et al. Expires January 13, 2011 [Page 44]
Internet-Draft YANG Language Abstractions July 2010
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 {
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.";
}
Linowski, et al. Expires January 13, 2011 [Page 45]
Internet-Draft YANG Language Abstractions July 2010
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;
}
}
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).";
}
Linowski, et al. Expires January 13, 2011 [Page 46]
Internet-Draft YANG Language Abstractions July 2010
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 {
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;
Linowski, et al. Expires January 13, 2011 [Page 47]
Internet-Draft YANG Language Abstractions July 2010
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;
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;
Linowski, et al. Expires January 13, 2011 [Page 48]
Internet-Draft YANG Language Abstractions July 2010
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
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;
Linowski, et al. Expires January 13, 2011 [Page 49]
Internet-Draft YANG Language Abstractions July 2010
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.";
}
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 {
Linowski, et al. Expires January 13, 2011 [Page 50]
Internet-Draft YANG Language Abstractions July 2010
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;
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;
Linowski, et al. Expires January 13, 2011 [Page 51]
Internet-Draft YANG Language Abstractions July 2010
}
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.
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
Linowski, et al. Expires January 13, 2011 [Page 52]
Internet-Draft YANG Language Abstractions July 2010
// 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;
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;
Linowski, et al. Expires January 13, 2011 [Page 53]
Internet-Draft YANG Language Abstractions July 2010
}
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;
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
Linowski, et al. Expires January 13, 2011 [Page 54]
Internet-Draft YANG Language Abstractions July 2010
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 {
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
Linowski, et al. Expires January 13, 2011 [Page 55]
Internet-Draft YANG Language Abstractions July 2010
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.";
}
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;
Linowski, et al. Expires January 13, 2011 [Page 56]
Internet-Draft YANG Language Abstractions July 2010
}
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 {
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";
Linowski, et al. Expires January 13, 2011 [Page 57]
Internet-Draft YANG Language Abstractions July 2010
}
}
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.";
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 {
Linowski, et al. Expires January 13, 2011 [Page 58]
Internet-Draft YANG Language Abstractions July 2010
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";
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 {
Linowski, et al. Expires January 13, 2011 [Page 59]
Internet-Draft YANG Language Abstractions July 2010
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;
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;
}
Linowski, et al. Expires January 13, 2011 [Page 60]
Internet-Draft YANG Language Abstractions July 2010
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;
}
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;
Linowski, et al. Expires January 13, 2011 [Page 61]
Internet-Draft YANG Language Abstractions July 2010
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.";
}
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 {
Linowski, et al. Expires January 13, 2011 [Page 62]
Internet-Draft YANG Language Abstractions July 2010
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.";
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
Linowski, et al. Expires January 13, 2011 [Page 63]
Internet-Draft YANG Language Abstractions July 2010
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; }
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";
}
Linowski, et al. Expires January 13, 2011 [Page 64]
Internet-Draft YANG Language Abstractions July 2010
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;
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;
Linowski, et al. Expires January 13, 2011 [Page 65]
Internet-Draft YANG Language Abstractions July 2010
}
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;
type SelectionProcess;
}
ct:instance-list cache {
if-feature meter;
type Cache;
}
ct:instance-list exportingProcess {
if-feature exporter;
type ExportingProcess;
}
}
}
Linowski, et al. Expires January 13, 2011 [Page 66]
Internet-Draft YANG Language Abstractions July 2010
<CODE ENDS>
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 January 13, 2011 [Page 67]
