Internet DRAFT - draft-zhuang-netmod-yang-poe-management

draft-zhuang-netmod-yang-poe-management







NETMOD Working Group                                           Y. Zhuang
Internet-Draft                                                    Huawei
Intended status: Standards Track                           July 26, 2017
Expires: January 27, 2018


      A YANG Data Model for Power over Ethernet System management
               draft-zhuang-netmod-yang-poe-management-02

Abstract

   This memo defines a YANG data model for Power over Ethernet System
   for use with network management protocols.  This document augments
   the IEEE 802.3 PSE module with attributes to manage PSE port and
   provide notification of powering states.  Besides, it also provides
   power source management for the whole system.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 27, 2018.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.



Zhuang                  Expires January 27, 2018                [Page 1]

Internet-Draft             YANG POE management                 July 2017


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Definitions an Acronyms . . . . . . . . . . . . . . . . . . .   2
     2.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   2
     2.2.  Tree diagram  . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Design of the data model  . . . . . . . . . . . . . . . . . .   4
     4.1.  Main Power Source management  . . . . . . . . . . . . . .   5
     4.2.  PSE port management . . . . . . . . . . . . . . . . . . .   6
     4.3.  Notification  . . . . . . . . . . . . . . . . . . . . . .   7
   5.  POE Power Management module . . . . . . . . . . . . . . . . .   7
   6.  Security Consideration  . . . . . . . . . . . . . . . . . . .  16
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  16
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  16
   Appendix A.  Related modules  . . . . . . . . . . . . . . . . . .  16
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  17

1.  Introduction

   This document defines a YANG [RFC7950] data model for the management
   of power over Ethernet [IEEE 802.3at] Power Sourcing Equipment (PSE).

2.  Definitions an Acronyms

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.1.  Terminology

   The following abbreviations are defined in [IEEE-802.3at] and will be
   used with the same significance in this document:

   PSE - Power Sourcing Equipment;

   PD - Powered Device

2.2.  Tree diagram

   The following notations are used within the data tree and carry the
   meaning as below.









Zhuang                  Expires January 27, 2018                [Page 2]

Internet-Draft             YANG POE management                 July 2017


  Each node is printed as:
    <status> <flags> <name> <opts> <type>

    <status> is one of:
         +  for current
         x  for deprecated
         o  for obsolete
    <flags> is one of:
        rw for configuration data
        ro for non-configuration data
        -x for rpcs
        -n for notifications
    <name> is the name of the node

    If the node is augmented into the tree from another module, its name
    is printed as <prefix>:<name>.
    <opts> is one of:
         ?  for an optional leaf or choice
         !  for a presence container
         *  for a leaf-list or list
         [<keys>] for a list's keys
    <type> is the name of the type for leafs and leaf-lists

   In this document, these words will appear with that interpretation
   only when in ALL CAPS.  Lower case uses of these words are not to be
   interpreted as carrying RFC-2119 significance.

3.  Overview

   Power over Ethernet (PoE) provides a way to allows devices receiving
   power over the same cable used for data transmission.  It also
   enables applications of powered devices connected to the network and
   managed by a remote management application.  The IEEE 802.3 Working
   Group has finished two standardization projects on this subject,
   known as IEEE 802.3af and IEEE 802.3at.

   With the increase of required power level in nowadays, the Working
   Group is now working on the 4-pair PoE which provides up to 90 watts
   powering known as IEEE 802.3bt [IEEE 802.3bt] to enable more
   applications such as lighting over Ethernet for intelligent lighting
   system.

   The IEEE 802.3 WG is currently also working on a YANG data model for
   the management of Power Source Equipment in [IEEE P802.3.2], however,
   it did not define a full management interface, but only the managed
   objects based on the hardware registers.  The module defined in this
   document is an extension to that module to provide management
   required for the poe system and ports as defined in Power Ethernet



Zhuang                  Expires January 27, 2018                [Page 3]

Internet-Draft             YANG POE management                 July 2017


   MIB[RFC3621], so as to be used by the system administrator for
   management.

4.  Design of the data model

   This document defines the YANG module "ietf-poe-power-management",
   which has two parts: main power source management and pse port
   management.  Besides, the module also defines several notifications
   for the port and power source.  The model structure is as follows:










































Zhuang                  Expires January 27, 2018                [Page 4]

Internet-Draft             YANG POE management                 July 2017


module: ietf-poe-power-management
    +--rw main-power-source-config
    |  +--rw main-power-source-entry* [slot-id]
    |     +--rw slot-id            uint32
    |     +--rw usage-threshold?   percentage
    +--ro main-power-sources-state
       +--ro main-power-source-entry* [slot-id]
          +--ro slot-id       uint32
          +--ro power-info
          |  +--ro total-power?       decimal64
          |  +--ro reserved-power?    percentage
          |  +--ro consuming-power?   decimal64
          |  +--ro remained-power?    decimal64
          |  +--ro peak-power?        decimal64
          |  +--ro usage-threshold?   percentage
          +--ro operStatus?   enumeration
  augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse:
    +--rw event-notification-enable?   boolean
  augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair:
    +--rw poe-ports-config
       +--rw power-priority?      uint32
        +--rw connected-pd-type?   string
notifications:
    +---n poe-port-notification
    |  +--ro event* [if-name event-type]
    |     +--ro if-name          string
    |     +--ro event-type       identityref
    |     +--ro event-content
    |        +--ro detection-status?       pse-detection-state
    |        +--ro pd-connection-events    identityref
    +---n poe-power-notification
       +--ro event* [slot-id event-type]
          +--ro slot-id          uint8
          +--ro event-type       identityref
          +--ro event-content
             +--ro power-usage
                +--ro consuming-power    uint32
                +--ro usage-threshold?   uint32


4.1.  Main Power Source management

   As defined Power Etherent MIB[RFC3621], the main power source
   container defines the management attributes for a managed main power
   source in a PSE device.  Ethernet switches are one example of boxes
   that would support these objects.





Zhuang                  Expires January 27, 2018                [Page 5]

Internet-Draft             YANG POE management                 July 2017


                   module: poe-power-management
       +--rw main-power-source-config
       |  +--rw main-power-source-entry* [slot-id]
       |     +--rw slot-id            uint32
       |     +--rw usage-threshold?   percentage
       +--ro main-power-sources-state
          +--ro main-power-source-entry* [slot-id]
             +--ro slot-id       uint32
             +--ro power-info
             |  +--ro total-power?       decimal64
             |  +--ro reserved-power?    percentage
             |  +--ro consuming-power?   decimal64
             |  +--ro remained-power?    decimal64
             |  +--ro peak-power?        decimal64
             |  +--ro usage-threshold?   percentage
             +--ro operStatus?   enumeration


   Container "poe-power-management" contains a list of main power source
   entry in both configuration and operational state.  In configuration,
   the entry contains a slot-id node to indicate its belonged chassis
   id.  It also provides a usage-threhold to express in percents for
   comparing the measured power and initiating an alarm if the threshold
   is exceeded.

   For the operational state, the main power source entry provides power
   information for the management, including the total power, reserved
   power, consuming power, remained power, peak power etc al.  It also
   provide "operStauts" node to indicate current operational status of
   the main PSE whether it is on/off/faulty.

4.2.  PSE port management

   The pse port management augments the YANG module "ieee802-pse.yang"
   with extra management objects defined in Power Ethernet MIB [RFC3621]
   for required management of the pse ports.

                augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse:
    +--rw event-notification-enable?   boolean
                augment /if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair:
    +--rw poe-ports-config
       +--rw power-priority?      uint32
       +--rw connected-pd-type?   String

   Under the poe-pse container in ieee802-pse module, this document
   defines a data node to control the notification of event.  Besides,
   for the multiple pair PSE, it defines power priority as
   pethPsePortPowerPrority object defined in PoE MIB to control the



Zhuang                  Expires January 27, 2018                [Page 6]

Internet-Draft             YANG POE management                 July 2017


   priority of the port from the point of view of a power management
   system.  The node "connected-pd-type" is the same as the
   pethPsePortType object in PoE MIB for a managr to indicate the type
   of the powered device that is connected to the port.

4.3.  Notification

   Consist with notifications defined in Power Etherent MIB [RFC3621],
   this document also provides notifications for pse ports and power
   source to be transmitted from the agent to a management application.

                   notifications:
       +---n poe-port-notification
       |  +--ro event* [if-name event-type]
       |     +--ro if-name          string
       |     +--ro event-type       identityref
       |     +--ro event-content
       |        +--ro detection-status?       pse-detection-state
       |        +--ro pd-connection-events    identityref
       +---n poe-power-notification
          +--ro event* [slot-id event-type]
             +--ro slot-id          uint8
             +--ro event-type       identityref
             +--ro event-content
                +--ro power-usage
                   +--ro consuming-power    uint32
                   +--ro usage-threshold?   uint32

   This module defines two sets of notification for pse port and the
   power supply.

5.  POE Power Management module

        <CODE BEGINS> file "ietf-poe-power-management@2017-03-07.yang"
module ietf-poe-power-management{
        namespace "urn:ietf:params:xml:ns:yang:ietf-poe-power-management";
    prefix poe-power;

        import ietf-interfaces {
                prefix if;
        }
        import ieee802-ethernet-interface {
        prefix eth;
    }
        import ieee802-pse {
                prefix pse;
        }




Zhuang                  Expires January 27, 2018                [Page 7]

Internet-Draft             YANG POE management                 July 2017


        /**Meta information**/
    organization
    "IETF NETMOD (NETCONF Data Modeling Language) Working Group";


    contact
     "WG Web:   < http://tools.ietf.org/wg/netmod/ >
        WG List:  <mailto:netmod@ietf.org >
        WG Chair: Lou Berger
                  <mailto:lberger@labn.net >
        WG Chair: Kent Watsen
                  <mailto:kwatsen@juniper.net >

                Editor: Yan Zhuang
                                <mailto:zhuangyan.zhuang@huawei.com.com >
         ";


  description
    "This module contains YANG defintions for configuring and
     managing power system for Power Over Ethernet feature defined by
     IEEE 802.3. It provdes functionality roughly equivalent to
     that of the POWER-ETHERNET-MIB defined in RFC3621.";

  revision 2017-03-09{
        description
        "Initial version of power management for IEEE 802.3 PSE.";
        reference
        "draft-zhuang-netmod-yang-poe-management-00.txt";
  }

  /*Identities and typedef*/
  typedef percentage {
    type uint8 {
      range "0..100";
    }
        description "Percentage value in integer format.";
  }

  identity poe-port-event {
    description "Poe port event notification base type.";
  }

  identity poe-power-module-event {
        description "Poe power module event notification base type.";
  }

  identity power-usage-alarm {



Zhuang                  Expires January 27, 2018                [Page 8]

Internet-Draft             YANG POE management                 July 2017


        base poe-power-module-event ;
        description
        "Base identity for power usage event";
  }
  identity power-status-event {
    base poe-port-event ;
        description "Poe port power status change notification.";
  }

  identity pd-connection-status-event {
    base poe-port-event ;
        description "Poe port peer,the power device status change notification.";
  }

  identity power-absence-event {
    base poe-port-event ;
    description "Poe port power absence notification.";
  }
  identity pd-connection-status {
    description
      "Base identity for the PD connnection status";
  }
    identity pd-connected {
    base pd-connection-status;
    description
      "pd is connected";
  }

  identity pd-disconnected {
    base pd-connection-status;
    description
      "pd is disconnected";
  }

  identity pd-class-invalid {
    base pd-connection-status;
    description "pd class is invalid";
  }

  identity pd-class-over-current {
    base pd-connection-status;
    description "pd class is over current";
  }

  typedef pse-detection-state {
    type enumeration {
      enum disabled {
        value 1;



Zhuang                  Expires January 27, 2018                [Page 9]

Internet-Draft             YANG POE management                 July 2017


        description "PSE disabled";
      }
      enum searching {
        value 2;
        description "PSE is searching";
      }
      enum deliveringPower {
        value 3;
        description "PSE is delivering power";
      }
      enum fault {
        value 4;
        description "PSE fault detected";
      }
      enum test {
        value 5;
        description "PSE test mode";
      }
      enum otherFault {
        value 6;
        description "PSE implementation specific fault detected";
      }
    }
        description
     "detection state of a multi-pair PSE";
    reference
     "IEEE Std 802.3, 30.9.1.1.5";
  }

  /************* PSE port management ******************/
  augment "/if:interfaces/if:interface/eth:ethernet/pse:poe-pse"{
        description "enable pse port notification";
        leaf event-notification-enable {
          type boolean ;
          default false ;
                  description "PSE port event notification switch.";
        }
  }

  augment "/if:interfaces/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair"{
  description "configuration of pse port management";
        container poe-ports-config {
                description "configuration for all poe ports.";
          leaf power-priority {
          type uint32;
          description
             "This object controls the priority of the port from the point
            of view of a power management algorithm.";



Zhuang                  Expires January 27, 2018               [Page 10]

Internet-Draft             YANG POE management                 July 2017


        }
                leaf connected-pd-type {
          type string;
          description
            "A manager will set the value of this variable to indicate
            the type of powered device that is connected to the port.
            The default value supplied by the agent if no value has
            ever been set should be a zero-length octet string";
        }
        }
  }
  augment "/if:interfaces-state/if:interface/eth:ethernet/pse:poe-pse/pse:multi-pair"{
  description "operational state for pse port";
  container poe-ports-state {
                config false;
                description "operational state for all poe ports.";

                leaf power-priority {
          type uint32;
          description
             "This object controls the priority of the port from the point
            of view of a power management algorithm.";
        }
                leaf connected-pd-type {
          type string;
          description
            "A manager will set the value of this variable to indicate
            the type of powered device that is connected to the port.
            The default value supplied by the agent if no value has
            ever been set should be a zero-length octet string";
        }
        }
  }


  /************** power source management ***************/
  /* Poe power module usage alarm configuration */
  container main-power-source-config {

   list main-power-source-entry{
                key "slot-id";
                description "main power source entry";

                leaf slot-id {
                        type uint32;
                        description "Poe power module installed slot.";
                }
                leaf usage-threshold {



Zhuang                  Expires January 27, 2018               [Page 11]

Internet-Draft             YANG POE management                 July 2017


                        type percentage ;
          description
          "The usage threshold expressed in percents for
           comparing the measured power and initiating an alarm
           if the threshold is exceeded.";

        }
        }
        description "Configurations of the main power source.";
  }

  /*main source operational state*/
  container main-power-sources-state {
    config false;

    description
      "operational state for main power source";

    list main-power-source-entry {
      key "slot-id";
      description "main power source entry";

      leaf slot-id {
                type uint32;
        description "Poe power module installed slot.";
      }

      container power-info {
        description
          "power information of the main power source";

        leaf total-power {
          type decimal64 {
            fraction-digits 4;
          }
          units 'watt';
          description
            "The nominal power of the PSE expressed in Watts";
        }

        leaf reserved-power {
          type percentage ;
          description
            "The percent of power that the system reserved.";
        }

        leaf consuming-power {
          type decimal64 {



Zhuang                  Expires January 27, 2018               [Page 12]

Internet-Draft             YANG POE management                 July 2017


            fraction-digits 4;
          }
          units 'watt';
          description
            "Measured usage power";
        }

        leaf remained-power {
          type decimal64 {
            fraction-digits 4 ;
          }
          units 'watt';
          description
            "total power * (1-reserved power)-consuming Power";
        }

        leaf peak-power {
          type decimal64 {
            fraction-digits 4;
          }
          units 'watt';
          description
            "the peak power";
        }

        leaf usage-threshold {
          type percentage ;

          description
            "The usage threshold expressed in percents for
             comparing the measured power and initiating
             an alarm if the threshold is exceeded.";
        }

      }


      leaf operStatus {
        type enumeration {
          enum on {
            value 1;
            description "the main pse is on";
          }
          enum off {
            value 2;
            description "the main pse is off";
          }
          enum faulty {



Zhuang                  Expires January 27, 2018               [Page 13]

Internet-Draft             YANG POE management                 July 2017


            value 3;
            description "the main pse is faulty";
          }
        }

        default on;
        description
          "The operational status of the main PSE";
      }
    }
  }


   /*
   * Notifications
   */

      /*
   * Notifications
   */
  notification poe-port-notification {
    description "Port event notification when the notification switch is on.";

      list event {
      key "if-name event-type";
      description "list of events";
      leaf if-name {
                type string ;
        description "Poe port interface name";
      }

      leaf event-type {
        type identityref {
          base poe-port-event ;
        }
                description "event type for poe port.";
      }

      container event-content {
        description "Event notification content.";

        leaf detection-status {
          when " ../../event-type = 'pse:power-status-event' " ;
          type pse-detection-state;
          description "pse detection status";
        }

        leaf pd-connection-events {



Zhuang                  Expires January 27, 2018               [Page 14]

Internet-Draft             YANG POE management                 July 2017


          when " ../../event-type = 'pse:pd-connection-status-event'" ;

          type identityref {
            base pd-connection-status;
          }
                  mandatory true;
                  description "pd connection events";
        }
      }
    }
  }
  notification poe-power-notification {
    description "power event notification when the notification switch is on.";

      list event {
      key "slot-id event-type";
      description "list of power events.";
      leaf slot-id {
        type uint8 ;
                description "Slot id of the power source";
      }

      leaf event-type {
        type identityref {
          base poe-power-module-event ;
        }
                description "event type for main power source.";
      }

      container event-content {
        description "Event notification content.";

        container power-usage {
          when " ../../event-type = 'poe-power:power-usage-alarm' " ;
          description "poe usage event content.";

          leaf consuming-power {
            type uint32;
                        mandatory true;
            description "consuming power";
          }

          leaf usage-threshold {
            type uint32;
            description "usage threshold";
          }
        }
      }



Zhuang                  Expires January 27, 2018               [Page 15]

Internet-Draft             YANG POE management                 July 2017


    }
  }
}
    <CODE ENDS>

6.  Security Consideration

   TBD

7.  Acknowledgements

8.  Normative References

   [IEEE-802.3.2]
              IEEE 802.3 Working Group, "IEEE P802.3.2 - YANG Data Model
              Definitions (ongoing)".

   [IEEE-802.3af]
              IEEE 802.3 Working Group, "IEEE Std 802.3af-2003 - Data
              Terminal Equipment (DTE) Power via Media Dependent
              Interface (MDI)", 2003.

   [IEEE-802.3at]
              IEEE 802.3 Working Group, "IEEE Std 802.3at-2009-DTE Power
              Enhancements", 2009.

   [IEEE-802.3bt]
              IEEE 802.3 Working Group, "DTE Power via MDI over 4-Pair
              (ongoing)".

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC3621]  Berger, A. and D. Romascanu, "Power Ethernet MIB",
              December 2003.

   [RFC7950]  Bjorklund, M., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, Augest 2016,
              <http://www.rfc-editor.org/info/rfc7950>.

Appendix A.  Related modules

   Related moduels can be found at
   https://github.com/YangModels/yang/tree/master/standard/ieee/802.3/
   draft.




Zhuang                  Expires January 27, 2018               [Page 16]

Internet-Draft             YANG POE management                 July 2017


Author's Address

   Yan Zhuang
   Huawei
   101 Software Avenue, Yuhua District
   Nanjing, Jiangsu  210012
   China

   Email: zhuangyan.zhuang@huawei.com










































Zhuang                  Expires January 27, 2018               [Page 17]