idnits 2.17.1 draft-zhuang-netmod-yang-poe-management-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 12 instances of too long lines in the document, the longest one being 20 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 180 has weird spacing: '...-events ide...' == Line 187 has weird spacing: '...g-power uin...' == Line 262 has weird spacing: '...-events ide...' == Line 269 has weird spacing: '...g-power uin...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (July 26, 2017) is 2465 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'IEEE-802.3.2' is defined on line 685, but no explicit reference was found in the text == Unused Reference: 'IEEE-802.3af' is defined on line 689, but no explicit reference was found in the text == Unused Reference: 'IEEE-802.3bt' is defined on line 698, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-802.3.2' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-802.3af' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-802.3at' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-802.3bt' Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group Y. Zhuang 3 Internet-Draft Huawei 4 Intended status: Standards Track July 26, 2017 5 Expires: January 27, 2018 7 A YANG Data Model for Power over Ethernet System management 8 draft-zhuang-netmod-yang-poe-management-02 10 Abstract 12 This memo defines a YANG data model for Power over Ethernet System 13 for use with network management protocols. This document augments 14 the IEEE 802.3 PSE module with attributes to manage PSE port and 15 provide notification of powering states. Besides, it also provides 16 power source management for the whole system. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 27, 2018. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Definitions an Acronyms . . . . . . . . . . . . . . . . . . . 2 54 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 55 2.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 2 56 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 4. Design of the data model . . . . . . . . . . . . . . . . . . 4 58 4.1. Main Power Source management . . . . . . . . . . . . . . 5 59 4.2. PSE port management . . . . . . . . . . . . . . . . . . . 6 60 4.3. Notification . . . . . . . . . . . . . . . . . . . . . . 7 61 5. POE Power Management module . . . . . . . . . . . . . . . . . 7 62 6. Security Consideration . . . . . . . . . . . . . . . . . . . 16 63 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 64 8. Normative References . . . . . . . . . . . . . . . . . . . . 16 65 Appendix A. Related modules . . . . . . . . . . . . . . . . . . 16 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 68 1. Introduction 70 This document defines a YANG [RFC7950] data model for the management 71 of power over Ethernet [IEEE 802.3at] Power Sourcing Equipment (PSE). 73 2. Definitions an Acronyms 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in [RFC2119]. 79 2.1. Terminology 81 The following abbreviations are defined in [IEEE-802.3at] and will be 82 used with the same significance in this document: 84 PSE - Power Sourcing Equipment; 86 PD - Powered Device 88 2.2. Tree diagram 90 The following notations are used within the data tree and carry the 91 meaning as below. 93 Each node is printed as: 94 96 is one of: 97 + for current 98 x for deprecated 99 o for obsolete 100 is one of: 101 rw for configuration data 102 ro for non-configuration data 103 -x for rpcs 104 -n for notifications 105 is the name of the node 107 If the node is augmented into the tree from another module, its name 108 is printed as :. 109 is one of: 110 ? for an optional leaf or choice 111 ! for a presence container 112 * for a leaf-list or list 113 [] for a list's keys 114 is the name of the type for leafs and leaf-lists 116 In this document, these words will appear with that interpretation 117 only when in ALL CAPS. Lower case uses of these words are not to be 118 interpreted as carrying RFC-2119 significance. 120 3. Overview 122 Power over Ethernet (PoE) provides a way to allows devices receiving 123 power over the same cable used for data transmission. It also 124 enables applications of powered devices connected to the network and 125 managed by a remote management application. The IEEE 802.3 Working 126 Group has finished two standardization projects on this subject, 127 known as IEEE 802.3af and IEEE 802.3at. 129 With the increase of required power level in nowadays, the Working 130 Group is now working on the 4-pair PoE which provides up to 90 watts 131 powering known as IEEE 802.3bt [IEEE 802.3bt] to enable more 132 applications such as lighting over Ethernet for intelligent lighting 133 system. 135 The IEEE 802.3 WG is currently also working on a YANG data model for 136 the management of Power Source Equipment in [IEEE P802.3.2], however, 137 it did not define a full management interface, but only the managed 138 objects based on the hardware registers. The module defined in this 139 document is an extension to that module to provide management 140 required for the poe system and ports as defined in Power Ethernet 141 MIB[RFC3621], so as to be used by the system administrator for 142 management. 144 4. Design of the data model 146 This document defines the YANG module "ietf-poe-power-management", 147 which has two parts: main power source management and pse port 148 management. Besides, the module also defines several notifications 149 for the port and power source. The model structure is as follows: 151 module: ietf-poe-power-management 152 +--rw main-power-source-config 153 | +--rw main-power-source-entry* [slot-id] 154 | +--rw slot-id uint32 155 | +--rw usage-threshold? percentage 156 +--ro main-power-sources-state 157 +--ro main-power-source-entry* [slot-id] 158 +--ro slot-id uint32 159 +--ro power-info 160 | +--ro total-power? decimal64 161 | +--ro reserved-power? percentage 162 | +--ro consuming-power? decimal64 163 | +--ro remained-power? decimal64 164 | +--ro peak-power? decimal64 165 | +--ro usage-threshold? percentage 166 +--ro operStatus? enumeration 167 augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse: 168 +--rw event-notification-enable? boolean 169 augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair: 170 +--rw poe-ports-config 171 +--rw power-priority? uint32 172 +--rw connected-pd-type? string 173 notifications: 174 +---n poe-port-notification 175 | +--ro event* [if-name event-type] 176 | +--ro if-name string 177 | +--ro event-type identityref 178 | +--ro event-content 179 | +--ro detection-status? pse-detection-state 180 | +--ro pd-connection-events identityref 181 +---n poe-power-notification 182 +--ro event* [slot-id event-type] 183 +--ro slot-id uint8 184 +--ro event-type identityref 185 +--ro event-content 186 +--ro power-usage 187 +--ro consuming-power uint32 188 +--ro usage-threshold? uint32 190 4.1. Main Power Source management 192 As defined Power Etherent MIB[RFC3621], the main power source 193 container defines the management attributes for a managed main power 194 source in a PSE device. Ethernet switches are one example of boxes 195 that would support these objects. 197 module: poe-power-management 198 +--rw main-power-source-config 199 | +--rw main-power-source-entry* [slot-id] 200 | +--rw slot-id uint32 201 | +--rw usage-threshold? percentage 202 +--ro main-power-sources-state 203 +--ro main-power-source-entry* [slot-id] 204 +--ro slot-id uint32 205 +--ro power-info 206 | +--ro total-power? decimal64 207 | +--ro reserved-power? percentage 208 | +--ro consuming-power? decimal64 209 | +--ro remained-power? decimal64 210 | +--ro peak-power? decimal64 211 | +--ro usage-threshold? percentage 212 +--ro operStatus? enumeration 214 Container "poe-power-management" contains a list of main power source 215 entry in both configuration and operational state. In configuration, 216 the entry contains a slot-id node to indicate its belonged chassis 217 id. It also provides a usage-threhold to express in percents for 218 comparing the measured power and initiating an alarm if the threshold 219 is exceeded. 221 For the operational state, the main power source entry provides power 222 information for the management, including the total power, reserved 223 power, consuming power, remained power, peak power etc al. It also 224 provide "operStauts" node to indicate current operational status of 225 the main PSE whether it is on/off/faulty. 227 4.2. PSE port management 229 The pse port management augments the YANG module "ieee802-pse.yang" 230 with extra management objects defined in Power Ethernet MIB [RFC3621] 231 for required management of the pse ports. 233 augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse: 234 +--rw event-notification-enable? boolean 235 augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair: 236 +--rw poe-ports-config 237 +--rw power-priority? uint32 238 +--rw connected-pd-type? String 240 Under the poe-pse container in ieee802-pse module, this document 241 defines a data node to control the notification of event. Besides, 242 for the multiple pair PSE, it defines power priority as 243 pethPsePortPowerPrority object defined in PoE MIB to control the 244 priority of the port from the point of view of a power management 245 system. The node "connected-pd-type" is the same as the 246 pethPsePortType object in PoE MIB for a managr to indicate the type 247 of the powered device that is connected to the port. 249 4.3. Notification 251 Consist with notifications defined in Power Etherent MIB [RFC3621], 252 this document also provides notifications for pse ports and power 253 source to be transmitted from the agent to a management application. 255 notifications: 256 +---n poe-port-notification 257 | +--ro event* [if-name event-type] 258 | +--ro if-name string 259 | +--ro event-type identityref 260 | +--ro event-content 261 | +--ro detection-status? pse-detection-state 262 | +--ro pd-connection-events identityref 263 +---n poe-power-notification 264 +--ro event* [slot-id event-type] 265 +--ro slot-id uint8 266 +--ro event-type identityref 267 +--ro event-content 268 +--ro power-usage 269 +--ro consuming-power uint32 270 +--ro usage-threshold? uint32 272 This module defines two sets of notification for pse port and the 273 power supply. 275 5. POE Power Management module 277 file "ietf-poe-power-management@2017-03-07.yang" 278 module ietf-poe-power-management{ 279 namespace "urn:ietf:params:xml:ns:yang:ietf-poe-power-management"; 280 prefix poe-power; 282 import ietf-interfaces { 283 prefix if; 284 } 285 import ieee802-ethernet-interface { 286 prefix eth; 287 } 288 import ieee802-pse { 289 prefix pse; 290 } 291 /**Meta information**/ 292 organization 293 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 295 contact 296 "WG Web: < http://tools.ietf.org/wg/netmod/ > 297 WG List: 298 WG Chair: Lou Berger 299 300 WG Chair: Kent Watsen 301 303 Editor: Yan Zhuang 304 305 "; 307 description 308 "This module contains YANG defintions for configuring and 309 managing power system for Power Over Ethernet feature defined by 310 IEEE 802.3. It provdes functionality roughly equivalent to 311 that of the POWER-ETHERNET-MIB defined in RFC3621."; 313 revision 2017-03-09{ 314 description 315 "Initial version of power management for IEEE 802.3 PSE."; 316 reference 317 "draft-zhuang-netmod-yang-poe-management-00.txt"; 318 } 320 /*Identities and typedef*/ 321 typedef percentage { 322 type uint8 { 323 range "0..100"; 324 } 325 description "Percentage value in integer format."; 326 } 328 identity poe-port-event { 329 description "Poe port event notification base type."; 330 } 332 identity poe-power-module-event { 333 description "Poe power module event notification base type."; 334 } 336 identity power-usage-alarm { 337 base poe-power-module-event ; 338 description 339 "Base identity for power usage event"; 340 } 341 identity power-status-event { 342 base poe-port-event ; 343 description "Poe port power status change notification."; 344 } 346 identity pd-connection-status-event { 347 base poe-port-event ; 348 description "Poe port peer,the power device status change notification."; 349 } 351 identity power-absence-event { 352 base poe-port-event ; 353 description "Poe port power absence notification."; 354 } 355 identity pd-connection-status { 356 description 357 "Base identity for the PD connnection status"; 358 } 359 identity pd-connected { 360 base pd-connection-status; 361 description 362 "pd is connected"; 363 } 365 identity pd-disconnected { 366 base pd-connection-status; 367 description 368 "pd is disconnected"; 369 } 371 identity pd-class-invalid { 372 base pd-connection-status; 373 description "pd class is invalid"; 374 } 376 identity pd-class-over-current { 377 base pd-connection-status; 378 description "pd class is over current"; 379 } 381 typedef pse-detection-state { 382 type enumeration { 383 enum disabled { 384 value 1; 385 description "PSE disabled"; 386 } 387 enum searching { 388 value 2; 389 description "PSE is searching"; 390 } 391 enum deliveringPower { 392 value 3; 393 description "PSE is delivering power"; 394 } 395 enum fault { 396 value 4; 397 description "PSE fault detected"; 398 } 399 enum test { 400 value 5; 401 description "PSE test mode"; 402 } 403 enum otherFault { 404 value 6; 405 description "PSE implementation specific fault detected"; 406 } 407 } 408 description 409 "detection state of a multi-pair PSE"; 410 reference 411 "IEEE Std 802.3, 30.9.1.1.5"; 412 } 414 /************* PSE port management ******************/ 415 augment "/if:interfaces/if:interface/eth:ethernet/pse:poe-pse"{ 416 description "enable pse port notification"; 417 leaf event-notification-enable { 418 type boolean ; 419 default false ; 420 description "PSE port event notification switch."; 421 } 422 } 424 augment "/if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair"{ 425 description "configuration of pse port management"; 426 container poe-ports-config { 427 description "configuration for all poe ports."; 428 leaf power-priority { 429 type uint32; 430 description 431 "This object controls the priority of the port from the point 432 of view of a power management algorithm."; 434 } 435 leaf connected-pd-type { 436 type string; 437 description 438 "A manager will set the value of this variable to indicate 439 the type of powered device that is connected to the port. 440 The default value supplied by the agent if no value has 441 ever been set should be a zero-length octet string"; 442 } 443 } 444 } 445 augment "/if:interfaces-state/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair"{ 446 description "operational state for pse port"; 447 container poe-ports-state { 448 config false; 449 description "operational state for all poe ports."; 451 leaf power-priority { 452 type uint32; 453 description 454 "This object controls the priority of the port from the point 455 of view of a power management algorithm."; 456 } 457 leaf connected-pd-type { 458 type string; 459 description 460 "A manager will set the value of this variable to indicate 461 the type of powered device that is connected to the port. 462 The default value supplied by the agent if no value has 463 ever been set should be a zero-length octet string"; 464 } 465 } 466 } 468 /************** power source management ***************/ 469 /* Poe power module usage alarm configuration */ 470 container main-power-source-config { 472 list main-power-source-entry{ 473 key "slot-id"; 474 description "main power source entry"; 476 leaf slot-id { 477 type uint32; 478 description "Poe power module installed slot."; 479 } 480 leaf usage-threshold { 481 type percentage ; 482 description 483 "The usage threshold expressed in percents for 484 comparing the measured power and initiating an alarm 485 if the threshold is exceeded."; 487 } 488 } 489 description "Configurations of the main power source."; 490 } 492 /*main source operational state*/ 493 container main-power-sources-state { 494 config false; 496 description 497 "operational state for main power source"; 499 list main-power-source-entry { 500 key "slot-id"; 501 description "main power source entry"; 503 leaf slot-id { 504 type uint32; 505 description "Poe power module installed slot."; 506 } 508 container power-info { 509 description 510 "power information of the main power source"; 512 leaf total-power { 513 type decimal64 { 514 fraction-digits 4; 515 } 516 units 'watt'; 517 description 518 "The nominal power of the PSE expressed in Watts"; 519 } 521 leaf reserved-power { 522 type percentage ; 523 description 524 "The percent of power that the system reserved."; 525 } 527 leaf consuming-power { 528 type decimal64 { 529 fraction-digits 4; 530 } 531 units 'watt'; 532 description 533 "Measured usage power"; 534 } 536 leaf remained-power { 537 type decimal64 { 538 fraction-digits 4 ; 539 } 540 units 'watt'; 541 description 542 "total power * (1-reserved power)-consuming Power"; 543 } 545 leaf peak-power { 546 type decimal64 { 547 fraction-digits 4; 548 } 549 units 'watt'; 550 description 551 "the peak power"; 552 } 554 leaf usage-threshold { 555 type percentage ; 557 description 558 "The usage threshold expressed in percents for 559 comparing the measured power and initiating 560 an alarm if the threshold is exceeded."; 561 } 563 } 565 leaf operStatus { 566 type enumeration { 567 enum on { 568 value 1; 569 description "the main pse is on"; 570 } 571 enum off { 572 value 2; 573 description "the main pse is off"; 574 } 575 enum faulty { 576 value 3; 577 description "the main pse is faulty"; 578 } 579 } 581 default on; 582 description 583 "The operational status of the main PSE"; 584 } 585 } 586 } 588 /* 589 * Notifications 590 */ 592 /* 593 * Notifications 594 */ 595 notification poe-port-notification { 596 description "Port event notification when the notification switch is on."; 598 list event { 599 key "if-name event-type"; 600 description "list of events"; 601 leaf if-name { 602 type string ; 603 description "Poe port interface name"; 604 } 606 leaf event-type { 607 type identityref { 608 base poe-port-event ; 609 } 610 description "event type for poe port."; 611 } 613 container event-content { 614 description "Event notification content."; 616 leaf detection-status { 617 when " ../../event-type = 'pse:power-status-event' " ; 618 type pse-detection-state; 619 description "pse detection status"; 620 } 622 leaf pd-connection-events { 623 when " ../../event-type = 'pse:pd-connection-status-event'" ; 625 type identityref { 626 base pd-connection-status; 627 } 628 mandatory true; 629 description "pd connection events"; 630 } 631 } 632 } 633 } 634 notification poe-power-notification { 635 description "power event notification when the notification switch is on."; 637 list event { 638 key "slot-id event-type"; 639 description "list of power events."; 640 leaf slot-id { 641 type uint8 ; 642 description "Slot id of the power source"; 643 } 645 leaf event-type { 646 type identityref { 647 base poe-power-module-event ; 648 } 649 description "event type for main power source."; 650 } 652 container event-content { 653 description "Event notification content."; 655 container power-usage { 656 when " ../../event-type = 'poe-power:power-usage-alarm' " ; 657 description "poe usage event content."; 659 leaf consuming-power { 660 type uint32; 661 mandatory true; 662 description "consuming power"; 663 } 665 leaf usage-threshold { 666 type uint32; 667 description "usage threshold"; 668 } 669 } 670 } 672 } 673 } 674 } 675 677 6. Security Consideration 679 TBD 681 7. Acknowledgements 683 8. Normative References 685 [IEEE-802.3.2] 686 IEEE 802.3 Working Group, "IEEE P802.3.2 - YANG Data Model 687 Definitions (ongoing)". 689 [IEEE-802.3af] 690 IEEE 802.3 Working Group, "IEEE Std 802.3af-2003 - Data 691 Terminal Equipment (DTE) Power via Media Dependent 692 Interface (MDI)", 2003. 694 [IEEE-802.3at] 695 IEEE 802.3 Working Group, "IEEE Std 802.3at-2009-DTE Power 696 Enhancements", 2009. 698 [IEEE-802.3bt] 699 IEEE 802.3 Working Group, "DTE Power via MDI over 4-Pair 700 (ongoing)". 702 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 703 Requirement Levels", BCP 14, RFC 2119, 704 DOI 10.17487/RFC2119, March 1997, 705 . 707 [RFC3621] Berger, A. and D. Romascanu, "Power Ethernet MIB", 708 December 2003. 710 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 711 RFC 7950, DOI 10.17487/RFC7950, Augest 2016, 712 . 714 Appendix A. Related modules 716 Related moduels can be found at 717 https://github.com/YangModels/yang/tree/master/standard/ieee/802.3/ 718 draft. 720 Author's Address 722 Yan Zhuang 723 Huawei 724 101 Software Avenue, Yuhua District 725 Nanjing, Jiangsu 210012 726 China 728 Email: zhuangyan.zhuang@huawei.com