idnits 2.17.1 draft-linowski-netmod-yang-abstract-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 10, 2010) is 4886 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-11) exists of draft-ietf-ipfix-configuration-model-08 -- Obsolete informational reference (is this intentional?): RFC 4133 (Obsoleted by RFC 6933) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Linowski 3 Internet-Draft TCS/Nokia Siemens Networks 4 Intended status: Experimental M. Ersue 5 Expires: June 13, 2011 Nokia Siemens Networks 6 S. Kuryla 7 360 Treasury Systems 8 December 10, 2010 10 Extending YANG with Language Abstractions 11 draft-linowski-netmod-yang-abstract-05 13 Abstract 15 YANG - the NETCONF Data Modeling Language - supports modeling of a 16 tree of data elements that represent the configuration and runtime 17 status of a particular network element managed via NETCONF. This 18 memo suggests to enhance YANG with supplementary modeling features 19 and language abstractions with the aim to improve the model 20 extensibility and reuse. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on June 13, 2011. 39 Copyright Notice 41 Copyright (c) 2010 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 59 1.3. Modeling Improvements with Language Abstractions . . . . . 6 60 1.4. Design Approach . . . . . . . . . . . . . . . . . . . . . 8 61 1.5. Modeling Resource Models with YANG . . . . . . . . . . . . 8 62 1.5.1. Example of a Physical Network Resource Model . . . . . 8 63 1.5.2. Modeling Entity MIB Entries as Physical Resources . . 13 64 2. Complex Types . . . . . . . . . . . . . . . . . . . . . . . . 16 65 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 16 66 2.2. complex-type extension statement . . . . . . . . . . . . . 16 67 2.3. instance extension statement . . . . . . . . . . . . . . . 18 68 2.4. instance-list extension statement . . . . . . . . . . . . 19 69 2.5. extends extension statement . . . . . . . . . . . . . . . 20 70 2.6. abstract extension statement . . . . . . . . . . . . . . . 20 71 2.7. XML Encoding Rules . . . . . . . . . . . . . . . . . . . . 21 72 2.8. Type Encoding Rules . . . . . . . . . . . . . . . . . . . 21 73 2.9. Extension and Feature Definition Module . . . . . . . . . 22 74 2.10. Example Model for Complex Types . . . . . . . . . . . . . 25 75 2.11. NETCONF Payload Example . . . . . . . . . . . . . . . . . 26 76 2.12. Update Rules for Modules Using Complex Types . . . . . . . 29 77 2.13. Using Complex Types . . . . . . . . . . . . . . . . . . . 29 78 2.13.1. Overriding Complex Type Data Nodes . . . . . . . . . . 29 79 2.13.2. Augmenting Complex Types . . . . . . . . . . . . . . . 30 80 2.13.3. Controlling the Use of Complex Types . . . . . . . . . 31 81 3. Typed Instance Identifier . . . . . . . . . . . . . . . . . . 32 82 3.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 32 83 3.2. instance-type extension statement . . . . . . . . . . . . 32 84 3.3. Typed Instance Identifier Example . . . . . . . . . . . . 32 85 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 86 5. Security Considerations . . . . . . . . . . . . . . . . . . . 34 87 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 34 88 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 89 7.1. Normative References . . . . . . . . . . . . . . . . . . . 34 90 7.2. Informative References . . . . . . . . . . . . . . . . . . 35 91 Appendix A. YANG Modules for Physical Network Resource Model 92 and Hardware Entities Model . . . . . . . . . . . . . 35 93 Appendix B. Example YANG Module for the IPFIX/PSAMP Model . . . . 42 94 B.1. Modeling Improvements for the IPFIX/PSAMP Model with 95 Complex types and Typed instance identifiers . . . . . . . 42 96 B.2. IPFIX/PSAMP Model with Complex Types and Typed 97 Instance Identifiers . . . . . . . . . . . . . . . . . . . 43 98 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 76 99 C.1. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 76 100 C.2. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 76 101 C.3. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 76 102 C.4. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 77 103 C.5. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 77 105 1. Introduction 107 YANG - the NETCONF Data Modeling Language [RFC6020] - supports 108 modeling of a tree of data elements that represent the configuration 109 and runtime status of a particular network element managed via 110 NETCONF. This document defines extensions for the modeling language 111 YANG as new language statements, which introduce language 112 abstractions to improve the model extensibility and reuse. The 113 document reports from modeling experience in the telecommunication 114 industry and gives model examples from an actual network management 115 system to highlight the value of proposed language extensions, 116 especially class inheritance and recursiveness. The language 117 extensions defined in this document have been implemented with two 118 open source tools. These tools have been used to validate the model 119 examples through the document. After successful usage this 120 experimental specification can be republished at IETF as a proposed 121 standard possibly as part of a future version of YANG. 123 1.1. Key Words 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 127 "OPTIONAL" in this document are to be interpreted as described in BCP 128 14, [RFC2119]. 130 1.2. Motivation 132 o Many systems today have a management information base that in 133 effect is organized as a tree build of recursively nested 134 container nodes. For example, the physical resources in the 135 ENTITY-MIB conceptually form a containment tree. The index 136 entPhysicalContainedIn points to the containing entity in a flat 137 list. The ability to represent nested, recursive data structures 138 of arbitrary depth would enable the representation of the primary 139 containment hierarchy of physical entities as a node tree in the 140 server MIB and in the NETCONF payload. 142 o A manager scanning the network in order to update the state of an 143 inventory management system might be only interested in data 144 structures that represent a specific type of hardware. Such a 145 manager would then look for entities that are of this specific 146 type, including those that are an extension or specialization of 147 this type. To support this use case, it is helpful to bear the 148 corresponding type information within the data structures, which 149 describe the network element hardware. 151 o A system that is managing network elements is concerned e.g. with 152 managed objects of type "plug-in modules" that have a name, a 153 version and an activation state. In this context, it is useful to 154 define the "plug-in module" as a concept that is supposed to be 155 further detailed and extended by additional concrete model 156 elements. In order to realize such a system, it is worth to model 157 abstract entities, which enable reuse and ease concrete 158 refinements of that abstract entity in a second step. 160 o As particular network elements have specific type of components 161 that need to be managed (OS images, plug-in modules, equipment, 162 etc.), it should be possible to define concrete types, which 163 describe the managed object precisely. By using type-safe 164 extensions of basic concepts a system in the manager role can 165 safely and explicitly determine that e.g. the "equipment" is 166 actually of type "network card". 168 o Currently different SDOs are working on the harmonization of their 169 management information models. Often a model mapping or 170 transformation between systems becomes necessary. The 171 harmonization of the models is done e.g. by mapping of the two 172 models on object level or integrating an object hierarchy into an 173 existing information model. Extending YANG with language 174 abstractions can simplify on the one hand the adoption of IETF 175 resource models by other SDOs and facilitate the alignment with 176 other SDO's resource models (e.g. TM Forum SID). The proposed 177 YANG extensions can on the other hand enable the utilization of 178 YANG modeling language in other SDOs, which are used to model 179 complex management systems in a top-down manner and use high-level 180 language features frequently. 182 This memo specifies additional modeling features for the YANG 183 language in the area of structured model abstractions, typed 184 references as well as recursive data structures and discusses how 185 these new features can improve the modeling capabilities of YANG. 187 Section 1.5.1 contains a physical resource model, which deals with 188 some of the modeling challenges illustrated above. Section 1.5.2 189 gives an example, which uses the base classes defined in the physical 190 resource model and derives a model for physical entities defined in 191 Entity MIB". 193 1.3. Modeling Improvements with Language Abstractions 195 As an enhancement to YANG 1.0 Complex Types and Typed Instance 196 Identifiers provide different technical improvements on modeling 197 level: 199 o In case the model of a system that should be managed with NETCONF 200 makes use of inheritance, complex types enable an almost one-to- 201 one mapping between the classes in the original model and the YANG 202 module. 204 o Typed instance identifiers allow representing associations between 205 the concepts in a type-safe way to prevent type errors caused by 206 referring to data nodes of incompatible types. This avoids 207 referring to a particular location in the MIB, which is not 208 mandated by the domain model. 210 o Complex types allow defining complete, self-contained type 211 definitions. It is not necessary to explicitly add a key 212 statement to lists, which use a grouping defining the data nodes. 214 o Complex types simplify concept refinement by extending a base 215 complex type and make it superfluous to represent concept 216 refinements with workarounds such as huge choice-statements with 217 complex branches. 219 o Abstract complex types ensure correct usage of abstract concepts 220 by enforcing the refinement of common set of properties before 221 instantiation. 223 o Complex types allow defining recursive structures. This enables 224 to represent complex structures of arbitrary depth by nesting 225 instances of basic complex types that may contain themselves. 227 o Complex types avoid introducing meta-data types (e.g. type code 228 enumerations) and meta-data leafs (e.g. leafs containing a type 229 code) to indicate, which concrete type of object is actually 230 represented by a generic container in the MIB. This also avoids 231 to explicitly rule out illegal use of sub-type specific properties 232 in generic containers. 234 o Complex type instances include the type information in the NETCONF 235 payload. This allows to determine the actual type of an instance 236 during the NETCONF payload parsing and avoids the use of 237 additional leafs in the model, which provide the type information 238 as content. 240 o Complex types may be declared explicitly as optional features, 241 which is not possible when the actual type of an entity 242 represented by a generic container is indicated with a type code 243 enumeration. 245 Appendix B: 'Example YANG Module for the IPFIX/PSAMP Model' lists 246 technical improvements for modeling with Complex Types and Typed 247 Instance Identifiers and exemplifies the usage of the proposed YANG 248 extensions based on the IPFIX/PSAMP configuration model in 249 [IPFIXCONF]. 251 1.4. Design Approach 253 The proposed additional features for YANG in this memo are designed 254 to reuse existing YANG statements whenever possible. Additional 255 semantics is expressed by an extension that is supposed to be used as 256 a substatement of an existing statement. 258 The proposed features don't change the semantics of models that are 259 valid with respect to the YANG specification [RFC6020]. 261 1.5. Modeling Resource Models with YANG 263 1.5.1. Example of a Physical Network Resource Model 265 The diagram below depicts a portion of an information model for 266 manageable network resources used in an actual network management 267 system. 269 Note: The referenced model (UDM, Unified Data Model) is based on key 270 resource modelling concepts from [SID V8] and is compliant with 271 selected parts of SID Resource Abstract Business Entities domain 272 ([UDM]). 274 The class diagram in Figure 1 and the according YANG module excerpt 275 focus on basic resource ("Resource" and the distinction between 276 logical- and physical resources) and hardware abstractions 277 ("Hardware", "Equipment", and "EquipmentHolder"). Some class 278 attributes were omitted to achieve decent readability. 280 +--------+ 281 |Resource| 282 +--------+ 283 /\ /\ 284 -- -- 285 | | 286 | +---------------+ 287 | |LogicalResource| 288 | +---------------+ 289 | 290 | 291 | 292 | +--------+ 293 | |Physical| +-----------+ 294 '-|Resource|<|-+-|PhysicalLink| 295 +---- ---+ | +------------+ 296 | |0..* physicalLink 297 | | 298 | | equipment 299 | | Holder 300 | | 0..* 301 | | +-------+ 302 | |0..* hardware | | 303 | +--------+ +---------------+ +---------+ | 304 '-|Hardware|<|-+-|ManagedHardware|<|-+-|Equipment|<>--+ 305 +--------+ | +---------------+ | | Holder |0..1 306 <> | | +---------+ 307 0..1| | | <> 308 | | | |0..* equipment 309 | | | | Holder 310 | | | | 311 | | | |0..* equipment 312 | | | | 313 | | | | equipment 314 | | | | 0..* 315 | | | | +-------+ 316 | | | | | | 317 | | | +---------+ | 318 | | '-|Equipment|<>--+ 319 | | +---------+0..1 320 | | compositeEquipment 321 | | 322 | | +-----------------+ 323 | '-|PhysicalConnector|----+0..* source 324 '----------+-----------------+ | Physical 325 physicalConnector 0..* | | Connector 326 | | 327 +-----------+ 328 0..* targetPhysicalConnector 330 Figure 1: Physical Network Resource Model 332 Since this model is an abstraction of network element specific MIB 333 topologies, modeling it with YANG creates some challenges. Some of 334 these challenges and how they can be addressed with complex types are 335 explained below: 337 o Modeling of abstract concepts: Classes like "Resource" represent 338 concepts that primarily serve as a base class for derived classes. 339 With complex types, such an abstract concept could be represented 340 by an abstract complex type (see "complex-type extension 341 statement" and "abstract extension statement"). 343 o Class Inheritance: Information models for complex management 344 domains often use class inheritance to create specialized classes 345 like "PhysicalConnector" from a more generic base class (here 346 "Hardware"), which itself might inherit from another base class 347 ("PhysicalResource") etc. Complex types allow creating enhanced 348 versions of an existing (abstract or concrete) base type via an 349 extension (see "extends extension statement"). 351 o Recursive containment: In order to specify containment hierarchies 352 models frequently contain different aggregation associations, in 353 which the target (contained element) is either the containing 354 class itself or a base class of the containing class. In the 355 model above, the recursive containment of "EquipmentHolder" is an 356 example of such a relationship (see the description for the 357 "complex-type EquipmentHolder" in the example model "udmcore" 358 below). 360 o Complex types support such a containment by using a complex type 361 (or one of its ancestor types) as type of an instance or instance 362 list that is part of its definition (see "instance(-list) 363 extension statement"). 365 o Reference relationships: A key requirement on large models for 366 network domains with many related managed objects is the 367 association between classes that represent an essential 368 relationship between instances of such a class. For example, the 369 relationship between "PhysicalLink" and "Hardware" tells which 370 physical link is connecting which hardware resources. It is 371 important to notice that this kind of relationships do not mandate 372 any particular location of the two connected hardware instances in 373 any MIB module. Such containment agnostic relationships can be 374 represented by a typed instance identifier that embodies one 375 direction of such an association (see "Typed instance 376 identifiers"). 378 The YANG module excerpt below shows how the challenges listed above 379 can be addressed by the Complex Types extension (module import prefix 380 "ct:"). The complete YANG module for the physical resource model in 381 Figure 1 can be found in Appendix A: 'YANG Modules for Physical 382 Network Resource Model and Hardware Entities Model'. 384 Note: The YANG extensions proposed in this document have been 385 implemented as the open source tools "Pyang Extension for Complex 386 Types" [Pyang-ct], [Pyang] and "Libsmi Extension for Complex Types" 387 [Libsmi]. All model examples in the document have been validated 388 with the tools Pyang-ct and Libsmi. 390 392 module udmcore { 394 namespace "http://example.com/udmcore"; 395 prefix "udm"; 397 import ietf-complex-types {prefix "ct"; } 399 // Basic complex types... 401 ct:complex-type PhysicalResource { 402 ct:extends Resource; 403 ct:abstract true; 404 // ... 405 leaf serialNumber { 406 type string; 407 description "'Manufacturer-allocated part number' as 408 defined in SID. E.g. the part number of a fiber link 409 cable."; 410 } 411 } 413 ct:complex-type Hardware { 414 ct:extends PhysicalResource; 415 ct:abstract true; 416 // ... 417 leaf-list physicalLink { 418 type instance-identifier {ct:instance-type PhysicalLink;} 419 } 420 ct:instance-list containedHardware { 421 ct:instance-type Hardware; 422 } 423 ct:instance-list physicalConnector { 424 ct:instance-type PhysicalConnector; 425 } 426 } 428 ct:complex-type PhysicalLink { 429 ct:extends PhysicalResource; 430 // ... 431 leaf-list hardware { 432 type instance-identifier {ct:instance-type Hardware;} 433 } 434 } 435 ct:complex-type ManagedHardware { 436 ct:extends Hardware; 437 ct:abstract true; 438 // ... 439 } 441 ct:complex-type PhysicalConnector { 442 ct:extends Hardware; 443 leaf location {type string;} 444 // ... 445 leaf-list sourcePhysicalConnector { 446 type instance-identifier {ct:instance-type PhysicalConnector;} 447 } 448 leaf-list targetPhysicalConnector { 449 type instance-identifier {ct:instance-type PhysicalConnector;} 450 } 451 } 453 ct:complex-type Equipment { 454 ct:extends ManagedHardware; 455 // ... 456 ct:instance-list equipment { 457 ct:instance-type Equipment; 458 } 459 } 461 ct:complex-type EquipmentHolder { 462 ct:extends ManagedHardware; 463 description "In SID V8 definition this is a class based on the 464 M.3100 specification. A base class that represents physical 465 objects that are both manageable as well as able to host, 466 hold, or contain other physical objects. Examples of physical 467 objects that can be represented by instances of this object 468 class are Racks, Chassis, Cards, and Slots. 469 A piece of equipment with the primary purpose of containing 470 other equipment."; 471 leaf vendorName {type string;} 472 // ... 473 ct:instance-list equipment { 474 ct:instance-type Equipment; 475 } 476 ct:instance-list equipmentHolder { 477 ct:instance-type EquipmentHolder; 478 } 479 } 480 // ... 481 } 483 485 1.5.2. Modeling Entity MIB Entries as Physical Resources 487 The physical resource module described above can now be used to model 488 physical entities as defined in the Entity MIB [RFC4133]. For each 489 physical entity class listed in the "PhysicalClass" enumeration, a 490 complex type is defined. Each of these complex types extends the 491 most specific complex type already available in the physical resource 492 module. For example, the type "HWModule" extends the complex type 493 "Equipment" as a hardware module. Physical entity properties that 494 should be included in a physical entity complex type are combined in 495 a grouping, which is then used in each complex type definition of an 496 entity. 498 This approach has following benefits: 500 o The definition of the complex types for hardware entities becomes 501 compact as many of the features can be reused from the basic 502 complex type definition. 504 o Physical entities are modeled in a consistent manner as predefined 505 concepts are extended. 507 o Entity MIB specific attributes as well as vendor specific 508 attributes can be added without having to define separate 509 extension data nodes. 511 Module umdcore : Module hardware-entities 512 : 513 equipment : 514 Holder : 515 0..* : 516 +-------+ : 517 | | : 518 +---------------+ +---------+ | : 519 |ManagedHardware|<|-+-|Equipment|<>--+ : 520 +---------------+ | | Holder |0..1 : +-------+ 521 | | |<|---------+--|Chassis| 522 | +---------+ : | +-------+ 523 | <> : | 524 | |0..* equipment : | +---------+ 525 | | Holder : '--|Container| 526 | | : +---------+ 527 | |0..* equipment : 528 | | : 529 | | equipment : 530 | | 0..* : 531 | | +-------+ : 532 | | | | : 533 | +---------+ | : 534 '-|Equipment|<>--+ : +--------+ 535 | |<|---------+--|HWModule| 536 +---------+ : | +--------+ 537 compositeEquipment : | 538 : | +---------+ 539 : |--|Backplane| 540 : +---------+ 542 Figure 2: Hardware Entities Model 544 Below is an excerpt of the according YANG module using complex types 545 to model hardware entities. The complete YANG module for the 546 Hardware Entities model in Figure 2 can be found in Appendix A: 'YANG 547 Modules for Physical Network Resource Model and Hardware Entities 548 Model'. 550 552 module hardware-entities { 554 namespace "http://example.com/hardware-entities"; 555 prefix "hwe"; 557 import ietf-yang-types {prefix "yt";} 558 import ietf-complex-types {prefix "ct";} 559 import udmcore {prefix "uc";} 561 grouping PhysicalEntityProperties { 562 // ... 563 leaf mfgDate {type yang:date-and-time; } 564 leaf-list uris {type string; } 565 } 567 // Physical entities representing equipment 569 ct:complex-type HWModule { 570 ct:extends uc:Equipment; 571 description "Complex type representing module entries 572 (entPhysicalClass = module(9)) in entPhysicalTable"; 573 uses PhysicalEntityProperties; 574 } 576 // ... 578 // Physical entities representing equipment holders 580 ct:complex-type Chassis { 581 ct:extends uc:EquipmentHolder; 582 description "Complex type representing chassis entries 583 (entPhysicalClass = chassis(3)) in entPhysicalTable"; 584 uses PhysicalEntityProperties; 585 } 587 // ... 588 } 590 591 2. Complex Types 593 2.1. Definition 595 YANG type concept is currently restricted to simple types, e.g. 596 restrictions of primitive types, enumerations or union of simple 597 types. 599 Complex types are types with a rich internal structure, which may be 600 composed of substatements defined in Table 1 (e.g. lists, leafs, 601 containers, choices). A new complex type may extend an existing 602 complex type. This allows providing type-safe extensions to existing 603 YANG models as instances of the new type. 605 Complex types have the following characteristics: 607 o Introduction of new types, as a named, formal description of a 608 concrete manageable resource as well as abstract concepts. 610 o Types can be extended, i.e. new types can be defined by 611 specializing existing types adding new features. Instances of 612 such an extended type can be used wherever instances of the base 613 type may appear. 615 o The type information is made part of the NETCONF payload in case a 616 derived type substitutes a base type. This enables easy and 617 efficient consumption of payload elements representing complex 618 type instances. 620 2.2. complex-type extension statement 622 The extension statement "complex-type" is introduced that accepts an 623 arbitrary number of node tree defining statements among other common 624 YANG statements ("YANG Statements", [RFC6020] Section 7). 626 +------------------+-------------+ 627 | substatement | cardinality | 628 +------------------+-------------+ 629 | abstract | 0..1 | 630 | anyxml | 0..n | 631 | choice | 0..n | 632 | container | 0..n | 633 | description | 0..1 | 634 | ct:instance | 0..n | 635 | ct:instance-list | 0..n | 636 | ct:extends | 0..1 | 637 | grouping | 0..n | 638 | if-feature | 0..n | 639 | key | 0..1 | 640 | leaf | 0..n | 641 | leaf-list | 0..n | 642 | list | 0..n | 643 | must | 0..n | 644 | ordered-by | 0..n | 645 | reference | 0..1 | 646 | refine | 0..n | 647 | status | 0..1 | 648 | typedef | 0..n | 649 | uses | 0..n | 650 +------------------+-------------+ 652 Table 1: complex-type's substatements 654 Complex type definitions may appear at every place, where a grouping 655 may be defined. That includes the module, submodule, rpc, input, 656 output, notification, container, and list statements. 658 Complex type names populate a distinct namespace. As with YANG 659 groupings, it is possible to define a complex type and a data node 660 (e.g. leaf, list, instance statements) with the same name in the same 661 scope. All complex type names defined within a parent node or at the 662 top-level of the module or its submodules share the same type 663 identifier namespace. This namespace is scoped to the parent node or 664 module. 666 A complex type MAY have an instance key. An instance key is either 667 defined with the "key" statement as part of the complex type or is 668 inherited from the base complex type. It is not allowed to define an 669 additional key if the base complex type or one of its ancestors 670 already defines a key. 672 Complex-type definitions do not create nodes in the schema tree. 674 2.3. instance extension statement 676 The "instance" extension statement is used to instantiate a complex 677 type by creating a subtree in the management information node tree. 678 The instance statement takes one argument that is the identifier of 679 the complex type instance. It is followed by a block of 680 substatements. 682 The type of the instance is specified with the mandatory "ct: 683 instance-type" substatement. The type of an instance MUST be a 684 complex type. Common YANG statements may be used as substatements of 685 the "instance" statement. An instance is by default optional. To 686 make an instance mandatory, "mandatory true" has to be applied as 687 substatement. 689 +------------------+-------------+ 690 | substatement | cardinality | 691 +------------------+-------------+ 692 | description | 0..1 | 693 | config | 0..1 | 694 | ct:instance-type | 1 | 695 | if-feature | 0..n | 696 | mandatory | 0..1 | 697 | must | 0..n | 698 | reference | 0..1 | 699 | status | 0..1 | 700 | when | 0..1 | 701 | anyxml | 0..n | 702 | choice | 0..n | 703 | container | 0..n | 704 | ct:instance | 0..n | 705 | ct:instance-list | 0..n | 706 | leaf | 0..n | 707 | leaf-list | 0..n | 708 | list | 0..n | 709 +------------------+-------------+ 711 Table 2: instance's substatements 713 The "instance" and "instance-list" extension statements (see Section 714 2.4 "instance-list extension statement") are similar to the existing 715 "leaf" and "leaf-list" statements, with the exception that the 716 content is composed of subordinate elements according to the 717 instantiated complex type. 719 It is also possible to add additional data nodes by using the 720 according leaf, leaf-list, list, and choice statements etc. as sub- 721 statements of the instance declaration. This is an in-place 722 augmentation of the used complex type confined to a complex type 723 instantiation (see also Section 2.13 "Using complex types" for 724 details on augmenting complex types). 726 2.4. instance-list extension statement 728 The "instance-list" extension statement is used to instantiate a 729 complex type by defining a sequence of subtrees in the management 730 information node tree. In addition, the "instance-list" statement 731 takes one argument that is the identifier of the complex type 732 instances. It is followed by a block of substatements. 734 The type of the instance is specified with the mandatory "ct: 735 instance-type" substatement. In addition it can be defined how often 736 an instance may appear in the schema tree by using the min-elements 737 and max-elements substatements. Common YANG statements may be used 738 as substatements of the "instance-list" statement. 740 In analogy to "instance" statement, sub-statement like "list", 741 "choice", leaf" etc. MAY be used to augment the instance list 742 elements at the root level with additional data nodes. 744 +------------------+-------------+ 745 | substatementc | cardinality | 746 +------------------+-------------+ 747 | description | 0..1 | 748 | config | 0..1 | 749 | ct:instance-type | 1 | 750 | if-feature | 0..n | 751 | max-elements | 0..1 | 752 | min-elements | 0..1 | 753 | must | 0..n | 754 | ordered-by | 0..1 | 755 | reference | 0..1 | 756 | status | 0..1 | 757 | when | 0..1 | 758 | anyxml | 0..n | 759 | choice | 0..n | 760 | container | 0..n | 761 | ct:instance | 0..n | 762 | ct:instance-list | 0..n | 763 | leaf | 0..n | 764 | leaf-list | 0..n | 765 | list | 0..n | 766 +------------------+-------------+ 768 Table 3: instance-list's substatements 770 In case the instance list represents configuration data, the used 771 complex type of an instance MUST have an instance key. 773 Instances as well as instance lists may appear as arguments of the 774 "deviate" statement. 776 2.5. extends extension statement 778 A complex type MAY extend exactly one existing base complex type by 779 using the "extends" extension statement. The keyword "extends" MAY 780 occur as substatement of the "complex-type" extension statement. The 781 argument of the "complex-type" extension statement refers to the base 782 complex type via its name. In case a complex type represents 783 configuration data (the default), it MUST have a key, otherwise it 784 MAY have a key. A key is either defined with the key statement as 785 part of the complex type or is inherited from the base complex type. 787 +--------------+-------------+ 788 | substatement | cardinality | 789 +--------------+-------------+ 790 | description | 0..1 | 791 | reference | 0..1 | 792 | status | 0..1 | 793 +--------------+-------------+ 795 Table 4: extends' substatements 797 2.6. abstract extension statement 799 Complex types may be declared to be abstract by using the "abstract" 800 extension statement. An abstract complex type cannot be 801 instantiated, meaning it cannot appear as most specific type of an 802 instance in NETCONF payload. In case an abstract type extends a base 803 type, the base complex type MUST be also abstract. By default, 804 complex types are not abstract. 806 The abstract complex type serves only as a base type for derived 807 concrete complex types and cannot be used as a type for an instance 808 in NETCONF payload. 810 The "abstract" extension statement takes a single string argument, 811 which is either "true" or "false". In case a "complex-type" 812 statement does not contain an "abstract" statement as substatement, 813 the default is "false". The "abstract" statement does not support 814 any substatements. 816 2.7. XML Encoding Rules 818 An "instance" node is encoded as an XML element, where an "instance- 819 list" node is encoded as a series of XML elements. The XML element 820 name is the "instance" respectively "instance-list" identifier, and 821 its XML namespace is the module's XML namespace. 823 Instance child nodes are encoded as subelements of the instance XML 824 element. Subelements representing child nodes defined in the same 825 complex type may appear in any order. However child nodes of an 826 extending complex type follow the child nodes of the extended complex 827 type. As such, the XML encoding of lists is similar to the encoding 828 of containers and lists in YANG. 830 Instance key nodes are encoded as subelements of the instance XML 831 element. Instance key nodes must appear in the same order as they 832 are defined within the "key" statement of the according complex type 833 definition and precede all other nodes defined in the same complex 834 type. I.e. if key nodes are defined in an extending complex type, 835 XML elements representing key data precede all other XML elements 836 representing child nodes. On the other hand XML elements 837 representing key data follow the XML elements representing data nodes 838 of the base type. 840 The type of actual complex type instance is encoded in a type 841 element, which is put in front of all instance child elements, 842 including key nodes, as described in Section 2.8 ("Type Encoding 843 Rules"). 845 The proposed XML encoding rules conform to the YANG XML encoding 846 rules in [RFC6020]. Compared to YANG, enabling key definitions in 847 derived hierarchies is a new feature introduced with the complex 848 types extension. As a new language feature complex types introduce 849 also a new payload entry for the instance type identifier. 851 Based on our implementation experience, the proposed XML encoding 852 rules support consistent mapping of YANG models with complex types to 853 XML Schema using XML complex types. 855 2.8. Type Encoding Rules 857 In order to encode the type of an instance in NETCONF payload, XML 858 elements named "type" belonging to the XML namespace 859 "urn:ietf:params:xml:ns:yang:ietf-complex-type-instance" are added to 860 the serialized form of instance and instance-list nodes in the 861 payload. The suggested namespace prefix is "cti". The "cti:type" 862 XML elements are inserted before the serialized form of all members 863 that have been declared in the according complex type definition. 865 The "cti:type" element is inserted for each type in the extension 866 chain to the actual type of the instance (most specific last). Each 867 type name includes its corresponding namespace. 869 The type of a complex type instance MUST be encoded in the reply to 870 NETCONF and operations, and in the payload of 871 NETCONF operation if the operation is "create" or 872 "replace". The type of the instance MUST also be specified in case 873 is used to export a configuration to a resource 874 addressed with an URI. The type of the instance has to be specified 875 in user defined RPC's. 877 The type of the instance MAY be specified in case the operation is 878 "merge" (either because this is explicitly specified or no operation 879 attribute is provided). 881 In case the node already exists in the target configuration and the 882 type attribute (type of a complex type instance) is specified but 883 differs from the data in the target, an element is 884 returned with an value of "wrong-complex-type". In 885 case no such element is present in the target configuration but the 886 type attribute is missing in the configuration data, an 887 element is returned with an value of "missing-attribute". 889 The type MUST NOT be specified in case the operation is "delete". 891 2.9. Extension and Feature Definition Module 893 The module below contains all YANG extension definitions for complex 894 types and typed instance identifiers. In addition a "complex-type" 895 feature is defined, which may be used to provide conditional or 896 alternative modeling for depending on the support status of complex 897 types in a NETCONF server. A NETCONF server that supports the 898 complex types modeling features and the XML encoding for complex 899 types as defined in this document MUST advertise this as a feature. 900 This is done by including the feature name "complex-types" into the 901 feature parameter list as part of the NETCONF message as 902 described in Section 5.6.4 in [RFC6020]. 904 file "ietf-complex-types@2010-10-05.yang" 906 module ietf-complex-types { 908 namespace "urn:ietf:params:xml:ns:yang:ietf-complex-types"; 909 prefix "ct"; 910 organization 911 "NETMOD WG"; 913 contact 914 "Editor: Bernd Linowski 915 916 Editor: Mehmet Ersue 917 918 Editor: Siarhei Kuryla 919 "; 921 description 922 "YANG extensions for complex types and typed instance 923 identifiers. 925 Copyright (c) 2010 IETF Trust and the persons identified as 926 the document authors. All rights reserved. 928 Redistribution and use in source and binary forms, with or 929 without modification, is permitted pursuant to, and subject 930 to the license terms contained in, the Simplified BSD License 931 set forth in Section 4.c of the IETF Trust's Legal Provisions 932 Relating to IETF Documents 933 (http://trustee.ietf.org/license-info). 935 This version of this YANG module is part of RFC XXXX; see 936 the RFC itself for full legal notices."; 938 // RFC Ed.: Please replace XXXX with actual RFC number and 939 // remove this note 941 revision 2010-12-10 { 942 description "Initial revision."; 943 } 945 // RFC Ed.: Please replace the date of the revision statement 946 // with RFC publication date and remove this note 948 extension complex-type { 949 description "Defines a complex-type."; 950 reference "section 2.2., complex-type extension statement"; 951 argument type-identifier { 952 yin-element true; 953 } 954 } 955 extension extends { 956 description "Defines the base type of a complex-type."; 957 reference "section 2.5., extends extension statement"; 958 argument base-type-identifier { 959 yin-element true; 960 } 961 } 963 extension abstract { 964 description "Makes the complex-type abstract."; 965 reference "section 2.6., abstract extension statement"; 966 argument status; 967 } 969 extension instance { 970 description "Declares an instance of the given 971 complex type."; 972 reference "section 2.3., instance extension statement"; 973 argument ct-instance-identifier { 974 yin-element true; 975 } 976 } 978 extension instance-list { 979 description "Declares a list of instances of the given 980 complex type"; 981 reference "section 2.4., instance-list extension statement"; 982 argument ct-instance-identifier { 983 yin-element true; 984 } 985 } 987 extension instance-type { 988 description "Tells to which type instance the instance 989 identifier refers to."; 990 reference "section 3.2., instance-type extension statement"; 991 argument target-type-identifier { 992 yin-element true; 993 } 994 } 996 feature complex-types { 997 description "This feature indicates that the server supports 998 complex types and instance identifiers."; 999 } 1001 } 1003 1005 2.10. Example Model for Complex Types 1007 The example model below shows how complex types can be used to 1008 represent physical equipment in a vendor independent, abstract way. 1009 It reuses the complex types defined in the physical resource model in 1010 Section 1.5.1 1011 1013 module hw { 1015 namespace "http://example.com/hw"; 1016 prefix "hw"; 1018 import ietf-complex-types {prefix "ct"; } 1019 import udmcore {prefix "uc"; } 1021 // Holder types 1023 ct:complex-type Slot { 1024 ct:extends uc:EquipmentHolder; 1025 leaf slotNumber { type uint16; config false; } 1026 // ... 1027 } 1029 ct:complex-type Chassis { 1030 ct:extends uc:EquipmentHolder; 1031 leaf numberOfChassisSlots { type uint32; config false; } 1032 // .. 1033 } 1035 // Equipment types 1037 ct:complex-type Card { 1038 ct:extends uc:Equipment; 1039 leaf position { type uint32; mandatory true; } 1040 leaf slotsRequired {type unit32; } 1041 } 1043 // Root Element 1044 ct:instance hardware { type uc:ManagedHardware; } 1046 } // hw module 1048 1050 2.11. NETCONF Payload Example 1052 Following example shows the payload of a reply to a NETCONF 1053 command. The actual type of managed hardware instances is indicated 1054 with the "cti:type" elements as required by the type encoding rules. 1055 The containment hierarchy in the NETCONF XML payload reflects the 1056 containment hierarchy of hardware instances. This makes filtering 1057 based on the containment hierarchy possible without having to deal 1058 with values of key-ref leafs that represent the tree structure in a 1059 flattened hierarchy. 1061 1062 uc:BasicObject 1063 /R-T31/CH-2 1064 6278279001 1065 uc:Resource 1066 uc:PhysicalResource 1067 Rack R322-1 1068 R-US-3276279a 1069 uc:Hardware 1070 uc:ManagedHardware 1071 hw:EquipmentHolder 1072 1073 uc:BasicObject 1074 /R-T31/CH-2/SL-1 1075 548872003 1076 uc:Resource 1077 uc:PhysicalResource 1078 CU-Slot 1079 T-K4733890x45 1080 uc:Hardware 1081 uc:ManagedHardware 1082 uc:EquipmentHolder 1083 1084 uc:BasicObject 1085 /R-T31/CH-2/SL-1/C-3 1086 89772001 1087 uc:Resource 1088 uc:PhysicalResource 1089 ATM-45252 1090 A-778911-b 1091 uc:Hardware 1092 uc:ManagedHardware 1093 uc:Equipment 1094 true 1095 A2 1096 1 1097 hw:Card 1098 1 1099 1100 hw:Slot 1101 1 1102 1103 hw:Chassis 1104 6 1105 // ... 1106 1108 2.12. Update Rules for Modules Using Complex Types 1110 In addition to the module update rules specified in Section 10 in 1111 [RFC6020], modules that define complex-types, instances of complex 1112 types and typed instance identifiers must obey following rules: 1114 o New complex types MAY be added. 1116 o A new complex type MAY extend an existing complex type. 1118 o New data definition statements MAY be added to a complex type only 1119 if: 1121 * they are not mandatory or 1123 * they are not conditionally dependent on a new feature (i.e., 1124 have an "if-feature" statement, which refers to a new feature). 1126 o The type referred to by the instance-type statement may be changed 1127 to a type that derives from the original type only if the original 1128 type does not represent configuration data. 1130 2.13. Using Complex Types 1132 All data nodes defined inside a complex type reside in the complex 1133 type namespace, which is their parent node namespace. 1135 2.13.1. Overriding Complex Type Data Nodes 1137 It is not allowed to override a data node inherited from a base type. 1138 I.e. it is an error if a type "base" with a leaf named "foo" is 1139 extended by another complex type ("derived") with a leaf named "foo" 1140 in the same module. In case they are derived in different modules, 1141 there are two distinct "foo" nodes which are mapped to the XML 1142 namespaces of the module, where the complex types are specified. 1144 A complex type that extends a basic complex type may use the "refine" 1145 statement in order to improve an inherited data node. The target 1146 node identifier must be qualified by the module prefix to indicate 1147 clearly, which inherited node is refined. 1149 The following refinements can be done: 1151 o A leaf or choice node may have a default value, or a new default 1152 value if it already had one 1154 o Any node may have a different "description" or "reference" string. 1156 o A leaf, anyxml, or choice node may have a "mandatory true" 1157 statement. However, it is not allowed to change from "mandatory 1158 true" to "mandatory false". 1160 o A leaf, leaf-list, list, container, or anyxml node may have 1161 additional "must" expressions. 1163 o A list, leaf-list, instance or instance-list node may have a "min- 1164 elements" statement, if the base type does not have one or one 1165 with a value that is greater than the minimum value of the base 1166 type. 1168 o A list, leaf-list, instance or instance-list node may have a "max- 1169 elements" statement, if the base type does not have one or one 1170 with a value that is smaller than the maximum value of the base 1171 type. 1173 It is not allowed to refine complex-type nodes inside instance or 1174 instance-list statements. 1176 2.13.2. Augmenting Complex Types 1178 Augmenting complex types is only allowed if a complex type is 1179 instantiated in an "instance" or "instance-list" statement. This 1180 confines the effect of the augmentation to the location in the schema 1181 tree, where the augmentation is done. The argument of the "augment" 1182 statement MUST be in the descendant form (as defined by the rule 1183 "descendant-schema-nodeid" in Section 12 in [RFC6020]). 1185 ct:complex-type Chassis { 1186 ct:extends EquipmentHolder; 1187 container chassisInfo { 1188 config false; 1189 leaf numberOfSlots { type uint16; } 1190 leaf occupiedSlots { type uint16; } 1191 leaf height {type unit16;} 1192 leaf width {type unit16;} 1193 } 1194 } 1196 ct:instance-list chassis { 1197 type Chassis; 1198 augment "chassisInfo" { 1199 leaf modelId { type string; } 1200 } 1201 } 1203 When augmenting a complex type, only the "container", "leaf", "list", 1204 "leaf-list", "choice", "instance", "instance-list" and "if-feature" 1205 statements may be used within the "augment" statement. The nodes 1206 added by the augmentation MUST NOT be mandatory nodes. One or many 1207 augment statements may not cause the creation of multiple nodes with 1208 the same name from the same namespace in the target node. 1210 To achieve less complex modeling this document proposes the 1211 augmentation of complex type instances without recursion. 1213 2.13.3. Controlling the Use of Complex Types 1215 A server might not want to support all complex types defined in a 1216 supported module. This issue can be addressed with YANG features as 1217 follows: 1219 o Features are defined that are used inside complex type definitions 1220 (by using "if-feature" as substatement) to make them optional. In 1221 this case such complex types may only be instantiated if the 1222 feature is supported (advertized as capability in the NETCONF 1223 message). 1225 o The "deviation" statement may be applied to node trees, which are 1226 created by "instance" and "instance-list" statements. In this 1227 case, only the substatement "deviate not-supported" is allowed. 1229 o It is not allowed to apply the deviation statement to node tree 1230 elements that may occur because of the recursive use of a complex 1231 type. Other forms of deviations ("deviate add", "deviate 1232 replace", "deviate delete") are NOT supported inside node trees 1233 spanned by "instance" or "instance-list". 1235 As complex type definitions do not contribute by itself to the data 1236 node tree, data node declarations inside complex types cannot be 1237 target of deviations. 1239 In the example below, client applications are informed that the leaf 1240 "occupiedSlots" is not supported in the top-level chassis. However, 1241 if a chassis contains another chassis, the contained chassis may 1242 support the leaf informing about the number of occupied slots. 1244 deviation "/chassis/chassisSpec/occupiedSlots" { 1245 deviate not-supported; 1246 } 1248 3. Typed Instance Identifier 1250 3.1. Definition 1252 Typed instance identifier relationships are an addition to the 1253 relationship types already defined in YANG, where the leafref 1254 relationship is location dependent, and the instance-identifier does 1255 not specify to which type of instances the identifier points to. 1257 A typed instance identifier represents a reference to an instance of 1258 a complex type without being restricted to a particular location in 1259 the containment tree. This is done by using the extension statement 1260 "instance-type" as a substatement of the existing "type instance 1261 identifier" statement. 1263 Typed instance identifiers allow referring to instances of complex 1264 types that may be located anywhere in the schema tree. The "type" 1265 statement plays the role of a restriction that must be fulfilled by 1266 the target node, which is referred to with the instance identifier. 1267 The target node MUST be of a particular complex type, either the type 1268 itself or any type that extends this complex type. 1270 3.2. instance-type extension statement 1272 The "instance-type" extension statement specifies the complex type of 1273 the instance referred by the instance-identifier. The referred 1274 instance may also instantiate any complex type that extends the 1275 specified complex type. 1277 The instance complex type is identified by the single name argument. 1278 The referred complex type MUST have a key. This extension statement 1279 MUST be used as a substatement of the "type instance-identifier" 1280 statement. The "instance-type" extension statement does not support 1281 any substatements. 1283 3.3. Typed Instance Identifier Example 1285 In the example below, a physical link connects an arbitrary number of 1286 physical ports. Here typed instance identifiers are used to denote, 1287 which "PhysicalPort" instances (anywhere in the data tree) are 1288 connected by a "PhysicalLink". 1290 // Extended version of type Card 1291 ct:complex-type Card { 1292 ct:extends Equipment; 1293 leaf usedSlot { type uint16; mandatory true; } 1294 ct:instance-list port { 1295 type PhysicalPort; 1296 } 1297 } 1299 ct:complex-type PhysicalPort { 1300 ct:extends ManagedHardware; 1301 leaf portNumber { type int32; mandatory true; } 1302 } 1304 ct:complex-type PhysicalLink { 1305 ct:extends ManagedHardware; 1306 leaf media { type string; } 1307 leaf-list connectedPort { 1308 type instance-identifier { 1309 ct:instance-type PhysicalPort; 1310 } 1311 min-elements 2; 1312 } 1313 } 1315 Below is the XML encoding of an element named "link" of type 1316 "PhysicalLink": 1318 1319 FTCL-771 1320 Fiber 1321 /hw:hardware[objectId='R-11'] 1322 /hw:equipment[objectId='AT22']/hw:port[objectId='P12'] 1323 1324 /hw:hardware[objectId='R-42] 1325 /hw:equipment[objectId='AT30']/hw:port[objectId='P3'] 1326 1327 F-7786828 1328 FibCon 7 1329 1331 4. IANA Considerations 1333 This document registers two URIs in the IETF XML registry. Following 1334 the format in [RFC3688], the following registrations are requested: 1336 URI: urn:ietf:params:xml:ns:yang:ietf-complex-types 1337 URI: urn:ietf:params:xml:ns:yang:ietf-complex-type-instance 1339 Registrant Contact: See the 'Author's Addresses' section of this 1340 document. 1342 XML: N/A, the requested URIs are XML namespaces. 1344 This document registers one module name in the 'YANG Module Names' 1345 registry, defined in [RFC6020]. 1347 name: ietf-complex-types 1349 namespace: urn:ietf:params:xml:ns:yang:ietf-complex-types 1351 prefix: ct 1353 RFC: XXXX 1355 RFC Ed.: Please replace XXXX with actual RFC number and remove this 1356 note. 1358 5. Security Considerations 1360 The YANG module "complex-types" in this memo defines YANG extensions 1361 for Complex-types and Typed Instance Identifiers as new language 1362 statements. 1364 Complex-types and Typed Instance Identifiers themselves do not have 1365 any security impact on the Internet. 1367 The security considerations described throughout [RFC6020] apply here 1368 as well. 1370 6. Acknowledgements 1372 The authors would like to thank to Martin Bjorklund, Balazs Lengyel, 1373 Gerhard Muenz, Dan Romascanu, Juergen Schoenwaelder and Martin Storch 1374 for their valuable review and comments on different versions of the 1375 document. 1377 7. References 1379 7.1. Normative References 1381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1382 Requirement Levels", March 1997. 1384 [RFC3688] Mealling, M., "The IETF XML Registry", January 2004. 1386 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1387 Network Configuration Protocol (NETCONF)", October 2010. 1389 7.2. Informative References 1391 [IPFIXCONF] Muenz, G., "Configuration Data Model for IPFIX and 1392 PSAMP", draft-ietf-ipfix-configuration-model-08 (work in 1393 progress), October 2010. 1395 [Libsmi] Kuryla, S., "Libsmi Extension for Complex Types", 1396 April 2010, . 1398 [Pyang] Bjorklund, M., "An extensible YANG validator and 1399 converter", October 2010, 1400 . 1402 [Pyang-ct] Kuryla, S., "Pyang Extension for Complex Types", 1403 April 2010, . 1405 [RFC4133] Bierman, A. and K. McCloghrie, "Entity MIB (Version 3)", 1406 August 2005. 1408 [SID V8] Tele Management Forum, "GB922-Information Framework 1409 (SID) Solution Suite, Release 8.0", July 2008, < http:/ 1410 /www.tmforum.org/DocumentsInformation/ 1411 GB922InformationFramework/35499/article.html>. 1413 [UDM] NSN, "Unified Data Model SID Compliance Statement", 1414 May 2010, . 1417 Appendix A. YANG Modules for Physical Network Resource Model and 1418 Hardware Entities Model 1420 YANG module for the 'Physical Network Resource Model': 1422 1424 module udmcore { 1426 namespace "http://example.com/udmcore"; 1427 prefix "udm"; 1429 import ietf-yang-types {prefix "yang";} 1430 import ietf-complex-types {prefix "ct";} 1431 ct:complex-type BasicObject { 1432 ct:abstract true; 1433 key "distinguishedName"; 1434 leaf globalId {type int64;} 1435 leaf distinguishedName {type string; mandatory true;} 1436 } 1438 ct:complex-type ManagedObject { 1439 ct:extends BasicObject; 1440 ct:abstract true; 1441 leaf instance {type string;} 1442 leaf objectState {type int32;} 1443 leaf release {type string;} 1444 } 1446 ct:complex-type Resource { 1447 ct:extends ManagedObject; 1448 ct:abstract true; 1449 leaf usageState {type int16;} 1450 leaf managementMethodSupported {type string;} 1451 leaf managementMethodCurrent {type string;} 1452 leaf managementInfo {type string;} 1453 leaf managementDomain {type string;} 1454 leaf version {type string;} 1455 leaf entityIdentification {type string;} 1456 leaf desription {type string;} 1457 leaf rootEntityType {type string;} 1458 } 1460 ct:complex-type LogicalResource { 1461 ct:extends Resource; 1462 ct:abstract true; 1463 leaf lrStatus {type int32;} 1464 leaf serviceState {type int32;} 1465 leaf isOperational {type boolean;} 1466 } 1468 ct:complex-type PhysicalResource { 1469 ct:extends Resource; 1470 ct:abstract true; 1471 leaf manufactureDate {type string;} 1472 leaf otherIdentifier {type string;} 1473 leaf powerState {type int32;} 1474 leaf serialNumber {type string;} 1475 leaf versionNumber {type string;} 1477 } 1479 ct:complex-type Hardware { 1480 ct:extends PhysicalResource; 1481 ct:abstract true; 1482 leaf width {type string;} 1483 leaf height {type string;} 1484 leaf depth {type string;} 1485 leaf measurementUnits {type int32;} 1486 leaf weight {type string;} 1487 leaf weightUnits {type int32;} 1488 leaf-list physicalLink { 1489 type instance-identifier { 1490 ct:instance-type PhysicalLink; 1491 } 1492 } 1493 ct:instance-list containedHardware { 1494 ct:instance-type Hardware; 1495 } 1496 ct:instance-list physicalConnector { 1497 ct:instance-type PhysicalConnector; 1498 } 1499 } 1501 ct:complex-type PhysicalLink { 1502 ct:extends PhysicalResource; 1503 leaf isWiereless {type boolean;} 1504 leaf currentLength {type string;} 1505 leaf maximumLength {type string;} 1506 leaf mediaType {type int32;} 1507 leaf-list hardware { 1508 type instance-identifier { 1509 ct:instance-type Hardware; 1510 } 1511 } 1512 } 1514 ct:complex-type ManagedHardware { 1515 ct:extends Hardware; 1516 leaf additionalinfo {type string;} 1517 leaf physicalAlarmReportingEnabled {type boolean;} 1518 leaf pyhsicalAlarmStatus {type int32;} 1519 leaf coolingRequirements {type string;} 1520 leaf hardwarePurpose {type string;} 1521 leaf isPhysicalContainer {type boolean;} 1523 } 1525 ct:complex-type AuxiliaryComponent { 1526 ct:extends ManagedHardware; 1527 ct:abstract true; 1528 } 1530 ct:complex-type PhysicalPort { 1531 ct:extends ManagedHardware; 1532 leaf portNumber {type int32;} 1533 leaf duplexMode {type int32;} 1534 leaf ifType {type int32;} 1535 leaf vendorPortName {type string;} 1536 } 1538 ct:complex-type PhysicalConnector { 1539 ct:extends Hardware; 1540 leaf location {type string;} 1541 leaf cableType {type int32;} 1542 leaf gender {type int32;} 1543 leaf inUse {type boolean;} 1544 leaf pinDescription {type string;} 1545 leaf typeOfConnector {type int32;} 1546 leaf-list sourcePhysicalConnector { 1547 type instance-identifier { 1548 ct:instance-type PhysicalConnector; 1549 } 1550 } 1551 leaf-list targetPhysicalConnector { 1552 type instance-identifier { 1553 ct:instance-type PhysicalConnector; 1554 } 1555 } 1556 } 1558 ct:complex-type Equipment { 1559 ct:extends ManagedHardware; 1560 leaf installStatus {type int32;} 1561 leaf expectedEquipmentType {type string;} 1562 leaf installedEquipmentType {type string;} 1563 leaf installedVersion {type string;} 1564 leaf redundancy {type int32;} 1565 leaf vendorName {type string;} 1566 leaf dateOfLastService {type yang:date-and-time;} 1567 leaf interchangeability {type string;} 1568 leaf identificationCode {type string;} 1569 ct:instance-list equipment { 1570 ct:instance-type Equipment; 1571 } 1572 } 1574 ct:complex-type EquipmentHolder { 1575 ct:extends ManagedHardware; 1576 leaf vendorName {type string;} 1577 leaf locationName {type string;} 1578 leaf dateOfLastService {type yang:date-and-time;} 1579 leaf partNumber {type string;} 1580 leaf availabilityStatus {type int16;} 1581 leaf nameFromPlanningSystem {type string;} 1582 leaf modelNumber {type string;} 1583 leaf acceptableEquipmentList {type string;} 1584 leaf isSolitaryHolder {type boolean;} 1585 leaf holderStatus {type int16;} 1586 leaf interchangeability {type string;} 1587 leaf equipmentHolderSpecificType {type string; } 1588 leaf position {type string;} 1589 leaf atomicCompositeType {type int16;} 1590 leaf uniquePhysical {type boolean;} 1591 leaf physicalDescription {type string;} 1592 leaf serviceApproach {type string;} 1593 leaf mountingOptions {type int32;} 1594 leaf cableManagementStrategy {type string;} 1595 leaf isSecureHolder {type boolean;} 1596 ct:instance-list equipment { 1597 ct:instance-type Equipment; 1598 } 1599 ct:instance-list equipmentHolder { 1600 ct:instance-type EquipmentHolder; 1601 } 1602 } 1604 // ... other resource complex types ... 1605 } 1606 1608 YANG module for the 'Hardware Entities Model': 1610 1611 module hardware-entities { 1613 namespace "http://example.com/:hardware-entities"; 1614 prefix "hwe"; 1616 import ietf-yang-types {prefix "yang";} 1617 import ietf-complex-types {prefix "ct";} 1618 import udmcore {prefix "uc";} 1620 grouping PhysicalEntityProperties { 1621 leaf hardwareRev {type string; } 1622 leaf firmwareRev {type string; } 1623 leaf softwareRev {type string; } 1624 leaf serialNum {type string; } 1626 leaf mfgName {type string; } 1627 leaf modelName {type string; } 1628 leaf alias {type string; } 1629 leaf ssetID{type string; } 1630 leaf isFRU {type boolean; } 1631 leaf mfgDate {type yang:date-and-time; } 1632 leaf-list uris {type string; } 1633 } 1635 // Physical entities representing equipment 1637 ct:complex-type Module { 1638 ct:extends uc:Equipment; 1639 description "Complex type representing module entries 1640 (entPhysicalClass = module(9)) in entPhysicalTable"; 1641 uses PhysicalEntityProperties; 1642 } 1644 ct:complex-type Backplane { 1645 ct:extends uc:Equipment; 1646 description "Complex type representing backplane entries 1647 (entPhysicalClass = backplane(4)) in entPhysicalTable"; 1648 uses PhysicalEntityProperties; 1649 } 1651 // Physical entities representing auxiliray hardware components 1653 ct:complex-type PowerSupply { 1654 ct:extends uc:AuxiliaryComponent; 1655 description "Complex type representing power supply entries 1656 (entPhysicalClass = powerSupply(6)) in entPhysicalTable"; 1657 uses PhysicalEntityProperties; 1658 } 1660 ct:complex-type Fan { 1661 ct:extends uc:AuxiliaryComponent; 1662 description "Complex type representing fan entries 1663 (entPhysicalClass = fan(7)) in entPhysicalTable"; 1664 uses PhysicalEntityProperties; 1665 } 1667 ct:complex-type Sensor { 1668 ct:extends uc:AuxiliaryComponent; 1669 description "Complex type representing sensor entries 1670 (entPhysicalClass = sensor(8)) in entPhysicalTable"; 1671 uses PhysicalEntityProperties; 1672 } 1674 // Physical entities representing equipment holders 1676 ct:complex-type Chassis { 1677 ct:extends uc:EquipmentHolder; 1678 description "Complex type representing chassis entries 1679 (entPhysicalClass = chassis(3)) in entPhysicalTable"; 1680 uses PhysicalEntityProperties; 1681 } 1683 ct:complex-type Container { 1684 ct:extends uc:EquipmentHolder; 1685 description "Complex type representing container entries 1686 (entPhysicalClass = container(5)) in entPhysicalTable"; 1687 uses PhysicalEntityProperties; 1688 } 1690 ct:complex-type Stack { 1691 ct:extends uc:EquipmentHolder; 1692 description "Complex type representing stack entries 1693 (entPhysicalClass = stack(11)) in entPhysicalTable"; 1694 uses PhysicalEntityProperties; 1695 } 1697 // Other kinds of physical entities 1699 ct:complex-type Port { 1700 ct:extends uc:PhysicalPort; 1701 description "Complex type representing port entries 1702 (entPhysicalClass = port(10)) in entPhysicalTable"; 1703 uses PhysicalEntityProperties; 1704 } 1706 ct:complex-type CPU { 1707 ct:extends uc:Hardware; 1708 description "Complex type representing cpu entries 1709 (entPhysicalClass = cpu(12)) in entPhysicalTable"; 1710 uses PhysicalEntityProperties; 1711 } 1713 } 1714 1716 Appendix B. Example YANG Module for the IPFIX/PSAMP Model 1718 B.1. Modeling Improvements for the IPFIX/PSAMP Model with Complex types 1719 and Typed instance identifiers 1721 The module below is a variation of the IPFIX/PSAMP configuration 1722 model, which uses complex types and typed instance identifiers to 1723 model the concept outlined in [IPFIXCONF]. 1725 When looking at the YANG module with complex types and typed instance 1726 identifiers, various technical improvements on modeling level become 1727 apparent. 1729 o There is almost a one-to-one mapping between the domain concepts 1730 introduced in IPFIX and the complex types in the YANG module 1732 o All associations between the concepts (which are not containment) 1733 are represented with typed identifiers. That avoids having to 1734 refer to a particular location in the tree, which is not mandated 1735 by the original model. 1737 o It is superfluous to represent concept refinement (class 1738 inheritance in the original model) with containment in form of 1739 quite big choice-statements with complex branches. Instead, 1740 concept refinement is realized by complex types extending a base 1741 complex type. 1743 o It is unnecessary to introduce metadata identities and leafs (e.g. 1744 "identity cacheMode" and "leaf cacheMode" in "grouping 1745 cacheParameters") that just serve the purpose of indicating which 1746 concrete sub-type of a generic type (modeled as grouping, which 1747 contains the union of all features of all subtypes) is actually 1748 represented in the MIB. 1750 o Ruling out illegal use of sub-type specific properties (e.g. "leaf 1751 maxFlows") by using "when" statements that refer to a sub-type 1752 discriminator is not necessary (e.g. when "../cacheMode != 1753 'immediate'"). 1755 o It is not needed to define properties like the configuration 1756 status wherever a so called "parameter grouping" is used. Instead 1757 those definitions can be put inside the complex-type definition 1758 itself. 1760 o It can be avoided to separate the declaration of the key from the 1761 related data nodes definitions in a grouping (see use of "grouping 1762 selectorParameters"). 1764 o Complex types may be declared as optional features. If the type 1765 is indicated with an identity (e.g. "identity immediate"), this is 1766 not possible, since "if-feature" is not allowed as a substatement 1767 of "identity". 1769 B.2. IPFIX/PSAMP Model with Complex Types and Typed Instance 1770 Identifiers 1772 1773 module ct-ipfix-psamp-example { 1774 namespace "http://example.com/ns/ct-ipfix-psamp-example"; 1775 prefix ipfix; 1777 import ietf-yang-types { prefix yang; } 1778 import ietf-inet-types { prefix inet; } 1779 import ietf-complex-types {prefix "ct"; } 1781 description "Example IPFIX/PSAMP Configuration Data Model 1782 with complex types and typed instance identifiers"; 1784 revision 2010-12-10 { 1785 description "Version of draft-ietf-ipfix-configuration-model-07 1786 modeled with complex types and typed instance identifiers."; 1787 } 1789 /***************************************************************** 1790 * Features 1791 *****************************************************************/ 1793 feature exporter { 1794 description "If supported, the Monitoring Device can be used as 1795 an Exporter. Exporting Processes can be configured."; 1796 } 1797 feature collector { 1798 description "If supported, the Monitoring Device can be used as 1799 a Collector. Collecting Processes can be configured."; 1800 } 1802 feature meter { 1803 description "If supported, Observation Points, Selection 1804 Processes, and Caches can be configured."; 1805 } 1807 feature psampSampCountBased { 1808 description "If supported, the Monitoring Device supports 1809 count-based Sampling..."; 1810 } 1812 feature psampSampTimeBased { 1813 description "If supported, the Monitoring Device supports 1814 time-based Sampling..."; 1815 } 1817 feature psampSampRandOutOfN { 1818 description "If supported, the Monitoring Device supports 1819 random n-out-of-N Sampling..."; 1820 } 1822 feature psampSampUniProb { 1823 description "If supported, the Monitoring Device supports 1824 uniform probabilistic Sampling..."; 1825 } 1827 feature psampFilterMatch { 1828 description "If supported, the Monitoring Device supports 1829 property match Filtering..."; 1830 } 1832 feature psampFilterHash { 1833 description "If supported, the Monitoring Device supports 1834 hash-based Filtering..."; 1835 } 1837 feature cacheModeImmediate { 1838 description "If supported, the Monitoring Device supports 1839 Cache Mode 'immediate'."; 1840 } 1842 feature cacheModeTimeout { 1843 description "If supported, the Monitoring Device supports 1844 Cache Mode 'timeout'."; 1846 } 1848 feature cacheModeNatural { 1849 description "If supported, the Monitoring Device supports 1850 Cache Mode 'natural'."; 1851 } 1853 feature cacheModePermanent { 1854 description "If supported, the Monitoring Device supports 1855 Cache Mode 'permanent'."; 1856 } 1858 feature udpTransport { 1859 description "If supported, the Monitoring Device supports UDP 1860 as transport protocol."; 1861 } 1863 feature tcpTransport { 1864 description "If supported, the Monitoring Device supports TCP 1865 as transport protocol."; 1866 } 1868 feature fileReader { 1869 description "If supported, the Monitoring Device supports the 1870 configuration of Collecting Processes as File Readers."; 1871 } 1873 feature fileWriter { 1874 description "If supported, the Monitoring Device supports the 1875 configuration of Exporting Processes as File Writers."; 1876 } 1878 /***************************************************************** 1879 * Identities 1880 *****************************************************************/ 1882 /*** Hash function identities ***/ 1883 identity hashFunction { 1884 description "Base identity for all hash functions..."; 1885 } 1886 identity BOB { 1887 base "hashFunction"; 1888 description "BOB hash function"; 1889 reference "RFC5475, Section 6.2.4.1."; 1890 } 1891 identity IPSX { 1892 base "hashFunction"; 1893 description "IPSX hash function"; 1894 reference "RFC5475, Section 6.2.4.1."; 1895 } 1896 identity CRC { 1897 base "hashFunction"; 1898 description "CRC hash function"; 1899 reference "RFC5475, Section 6.2.4.1."; 1900 } 1902 /*** Export mode identities ***/ 1903 identity exportMode { 1904 description "Base identity for different usages of export 1905 destinations configured for an Exporting Process..."; 1906 } 1907 identity parallel { 1908 base "exportMode"; 1909 description "Parallel export of Data Records to all 1910 destinations configured for the Exporting Process."; 1911 } 1912 identity loadBalancing { 1913 base "exportMode"; 1914 description "Load-balancing between the different 1915 destinations..."; 1916 } 1917 identity fallback { 1918 base "exportMode"; 1919 description "Export to the primary destination..."; 1920 } 1922 /*** Options type identities ***/ 1923 identity optionsType { 1924 description "Base identity for report types exported 1925 with options..."; 1926 } 1927 identity meteringStatistics { 1928 base "optionsType"; 1929 description "Metering Process Statistics."; 1930 reference "RFC 5101, Section 4.1."; 1931 } 1932 identity meteringReliability { 1933 base "optionsType"; 1934 description "Metering Process Reliability Statistics."; 1935 reference "RFC 5101, Section 4.2."; 1936 } 1937 identity exportingReliability { 1938 base "optionsType"; 1939 description "Exporting Process Reliability 1940 Statistics."; 1941 reference "RFC 5101, Section 4.3."; 1943 } 1944 identity flowKeys { 1945 base "optionsType"; 1946 description "Flow Keys."; 1947 reference "RFC 5101, Section 4.4."; 1948 } 1949 identity selectionSequence { 1950 base "optionsType"; 1951 description "Selection Sequence and Selector Reports."; 1952 reference "RFC5476, Sections 6.5.1 and 6.5.2."; 1953 } 1954 identity selectionStatistics { 1955 base "optionsType"; 1956 description "Selection Sequence Statistics Report."; 1957 reference "RFC5476, Sections 6.5.3."; 1958 } 1959 identity accuracy { 1960 base "optionsType"; 1961 description "Accuracy Report."; 1962 reference "RFC5476, Section 6.5.4."; 1963 } 1964 identity reducingRedundancy { 1965 base "optionsType"; 1966 description "Enables the utilization of Options Templates to 1967 reduce redundancy in the exported Data Records."; 1968 reference "RFC5473."; 1969 } 1970 identity extendedTypeInformation { 1971 base "optionsType"; 1972 description "Export of extended type information for 1973 enterprise-specific Information Elements used in the 1974 exported Templates."; 1975 reference "RFC5610."; 1976 } 1978 /***************************************************************** 1979 * Type definitions 1980 *****************************************************************/ 1982 typedef nameType { 1983 type string { 1984 length "1..max"; 1985 pattern "\S(.*\S)?"; 1986 } 1987 description "Type for 'name' leafs..."; 1988 } 1990 typedef direction { 1991 type enumeration { 1992 enum ingress { 1993 description "This value is used for monitoring incoming 1994 packets."; 1995 } 1996 enum egress { 1997 description "This value is used for monitoring outgoing 1998 packets."; 1999 } 2000 enum both { 2001 description "This value is used for monitoring incoming and 2002 outgoing packets."; 2003 } 2004 } 2005 description "Direction of packets going through an interface or 2006 linecard."; 2007 } 2009 typedef transportSessionStatus { 2010 type enumeration { 2011 enum inactive { 2012 description "This value MUST be used for..."; 2013 } 2014 enum active { 2015 description "This value MUST be used for..."; 2016 } 2017 enum unknown { 2018 description "This value MUST be used if the status..."; 2019 } 2020 } 2021 description "Status of a Transport Session."; 2022 reference "RFC5815, Section 8 (ipfixTransportSessionStatus)."; 2023 } 2025 /***************************************************************** 2026 * Complex types 2027 *****************************************************************/ 2029 ct:complex-type ObservationPoint { 2030 description "Observation Point"; 2031 key name; 2032 leaf name { 2033 type nameType; 2034 description "Key of an observation point."; 2035 } 2036 leaf observationPointId { 2037 type uint32; 2038 config false; 2039 description "Observation Point ID..."; 2040 reference "RFC5102, Section 5.1.10."; 2041 } 2042 leaf observationDomainId { 2043 type uint32; 2044 mandatory true; 2045 description "The Observation Domain ID associates..."; 2046 reference "RFC5101."; 2047 } 2048 choice OPLocation { 2049 mandatory true; 2050 description "Location of the Observation Point."; 2051 leaf ifIndex { 2052 type uint32; 2053 description "Index of an interface..."; 2054 reference "RFC 1229."; 2055 } 2056 leaf ifName { 2057 type string; 2058 description "Name of an interface..."; 2059 reference "RFC 1229."; 2060 } 2061 leaf entPhysicalIndex { 2062 type uint32; 2063 description "Index of a linecard..."; 2064 reference "RFC 4133."; 2065 } 2066 leaf entPhysicalName { 2067 type string; 2068 description "Name of a linecard..."; 2069 reference "RFC 4133."; 2070 } 2071 } 2072 leaf direction { 2073 type direction; 2074 default both; 2075 description "Direction of packets...."; 2076 } 2077 leaf-list selectionProcess { 2078 type instance-identifier { ct:instance-type SelectionProcess; } 2079 description "Selection Processes in this list process packets 2080 in parallel."; 2081 } 2082 } 2084 ct:complex-type Selector { 2085 ct:abstract true; 2086 description "Abstract selector"; 2087 key name; 2088 leaf name { 2089 type nameType; 2090 description "Key of a selector"; 2091 } 2092 leaf packetsObserved { 2093 type yang:counter64; 2094 config false; 2095 description "The number of packets observed ..."; 2096 reference "RFC5815, Section 8 2097 (ipfixSelectorStatsPacketsObserved)."; 2098 } 2099 leaf packetsDropped { 2100 type yang:counter64; 2101 config false; 2102 description "The total number of packets discarded ..."; 2103 reference "RFC5815, Section 8 2104 (ipfixSelectorStatsPacketsDropped)."; 2105 } 2106 leaf selectorDiscontinuityTime { 2107 type yang:date-and-time; 2108 config false; 2109 description "Timestamp of the most recent occasion at which 2110 one or more of the Selector counters suffered a 2111 discontinuity..."; 2112 reference "RFC5815, Section 8 2113 (ipfixSelectionProcessStatsDiscontinuityTime)."; 2114 } 2115 } 2117 ct:complex-type SelectAllSelector { 2118 ct:extends Selector; 2119 description "Method which selects all packets."; 2120 } 2122 ct:complex-type SampCountBasedSelector { 2123 if-feature psampSampCountBased; 2124 ct:extends Selector; 2125 description "Selector applying systematic count-based 2126 packet sampling to the packet stream."; 2127 reference "RFC5475, Section 5.1; 2128 RFC5476, Section 6.5.2.1."; 2129 leaf packetInterval { 2130 type uint32; 2131 units packets; 2132 mandatory true; 2133 description "The number of packets that are consecutively 2134 sampled between gaps of length packetSpace. 2136 This parameter corresponds to the Information Element 2137 samplingPacketInterval."; 2138 reference "RFC5477, Section 8.2.2."; 2139 } 2140 leaf packetSpace { 2141 type uint32; 2142 units packets; 2143 mandatory true; 2144 description "The number of unsampled packets between two 2145 sampling intervals. 2146 This parameter corresponds to the Information Element 2147 samplingPacketSpace."; 2148 reference "RFC5477, Section 8.2.3."; 2149 } 2150 } 2152 ct:complex-type SampTimeBasedSelector { 2153 if-feature psampSampTimeBased; 2154 ct:extends Selector; 2155 description "Selector applying systematic time-based 2156 packet sampling to the packet stream."; 2157 reference "RFC5475, Section 5.1; 2158 RFC5476, Section 6.5.2.2."; 2159 leaf timeInterval { 2160 type uint32; 2161 units microseconds; 2162 mandatory true; 2163 description "The time interval in microseconds during 2164 which all arriving packets are sampled between gaps 2165 of length timeSpace. 2166 This parameter corresponds to the Information Element 2167 samplingTimeInterval."; 2168 reference "RFC5477, Section 8.2.4."; 2169 } 2170 leaf timeSpace { 2171 type uint32; 2172 units microseconds; 2173 mandatory true; 2174 description "The time interval in microseconds during 2175 which no packets are sampled between two sampling 2176 intervals specified by timeInterval. 2177 This parameter corresponds to the Information Element 2178 samplingTimeInterval."; 2179 reference "RFC5477, Section 8.2.5."; 2180 } 2181 } 2183 ct:complex-type SampRandOutOfNSelector { 2184 if-feature psampSampRandOutOfN; 2185 ct:extends Selector; 2186 description "This container contains the configuration 2187 parameters of a Selector applying n-out-of-N packet 2188 sampling to the packet stream."; 2189 reference "RFC5475, Section 5.2.1; 2190 RFC5476, Section 6.5.2.3."; 2191 leaf size { 2192 type uint32; 2193 units packets; 2194 mandatory true; 2195 description "The number of elements taken from the parent 2196 population. 2197 This parameter corresponds to the Information Element 2198 samplingSize."; 2199 reference "RFC5477, Section 8.2.6."; 2200 } 2201 leaf population { 2202 type uint32; 2203 units packets; 2204 mandatory true; 2205 description "The number of elements in the parent 2206 population. 2207 This parameter corresponds to the Information Element 2208 samplingPopulation."; 2209 reference "RFC5477, Section 8.2.7."; 2210 } 2211 } 2213 ct:complex-type SampUniProbSelector { 2214 if-feature psampSampUniProb; 2215 ct:extends Selector; 2216 description "Selector applying uniform probabilistic 2217 packet sampling (with equal probability per packet) to the 2218 packet stream."; 2219 reference "RFC5475, Section 5.2.2.1; 2220 RFC5476, Section 6.5.2.4."; 2221 leaf probability { 2222 type decimal64 { 2223 fraction-digits 18; 2224 range "0..1"; 2225 } 2226 mandatory true; 2227 description "Probability that a packet is sampled, 2228 expressed as a value between 0 and 1. The probability 2229 is equal for every packet. 2230 This parameter corresponds to the Information Element 2231 samplingProbability."; 2233 reference "RFC5477, Section 8.2.8."; 2234 } 2235 } 2237 ct:complex-type FilterMatchSelector { 2238 if-feature psampFilterMatch; 2239 ct:extends Selector; 2240 description "This container contains the configuration 2241 parameters of a Selector applying property match filtering 2242 to the packet stream."; 2243 reference "RFC5475, Section 6.1; 2244 RFC5476, Section 6.5.2.5."; 2245 choice nameOrId { 2246 mandatory true; 2247 description "The field to be matched is specified by 2248 either the name or the ID of the Information 2249 Element."; 2250 leaf ieName { 2251 type string; 2252 description "Name of the Information Element."; 2253 } 2254 leaf ieId { 2255 type uint16 { 2256 range "1..32767" { 2257 description "Valid range of Information Element 2258 identifiers."; 2259 reference "RFC5102, Section 4."; 2260 } 2261 } 2262 description "ID of the Information Element."; 2263 } 2264 } 2265 leaf ieEnterpriseNumber { 2266 type uint32; 2267 description "If present, ... "; 2268 } 2269 leaf value { 2270 type string; 2271 mandatory true; 2272 description "Matching value of the Information Element."; 2273 } 2274 } 2276 ct:complex-type FilterHashSelector { 2277 if-feature psampFilterHash; 2278 ct:extends Selector; 2279 description "This container contains the configuration 2280 parameters of a Selector applying hash-based filtering 2281 to the packet stream."; 2282 reference "RFC5475, Section 6.2; 2283 RFC5476, Section 6.5.2.6."; 2284 leaf hashFunction { 2285 type identityref { 2286 base "hashFunction"; 2287 } 2288 default BOB; 2289 description "Hash function to be applied. According to 2290 RFC5475, Section 6.2.4.1, 'BOB' must be used in order to 2291 be compliant with PSAMP."; 2292 } 2293 leaf ipPayloadOffset { 2294 type uint64; 2295 units octets; 2296 default 0; 2297 description "IP payload offset ... "; 2298 reference "RFC5477, Section 8.3.2."; 2299 } 2300 leaf ipPayloadSize { 2301 type uint64; 2302 units octets; 2303 default 8; 2304 description "Number of IP payload bytes ... "; 2305 reference "RFC5477, Section 8.3.3."; 2306 } 2307 leaf digestOutput { 2308 type boolean; 2309 default false; 2310 description "If true, the output ... "; 2311 reference "RFC5477, Section 8.3.8."; 2312 } 2313 leaf initializerValue { 2314 type uint64; 2315 description "Initializer value to the hash function. 2316 If not configured by the user, the Monitoring Device 2317 arbitrarily chooses an initializer value."; 2318 reference "RFC5477, Section 8.3.9."; 2319 } 2320 list selectedRange { 2321 key name; 2322 min-elements 1; 2323 description "List of hash function return ranges for 2324 which packets are selected."; 2325 leaf name { 2326 type nameType; 2327 description "Key of this list."; 2328 } 2329 leaf min { 2330 type uint64; 2331 description "Beginning of the hash function's selected 2332 range. 2333 This parameter corresponds to the Information Element 2334 hashSelectedRangeMin."; 2335 reference "RFC5477, Section 8.3.6."; 2336 } 2337 leaf max { 2338 type uint64; 2339 description "End of the hash function's selected range. 2340 This parameter corresponds to the Information Element 2341 hashSelectedRangeMax."; 2342 reference "RFC5477, Section 8.3.7."; 2343 } 2344 } 2345 } 2347 ct:complex-type Cache { 2348 ct:abstract true; 2349 description "Cache of a Monitoring Device."; 2350 key name; 2351 leaf name { 2352 type nameType; 2353 description "Key of a cache"; 2354 } 2355 leaf-list exportingProcess { 2356 type leafref { path "/ipfix/exportingProcess/name"; } 2357 description "Records are exported by all Exporting Processes 2358 in the list."; 2359 } 2360 description "Configuration and state parameters of a Cache."; 2361 container cacheLayout { 2362 description "Cache Layout."; 2363 list cacheField { 2364 key name; 2365 min-elements 1; 2366 description "List of fields in the Cache Layout."; 2367 leaf name { 2368 type nameType; 2369 description "Key of this list."; 2370 } 2371 choice nameOrId { 2372 mandatory true; 2373 description "Name or ID of the Information Element."; 2374 reference "RFC5102."; 2375 leaf ieName { 2376 type string; 2377 description "Name of the Information Element."; 2378 } 2379 leaf ieId { 2380 type uint16 { 2381 range "1..32767" { 2382 description "Valid range of Information Element 2383 identifiers."; 2384 reference "RFC5102, Section 4."; 2385 } 2386 } 2387 description "ID of the Information Element."; 2388 } 2389 } 2390 leaf ieLength { 2391 type uint16; 2392 units octets; 2393 description "Length of the field ... "; 2394 reference "RFC5101, Section 6.2; RFC5102."; 2395 } 2396 leaf ieEnterpriseNumber { 2397 type uint32; 2398 description "If present, the Information Element is 2399 enterprise-specific. ... "; 2400 reference "RFC5101; RFC5102."; 2401 } 2402 leaf isFlowKey { 2403 when "(../../../cacheMode != 'immediate') 2404 and 2405 ((count(../ieEnterpriseNumber) = 0) 2406 or 2407 (../ieEnterpriseNumber != 29305))" { 2408 description "This parameter is not available 2409 for Reverse Information Elements (which have 2410 enterprise number 29305) or if the Cache Mode 2411 is 'immediate'."; 2412 } 2413 type empty; 2414 description "If present, this is a flow key."; 2415 } 2416 } 2417 } 2418 leaf dataRecords { 2419 type yang:counter64; 2420 units "Data Records"; 2421 config false; 2422 description "The number of Data Records generated ... "; 2423 reference "ietf-draft-ipfix-mib-10, Section 8 2424 (ipfixMeteringProcessDataRecords)."; 2426 } 2427 leaf cacheDiscontinuityTime { 2428 type yang:date-and-time; 2429 config false; 2430 description "Timestamp of the ... "; 2431 reference "ietf-draft-ipfix-mib-10, Section 8 2432 (ipfixMeteringProcessDiscontinuityTime)."; 2433 } 2434 } 2436 ct:complex-type ImmediateCache { 2437 if-feature cacheModeImmediate; 2438 ct:extends Cache; 2439 } 2441 ct:complex-type NonImmediateCache { 2442 ct:abstract true; 2443 ct:extends Cache; 2444 leaf maxFlows { 2445 type uint32; 2446 units flows; 2447 description "This parameter configures the maximum number of 2448 Flows in the Cache ... "; 2449 } 2450 leaf activeFlows { 2451 type yang:gauge32; 2452 units flows; 2453 config false; 2454 description "The number of Flows currently active in this 2455 Cache."; 2456 reference "ietf-draft-ipfix-mib-10, Section 8 2457 (ipfixMeteringProcessCacheActiveFlows)."; 2458 } 2459 leaf unusedCacheEntries { 2460 type yang:gauge32; 2461 units flows; 2462 config false; 2463 description "The number of unused Cache entries in this 2464 Cache."; 2465 reference "ietf-draft-ipfix-mib-10, Section 8 2466 (ipfixMeteringProcessCacheUnusedCacheEntries)."; 2467 } 2468 } 2470 ct:complex-type NonPermanentCache { 2471 ct:abstract true; 2472 ct:extends NonImmediateCache; 2473 leaf activeTimeout { 2474 type uint32; 2475 units milliseconds; 2476 description "This parameter configures the time in 2477 milliseconds after which ... "; 2478 } 2479 leaf inactiveTimeout { 2480 type uint32; 2481 units milliseconds; 2482 description "This parameter configures the time in 2483 milliseconds after which ... "; 2484 } 2485 } 2487 ct:complex-type NaturalCache { 2488 if-feature cacheModeNatural; 2489 ct:extends NonPermanentCache; 2490 } 2492 ct:complex-type TimeoutCache { 2493 if-feature cacheModeTimeout; 2494 ct:extends NonPermanentCache; 2495 } 2497 ct:complex-type PermanentCache { 2498 if-feature cacheModePermanent; 2499 ct:extends NonImmediateCache; 2500 leaf exportInterval { 2501 type uint32; 2502 units milliseconds; 2503 description "This parameter configures the interval for 2504 periodical export of Flow Records in milliseconds. 2505 If not configured by the user, the Monitoring Device sets 2506 this parameter."; 2507 } 2508 } 2510 ct:complex-type ExportDestination { 2511 ct:abstract true; 2512 description "Abstract export destination."; 2513 key name; 2514 leaf name { 2515 type nameType; 2516 description "Key of an export destination."; 2517 } 2518 } 2520 ct:complex-type IpDestination { 2521 ct:abstract true; 2522 ct:extends ExportDestination; 2523 description "IP export destination."; 2524 leaf ipfixVersion { 2525 type uint16; 2526 default 10; 2527 description "IPFIX version number."; 2528 } 2529 leaf destinationPort { 2530 type inet:port-number; 2531 description "If not configured by the user, the Monitoring 2532 Device uses the default port number for IPFIX, which is 2533 4739 without transport layer security and 4740 if transport 2534 layer security is activated."; 2535 } 2536 choice indexOrName { 2537 description "Index or name of the interface ... "; 2538 reference "RFC 1229."; 2539 leaf ifIndex { 2540 type uint32; 2541 description "Index of an interface as stored in the ifTable 2542 of IF-MIB."; 2543 reference "RFC 1229."; 2544 } 2545 leaf ifName { 2546 type string; 2547 description "Name of an interface as stored in the ifTable 2548 of IF-MIB."; 2549 reference "RFC 1229."; 2550 } 2551 } 2552 leaf sendBufferSize { 2553 type uint32; 2554 units bytes; 2555 description "Size of the socket send buffer. 2556 If not configured by the user, this parameter is set by 2557 the Monitoring Device."; 2558 } 2559 leaf rateLimit { 2560 type uint32; 2561 units "bytes per second"; 2562 description "Maximum number of bytes per second ... "; 2563 reference "RFC5476, Section 6.3"; 2564 } 2565 container transportLayerSecurity { 2566 presence "If transportLayerSecurity is present, DTLS is 2567 enabled if the transport protocol is SCTP or UDP, and TLS 2568 is enabled if the transport protocol is TCP."; 2570 description "Transport layer security configuration."; 2571 uses transportLayerSecurityParameters; 2572 } 2573 container transportSession { 2574 config false; 2575 description "State parameters of the Transport Session 2576 directed to the given destination."; 2577 uses transportSessionParameters; 2578 } 2579 } 2581 ct:complex-type SctpExporter { 2582 ct:extends IpDestination; 2583 description "SCTP exporter."; 2584 leaf-list sourceIPAddress { 2585 type inet:ip-address; 2586 description "List of source IP addresses used ... "; 2587 reference "RFC 4960 (multi-homed SCTP endpoint)."; 2588 } 2589 leaf-list destinationIPAddress { 2590 type inet:ip-address; 2591 min-elements 1; 2592 description "One or multiple IP addresses ... "; 2593 reference "RFC 4960 (multi-homed SCTP endpoint)."; 2594 } 2595 leaf timedReliability { 2596 type uint32; 2597 units milliseconds; 2598 default 0; 2599 description "Lifetime in milliseconds ... "; 2600 reference "RFC 3758; RFC 4960."; 2601 } 2602 } 2604 ct:complex-type UdpExporter { 2605 ct:extends IpDestination; 2606 if-feature udpTransport; 2607 description "UDP parameters."; 2608 leaf sourceIPAddress { 2609 type inet:ip-address; 2610 description "Source IP address used by the Exporting 2611 Process ..."; 2612 } 2613 leaf destinationIPAddress { 2614 type inet:ip-address; 2615 mandatory true; 2616 description "IP address of the Collection Process to which 2617 IPFIX Messages are sent."; 2619 } 2620 leaf maxPacketSize { 2621 type uint16; 2622 units octets; 2623 description "This parameter specifies the maximum size of 2624 IP packets ... "; 2625 } 2626 leaf templateRefreshTimeout { 2627 type uint32; 2628 units seconds; 2629 default 600; 2630 description "Sets time after which Templates are resent in the 2631 UDP Transport Session. ... "; 2632 reference "RFC5101, Section 10.3.6; RFC5815, Section 8 2633 (ipfixTransportSessionTemplateRefreshTimeout)."; 2634 } 2635 leaf optionsTemplateRefreshTimeout { 2636 type uint32; 2637 units seconds; 2638 default 600; 2639 description "Sets time after which Options Templates are 2640 resent in the UDP Transport Session. ... "; 2641 reference "RFC5101, Section 10.3.6; RFC5815, Section 8 2642 (ipfixTransportSessionOptionsTemplateRefreshTimeout)."; 2643 } 2644 leaf templateRefreshPacket { 2645 type uint32; 2646 units "IPFIX Messages"; 2647 description "Sets number of IPFIX Messages after which 2648 Templates are resent in the UDP Transport Session. ... "; 2649 reference "RFC5101, Section 10.3.6; RFC5815, Section 8 2650 (ipfixTransportSessionTemplateRefreshPacket)."; 2651 } 2652 leaf optionsTemplateRefreshPacket { 2653 type uint32; 2654 units "IPFIX Messages"; 2655 description "Sets number of IPFIX Messages after which 2656 Options Templates are resent in the UDP Transport Session 2657 protocol. ... "; 2658 reference "RFC5101, Section 10.3.6; RFC5815, Section 8 2659 (ipfixTransportSessionOptionsTemplateRefreshPacket)."; 2660 } 2661 } 2663 ct:complex-type TcpExporter { 2664 ct:extends IpDestination; 2665 if-feature tcpTransport; 2666 description "TCP exporter"; 2667 leaf sourceIPAddress { 2668 type inet:ip-address; 2669 description "Source IP address used by the Exporting 2670 Process..."; 2671 } 2672 leaf destinationIPAddress { 2673 type inet:ip-address; 2674 mandatory true; 2675 description "IP address of the Collection Process to which 2676 IPFIX Messages are sent."; 2677 } 2678 } 2680 ct:complex-type FileWriter { 2681 ct:extends ExportDestination; 2682 if-feature fileWriter; 2683 description "File Writer."; 2684 leaf ipfixVersion { 2685 type uint16; 2686 default 10; 2687 description "IPFIX version number."; 2688 } 2689 leaf file { 2690 type inet:uri; 2691 mandatory true; 2692 description "URI specifying the location of the file."; 2693 } 2694 leaf bytes { 2695 type yang:counter64; 2696 units octets; 2697 config false; 2698 description "The number of bytes written by the File 2699 Writer..."; 2700 } 2701 leaf messages { 2702 type yang:counter64; 2703 units "IPFIX Messages"; 2704 config false; 2705 description "The number of IPFIX Messages written by the File 2706 Writer. ... "; 2707 } 2708 leaf discardedMessages { 2709 type yang:counter64; 2710 units "IPFIX Messages"; 2711 config false; 2712 description "The number of IPFIX Messages that could not be 2713 written by the File Writer ... "; 2714 } 2715 leaf records { 2716 type yang:counter64; 2717 units "Data Records"; 2718 config false; 2719 description "The number of Data Records written by the File 2720 Writer. ... "; 2721 } 2722 leaf templates { 2723 type yang:counter32; 2724 units "Templates"; 2725 config false; 2726 description "The number of Template Records (excluding 2727 Options Template Records) written by the File Writer. 2728 ... "; 2729 } 2730 leaf optionsTemplates { 2731 type yang:counter32; 2732 units "Options Templates"; 2733 config false; 2734 description "The number of Options Template Records written 2735 by the File Writer. ... "; 2736 } 2737 leaf fileWriterDiscontinuityTime { 2738 type yang:date-and-time; 2739 config false; 2740 description "Timestamp of the most recent occasion at which 2741 one or more File Writer counters suffered a discontinuity. 2742 ... "; 2743 } 2744 list template { 2745 config false; 2746 description "This list contains the Templates and Options 2747 Templates that have been written by the File Reader. ... "; 2748 uses templateParameters; 2749 } 2750 } 2752 ct:complex-type ExportingProcess { 2753 if-feature exporter; 2754 description "Exporting Process of the Monitoring Device."; 2755 key name; 2756 leaf name { 2757 type nameType; 2758 description "Key of this list."; 2759 } 2760 leaf exportMode { 2761 type identityref { 2762 base "exportMode"; 2764 } 2765 default parallel; 2766 description "This parameter determines to which configured 2767 destination(s) the incoming Data Records are exported."; 2768 } 2769 ct:instance-list destination { 2770 ct:instance-type ExportDestination; 2771 min-elements 1; 2772 description "Export destinations."; 2773 } 2774 list options { 2775 key name; 2776 description "List of options reported by the Exporting 2777 Process."; 2778 leaf name { 2779 type nameType; 2780 description "Key of this list."; 2781 } 2782 leaf optionsType { 2783 type identityref { 2784 base "optionsType"; 2785 } 2786 mandatory true; 2787 description "Type of the exported options data."; 2788 } 2789 leaf optionsTimeout { 2790 type uint32; 2791 units milliseconds; 2792 description "Time interval for periodic export of the options 2793 data. ... "; 2794 } 2795 } 2796 } 2798 ct:complex-type CollectingProcess { 2799 description "A Collecting Process."; 2800 key name; 2801 leaf name { 2802 type nameType; 2803 description "Key of a collecing process."; 2804 } 2805 ct:instance-list sctpCollector { 2806 ct:instance-type SctpCollector; 2807 description "List of SCTP receivers (sockets) on which the 2808 Collecting Process receives IPFIX Messages."; 2809 } 2810 ct:instance-list udpCollector { 2811 if-feature udpTransport; 2812 ct:instance-type UdpCollector; 2813 description "List of UDP receivers (sockets) on which the 2814 Collecting Process receives IPFIX Messages."; 2815 } 2816 ct:instance-list tcpCollector { 2817 if-feature tcpTransport; 2818 ct:instance-type TcpCollector; 2819 description "List of TCP receivers (sockets) on which the 2820 Collecting Process receives IPFIX Messages."; 2821 } 2822 ct:instance-list fileReader { 2823 if-feature fileReader; 2824 ct:instance-type FileReader; 2825 description "List of File Readers from which the Collecting 2826 Process reads IPFIX Messages."; 2827 } 2828 leaf-list exportingProcess { 2829 type instance-identifier { ct:instance-type ExportingProcess; } 2830 description "Export of received records without any 2831 modifications. Records are processed by all Exporting 2832 Processes in the list."; 2833 } 2834 } 2836 ct:complex-type Collector { 2837 ct:abstract true; 2838 description "Abstract collector."; 2839 key name; 2840 leaf name { 2841 type nameType; 2842 description "Key of collectors"; 2843 } 2844 } 2846 ct:complex-type IpCollector { 2847 ct:abstract true; 2848 ct:extends Collector; 2849 description "Collector for IP transport protocols."; 2850 leaf localPort { 2851 type inet:port-number; 2852 description "If not configured, the Monitoring Device uses the 2853 default port number for IPFIX, which is 4739 without 2854 transport layer security and 4740 if transport layer 2855 security is activated."; 2856 } 2857 container transportLayerSecurity { 2858 presence "If transportLayerSecurity is present, DTLS is enabled 2859 if the transport protocol is SCTP or UDP, and TLS is enabled 2860 if the transport protocol is TCP."; 2861 description "Transport layer security configuration."; 2862 uses transportLayerSecurityParameters; 2863 } 2864 list transportSession { 2865 config false; 2866 description "This list contains the currently established 2867 Transport Sessions terminating at the given socket."; 2868 uses transportSessionParameters; 2869 } 2870 } 2872 ct:complex-type SctpCollector { 2873 ct:extends IpCollector; 2874 description "Collector listening on aSCTP socket"; 2875 leaf-list localIPAddress { 2876 type inet:ip-address; 2877 description "List of local IP addresses ... "; 2878 reference "RFC 4960 (multi-homed SCTP endpoint)."; 2879 } 2880 } 2882 ct:complex-type UdpCollector { 2883 ct:extends IpCollector; 2884 description "Parameters of a listening UDP socket at a 2885 Collecting Process."; 2886 leaf-list localIPAddress { 2887 type inet:ip-address; 2888 description "List of local IP addresses on which the Collecting 2889 Process listens for IPFIX Messages."; 2890 } 2891 leaf templateLifeTime { 2892 type uint32; 2893 units seconds; 2894 default 1800; 2895 description "Sets the lifetime of Templates for all UDP 2896 Transport Sessions ... "; 2897 reference "RFC5101, Section 10.3.7; RFC5815, Section 8 2898 (ipfixTransportSessionTemplateRefreshTimeout)."; 2899 } 2900 leaf optionsTemplateLifeTime { 2901 type uint32; 2902 units seconds; 2903 default 1800; 2904 description "Sets the lifetime of Options Templates for all 2905 UDP Transport Sessions terminating at this UDP socket. 2906 ... "; 2907 reference "RFC5101, Section 10.3.7; RFC5815, Section 8 2908 (ipfixTransportSessionOptionsTemplateRefreshTimeout)."; 2909 } 2910 leaf templateLifePacket { 2911 type uint32; 2912 units "IPFIX Messages"; 2913 description "If this parameter is configured, Templates 2914 defined in a UDP Transport Session become invalid if ..."; 2915 reference "RFC5101, Section 10.3.7; RFC5815, Section 8 2916 (ipfixTransportSessionTemplateRefreshPacket)."; 2917 } 2918 leaf optionsTemplateLifePacket { 2919 type uint32; 2920 units "IPFIX Messages"; 2921 description "If this parameter is configured, Options 2922 Templates defined in a UDP Transport Session become 2923 invalid if ..."; 2924 reference "RFC5101, Section 10.3.7; RFC5815, Section 8 2925 (ipfixTransportSessionOptionsTemplateRefreshPacket)."; 2926 } 2927 } 2929 ct:complex-type TcpCollector { 2930 ct:extends IpCollector; 2931 description "Collector listening on a TCP socket."; 2932 leaf-list localIPAddress { 2933 type inet:ip-address; 2934 description "List of local IP addresses on which the Collecting 2935 Process listens for IPFIX Messages."; 2936 } 2937 } 2939 ct:complex-type FileReader { 2940 ct:extends Collector; 2941 description "File Reading collector."; 2942 leaf file { 2943 type inet:uri; 2944 mandatory true; 2945 description "URI specifying the location of the file."; 2946 } 2947 leaf bytes { 2948 type yang:counter64; 2949 units octets; 2950 config false; 2951 description "The number of bytes read by the File Reader. 2952 ... "; 2953 } 2954 leaf messages { 2955 type yang:counter64; 2956 units "IPFIX Messages"; 2957 config false; 2958 description "The number of IPFIX Messages read by the File 2959 Reader. ... "; 2960 } 2961 leaf records { 2962 type yang:counter64; 2963 units "Data Records"; 2964 config false; 2965 description "The number of Data Records read by the File 2966 Reader. ... "; 2967 } 2968 leaf templates { 2969 type yang:counter32; 2970 units "Templates"; 2971 config false; 2972 description "The number of Template Records (excluding 2973 Options Template Records) read by the File Reader. ..."; 2974 } 2975 leaf optionsTemplates { 2976 type yang:counter32; 2977 units "Options Templates"; 2978 config false; 2979 description "The number of Options Template Records read by 2980 the File Reader. ... "; 2981 } 2982 leaf fileReaderDiscontinuityTime { 2983 type yang:date-and-time; 2984 config false; 2985 description "Timestamp of the most recent occasion ... "; 2986 } 2987 list template { 2988 config false; 2989 description "This list contains the Templates and Options 2990 Templates that have been read by the File Reader. 2991 Withdrawn or invalidated (Options) Template MUST be removed 2992 from this list."; 2993 uses templateParameters; 2994 } 2995 } 2997 ct:complex-type SelectionProcess { 2998 description "Selection Process"; 2999 key name; 3000 leaf name { 3001 type nameType; 3002 description "Key of a selection process."; 3003 } 3004 ct:instance-list selector { 3005 ct:instance-type Selector; 3006 min-elements 1; 3007 ordered-by user; 3008 description "List of Selectors that define the action of the 3009 Selection Process on a single packet. The Selectors are 3010 serially invoked in the same order as they appear in this 3011 list."; 3012 } 3013 list selectionSequence { 3014 config false; 3015 description "This list contains the Selection Sequence IDs 3016 which are assigned by the Monitoring Device ... "; 3017 reference "RFC5476."; 3018 leaf observationDomainId { 3019 type uint32; 3020 description "Observation Domain ID for which the 3021 Selection Sequence ID is assigned."; 3022 } 3023 leaf selectionSequenceId { 3024 type uint64; 3025 description "Selection Sequence ID used in the Selection 3026 Sequence (Statistics) Report Interpretation."; 3027 } 3028 } 3029 leaf cache { 3030 type instance-identifier { ct:instance-type Cache; } 3031 description "Cache which receives the output of the 3032 Selection Process."; 3033 } 3034 } 3036 /***************************************************************** 3037 * Groupings 3038 *****************************************************************/ 3040 grouping transportLayerSecurityParameters { 3041 description "Transport layer security parameters."; 3042 leaf-list localCertificationAuthorityDN { 3043 type string; 3044 description "Distinguished names of certification authorities 3045 whose certificates may be used to identify the local 3046 endpoint."; 3047 } 3048 leaf-list localSubjectDN { 3049 type string; 3050 description "Distinguished names which may be used in the 3051 certificates to identify the local endpoint."; 3053 } 3054 leaf-list localSubjectFQDN { 3055 type inet:domain-name; 3056 description "Fully qualified domain names which may be used to 3057 in the certificates to identify the local endpoint."; 3058 } 3059 leaf-list remoteCertificationAuthorityDN { 3060 type string; 3061 description "Distinguished names of certification authorities 3062 whose certificates are accepted to authorize remote 3063 endpoints."; 3064 } 3065 leaf-list remoteSubjectDN { 3066 type string; 3067 description "Distinguished names which are accepted in 3068 certificates to authorize remote endpoints."; 3069 } 3070 leaf-list remoteSubjectFQDN { 3071 type inet:domain-name; 3072 description "Fully qualified domain name which are accepted in 3073 certificates to authorize remote endpoints."; 3074 } 3075 } 3077 grouping templateParameters { 3078 description "State parameters of a Template used by an Exporting 3079 Process or received by a Collecting Process ... "; 3080 reference "RFC5101; RFC5815, Section 8 (ipfixTemplateEntry, 3081 ipfixTemplateDefinitionEntry, ipfixTemplateStatsEntry)"; 3082 leaf observationDomainId { 3083 type uint32; 3084 description "The ID of the Observation Domain for which this 3085 Template is defined."; 3086 reference "RFC5815, Section 8 3087 (ipfixTemplateObservationDomainId)."; 3088 } 3089 leaf templateId { 3090 type uint16 { 3091 range "256..65535" { 3092 description "Valid range of Template IDs."; 3093 reference "RFC5101"; 3094 } 3095 } 3096 description "This number indicates the Template Id in the IPFIX 3097 message."; 3098 reference "RFC5815, Section 8 (ipfixTemplateId)."; 3099 } 3100 leaf setId { 3101 type uint16; 3102 description "This number indicates the Set ID of the Template. 3103 ... "; 3104 reference "RFC5815, Section 8 (ipfixTemplateSetId)."; 3105 } 3106 leaf accessTime { 3107 type yang:date-and-time; 3108 description "Used for Exporting Processes, ... "; 3109 reference "RFC5815, Section 8 (ipfixTemplateAccessTime)."; 3110 } 3111 leaf templateDataRecords { 3112 type yang:counter64; 3113 description "The number of transmitted or received Data 3114 Records ... "; 3115 reference "RFC5815, Section 8 (ipfixTemplateDataRecords)."; 3116 } 3117 leaf templateDiscontinuityTime { 3118 type yang:date-and-time; 3119 description "Timestamp of the most recent occasion at which 3120 the counter templateDataRecords suffered a discontinuity. 3121 ... "; 3122 reference "RFC5815, Section 8 3123 (ipfixTemplateDiscontinuityTime)."; 3124 } 3125 list field { 3126 description "This list contains the (Options) Template 3127 fields of which the (Options) Template is defined. 3128 ... "; 3129 leaf ieId { 3130 type uint16 { 3131 range "1..32767" { 3132 description "Valid range of Information Element 3133 identifiers."; 3134 reference "RFC5102, Section 4."; 3135 } 3136 } 3137 description "This parameter indicates the Information 3138 Element Id of the field."; 3139 reference "RFC5815, Section 8 (ipfixTemplateDefinitionIeId); 3140 RFC5102."; 3141 } 3142 leaf ieLength { 3143 type uint16; 3144 units octets; 3145 description "This parameter indicates the length of the 3146 Information Element of the field."; 3147 reference "RFC5815, Section 8 3148 (ipfixTemplateDefinitionIeLength); RFC5102."; 3150 } 3151 leaf ieEnterpriseNumber { 3152 type uint32; 3153 description "This parameter indicates the IANA enterprise 3154 number of the authority ... "; 3155 reference "RFC5815, Section 8 3156 (ipfixTemplateDefinitionIeEnterpriseNumber)."; 3157 } 3158 leaf isFlowKey { 3159 when "../../setId = 2" { 3160 description "This parameter is available for non-Options 3161 Templates (Set ID is 2)."; 3162 } 3163 type empty; 3164 description "If present, this is a Flow Key field."; 3165 reference "RFC5815, Section 8 3166 (ipfixTemplateDefinitionFlags)."; 3167 } 3168 leaf isScope { 3169 when "../../setId = 3" { 3170 description "This parameter is available for Options 3171 Templates (Set ID is 3)."; 3172 } 3173 type empty; 3174 description "If present, this is a scope field."; 3175 reference "RFC5815, Section 8 3176 (ipfixTemplateDefinitionFlags)."; 3177 } 3178 } 3179 } 3181 grouping transportSessionParameters { 3182 description "State parameters of a Transport Session ... "; 3183 reference "RFC5101, RFC5815, Section 8 3184 (ipfixTransportSessionEntry, 3185 ipfixTransportSessionStatsEntry)"; 3186 leaf ipfixVersion { 3187 type uint16; 3188 description "Used for Exporting Processes, this parameter 3189 contains the version number of the IPFIX protocol ... "; 3190 reference "RFC5815, Section 8 3191 (ipfixTransportSessionIpfixVersion)."; 3192 } 3193 leaf sourceAddress { 3194 type inet:ip-address; 3195 description "The source address of the Exporter of the 3196 IPFIX Transport Session... "; 3197 reference "RFC5815, Section 8 3198 (ipfixTransportSessionSourceAddressType, 3199 ipfixTransportSessionSourceAddress)."; 3200 } 3201 leaf destinationAddress { 3202 type inet:ip-address; 3203 description "The destination address of the Collector of 3204 the IPFIX Transport Session... "; 3205 reference "RFC5815, Section 8 3206 (ipfixTransportSessionDestinationAddressType, 3207 ipfixTransportSessionDestinationAddress)."; 3208 } 3209 leaf sourcePort { 3210 type inet:port-number; 3211 description "The transport protocol port number of the 3212 Exporter of the IPFIX Transport Session."; 3213 reference "RFC5815, Section 8 3214 (ipfixTransportSessionSourcePort)."; 3215 } 3216 leaf destinationPort { 3217 type inet:port-number; 3218 description "The transport protocol port number of the 3219 Collector of the IPFIX Transport Session... "; 3220 reference "RFC5815, Section 8 3221 (ipfixTransportSessionDestinationPort)."; 3222 } 3223 leaf sctpAssocId { 3224 type uint32; 3225 description "The association id used for the SCTP session 3226 between the Exporter and the Collector ... "; 3227 reference "RFC5815, Section 8 3228 (ipfixTransportSessionSctpAssocId), 3229 RFC3871"; 3230 } 3231 leaf status { 3232 type transportSessionStatus; 3233 description "Status of the Transport Session."; 3234 reference "RFC5815, Section 8 (ipfixTransportSessionStatus)."; 3235 } 3236 leaf rate { 3237 type yang:gauge32; 3238 units "bytes per second"; 3239 description "The number of bytes per second transmitted by the 3240 Exporting Process or received by the Collecting Process. 3241 This parameter is updated every second."; 3242 reference "RFC5815, Section 8 (ipfixTransportSessionRate)."; 3243 } 3244 leaf bytes { 3245 type yang:counter64; 3246 units bytes; 3247 description "The number of bytes transmitted by the 3248 Exporting Process or received by the Collecting 3249 Process ... "; 3250 reference "RFC5815, Section 8 (ipfixTransportSessionBytes)."; 3251 } 3252 leaf messages { 3253 type yang:counter64; 3254 units "IPFIX Messages"; 3255 description "The number of messages transmitted by the 3256 Exporting Process or received by the Collecting Process... "; 3257 reference "RFC5815, Section 8 3258 (ipfixTransportSessionMessages)."; 3259 } 3260 leaf discardedMessages { 3261 type yang:counter64; 3262 units "IPFIX Messages"; 3263 description "Used for Exporting Processes, this parameter 3264 indicates the number of messages that could not be 3265 sent ..."; 3266 reference "RFC5815, Section 8 3267 (ipfixTransportSessionDiscardedMessages)."; 3268 } 3269 leaf records { 3270 type yang:counter64; 3271 units "Data Records"; 3272 description "The number of Data Records transmitted ... "; 3273 reference "RFC5815, Section 8 3274 (ipfixTransportSessionRecords)."; 3275 } 3276 leaf templates { 3277 type yang:counter32; 3278 units "Templates"; 3279 description "The number of Templates transmitted by the 3280 Exporting Process or received by the Collecting Process. 3281 ... "; 3282 reference "RFC5815, Section 8 3283 (ipfixTransportSessionTemplates)."; 3284 } 3285 leaf optionsTemplates { 3286 type yang:counter32; 3287 units "Options Templates"; 3288 description "The number of Option Templates transmitted by the 3289 Exporting Process or received by the Collecting Process..."; 3290 reference "RFC5815, Section 8 3291 (ipfixTransportSessionOptionsTemplates)."; 3292 } 3293 leaf transportSessionStartTime { 3294 type yang:date-and-time; 3295 description "Timestamp of the start of the given Transport 3296 Session... "; 3297 } 3298 leaf transportSessionDiscontinuityTime { 3299 type yang:date-and-time; 3300 description "Timestamp of the most recent occasion at which 3301 one or more of the Transport Session counters suffered a 3302 discontinuity... "; 3303 reference "RFC5815, Section 8 3304 (ipfixTransportSessionDiscontinuityTime)."; 3305 } 3306 list template { 3307 description "This list contains the Templates and Options 3308 Templates that are transmitted by the Exporting Process 3309 or received by the Collecting Process. 3310 Withdrawn or invalidated (Options) Template MUST be removed 3311 from this list."; 3312 uses templateParameters; 3313 } 3314 } 3316 /***************************************************************** 3317 * Main container 3318 *****************************************************************/ 3320 container ipfix { 3321 description "Top-level node of the IPFIX/PSAMP configuration 3322 data model."; 3324 ct:instance-list collectingProcess { 3325 if-feature collector; 3326 ct:instance-type CollectingProcess; 3327 } 3329 ct:instance-list observationPoint { 3330 if-feature meter; 3331 ct:instance-type ObservationPoint; 3332 } 3334 ct:instance-list selectionProcess { 3335 if-feature meter; 3336 ct:instance-type SelectionProcess; 3337 } 3339 ct:instance-list cache { 3340 if-feature meter; 3341 description "Cache of the Monitoring Device."; 3342 ct:instance-type Cache; 3343 } 3345 ct:instance-list exportingProcess { 3346 if-feature exporter; 3347 description "Exporting Process of the Monitoring Device."; 3348 ct:instance-type ExportingProcess; 3349 } 3351 } 3352 } 3353 3355 Appendix C. Change Log 3357 C.1. 04-05 3359 Editorial bug fixing. 3361 C.2. 03-04 3363 o Changed the complex type XML encoding rules so that XML elements 3364 reprensenting data nodes defined in the same complex type may 3365 appear in any order. 3367 o Used the "ct:" prefix in substatement tables when referring to 3368 complex type extension statements. 3370 o Modeled the IPFIX/PSMAP example based on v-07 of the IPFIX 3371 configuration draft. Changed motivation text accordingly. 3373 o Minor updates and clarifications in the text. 3375 C.3. 02-03 3377 o Added an example based on the physical resource modeling concepts 3378 of SID. A simplified class diagram and an excerpt of an according 3379 YANG module were added in the introduction section. 3381 o Changed the example YANG module in the NETCONF payload section to 3382 be based on the physical resource types defined in the added 3383 physical resource model. 3385 o A second example shows how Entity MIB entries can be modeled as 3386 physical resources. The example includes a class diagram and an 3387 according YANG module excerpt. 3389 o The complete YANG modules for both examples were added into the 3390 appendix. 3392 o Changed the complex type encoding rules. 3394 o Updated the NETCONF payload example the changed type encoding 3395 rules and the changed example module. 3397 o Changed the augmentation rules for complex types. Instead of 3398 using "." as argument in the augment statement, instance and 3399 instance-list statement may now contain additional data node 3400 statements. The substatement tables for the instance and 3401 instance-list statements were updated accordingly. 3403 o Minor updates in the text and examples. 3405 C.4. 01-02 3407 o It is no longer allowed to use the "config" statement inside a 3408 complex type definition. 3410 o Complex type can now be defined where a grouping can be defined. 3411 Complex types have their own namespace. 3413 o Explicitly specified which kind of refinements can be applied to 3414 elements of the base type in the definition of an extending 3415 complex type. 3417 o Confined the use of deviations for complex types to complex type 3418 instantiations. 3420 o Defined augmentation of complex types allowing augmentation only 3421 during instantiation via an "instance" or "instance-list" 3422 statement. 3424 o Removed leftovers from substatement tables. 3426 o Updates and bug-fixes in the examples. 3428 C.5. 00-01 3430 o Transformed proposed new YANG statements to YANG extension 3431 statements (complex-type, element, extends, abstract). 3433 o Renamed statement "element" to the extension statement "instance" 3434 in order to avoid confusion with XML payload elements. 3436 o Introduced extension statement "instance-type" as allowing the use 3437 of the existing "type" statement as substatement in the existing 3438 "instance-identifier" statement cannot be done with extensions. 3440 o Added the complex type extension statement module. 3442 o Updated examples to reflect the changes mentioned above. 3444 o Added update rules for complex types. 3446 o Updated IANA Considerations section. 3448 o Added this change log. 3450 Authors' Addresses 3452 Bernd Linowski 3453 TCS/Nokia Siemens Networks 3454 Heltorfer Strasse 1 3455 Duesseldorf 40472 3456 Germany 3458 EMail: bernd.linowski@ext.nsn.com 3460 Mehmet Ersue 3461 Nokia Siemens Networks 3462 St.-Martin-Strasse 53 3463 Munich 81541 3464 Germany 3466 EMail: mehmet.ersue@nsn.com 3468 Siarhei Kuryla 3469 360 Treasury Systems 3470 Grueneburgweg 16-18 3471 Frankfurt am Main 60322 3472 Germany 3474 EMail: s.kuryla@gmail.com