[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-chisholm-netconf-monitoring) 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 RFC 6022

Network Working Group                                           M. Scott
Internet-Draft                                                  Ericsson
Intended status: Standards Track                            M. Bjorklund
Expires: June 3, 2010                                     Tail-f Systems
                                                       November 30, 2009


                   YANG Module for NETCONF Monitoring
                    draft-ietf-netconf-monitoring-10

Status of this Memo

   This Internet-Draft is submitted to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.  This document may contain material
   from IETF Documents or IETF Contributions published or made publicly
   available before November 10, 2008.  The person(s) controlling the
   copyright in some of this material may not have granted the IETF
   Trust the right to allow modifications of such material outside the
   IETF Standards Process.  Without obtaining an adequate license from
   the person(s) controlling the copyright in such materials, this
   document may not be modified outside the IETF Standards Process, and
   derivative works of it may not be created outside the IETF Standards
   Process, except to format it for publication as an RFC or to
   translate it into languages other than English.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

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

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on June 3, 2010.

Copyright Notice

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




Scott & Bjorklund         Expires June 3, 2010                  [Page 1]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.














































Scott & Bjorklund         Expires June 3, 2010                  [Page 2]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


Abstract

   This document defines a NETCONF data model to be used to monitor the
   NETCONF protocol.  The monitoring data model includes information
   about NETCONF datastores, sessions, locks and statistics.  This data
   facilitates the management of a NETCONF server.  This document also
   defines methods for NETCONF clients to discover data models supported
   by a NETCONF server and defines a new NETCONF <get-schema> operation
   to retrieve them.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.1.  Definition of Terms  . . . . . . . . . . . . . . . . . . .  4
   2.  Data Model to Monitor NETCONF  . . . . . . . . . . . . . . . .  5
     2.1.  The /netconf-state Subtree . . . . . . . . . . . . . . . .  5
       2.1.1.  The /netconf-state/capabilities Subtree  . . . . . . .  6
       2.1.2.  The /netconf-state/datastores Subtree  . . . . . . . .  6
       2.1.3.  The /netconf-state/schemas Subtree . . . . . . . . . .  6
       2.1.4.  The /netconf-state/sessions Subtree  . . . . . . . . .  7
       2.1.5.  The /netconf-state/statistics Subtree  . . . . . . . .  8
   3.  Schema Specific Operations . . . . . . . . . . . . . . . . . . 10
     3.1.  The <get-schema> Operation . . . . . . . . . . . . . . . . 10
   4.  Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     4.1.  Retrieving Schema List via <get> Operation . . . . . . . . 11
     4.2.  Retrieving Schema Instances  . . . . . . . . . . . . . . . 13
   5.  NETCONF Monitoring Schema  . . . . . . . . . . . . . . . . . . 15
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 27
   7.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 29
   9.  Appendix A - Change Log  . . . . . . . . . . . . . . . . . . . 30
     9.1.  draft-ietf-netconf-monitoring-10 . . . . . . . . . . . . . 30
     9.2.  draft-ietf-netconf-monitoring-09 . . . . . . . . . . . . . 30
     9.3.  draft-ietf-netconf-monitoring-08 . . . . . . . . . . . . . 31
     9.4.  draft-ietf-netconf-monitoring-07 . . . . . . . . . . . . . 31
     9.5.  draft-ietf-netconf-monitoring-06 . . . . . . . . . . . . . 31
     9.6.  draft-ietf-netconf-monitoring-05 . . . . . . . . . . . . . 32
     9.7.  draft-ietf-netconf-monitoring-04 . . . . . . . . . . . . . 32
     9.8.  draft-ietf-netconf-monitoring-03 . . . . . . . . . . . . . 33
     9.9.  draft-ietf-netconf-monitoring-02 . . . . . . . . . . . . . 33
     9.10. draft-ietf-netconf-monitoring-01 . . . . . . . . . . . . . 33
     9.11. draft-scott-netconf-monitoring-00  . . . . . . . . . . . . 33
   10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34
     10.1. Normative References . . . . . . . . . . . . . . . . . . . 34
     10.2. Informative References . . . . . . . . . . . . . . . . . . 35
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36




Scott & Bjorklund         Expires June 3, 2010                  [Page 3]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


1.  Introduction

   This document defines a [YANG] model to be used to monitor the
   NETCONF protocol.  It provides information about NETCONF sessions and
   supported schema.

   Considerations such as different schema formats, feature optionality
   and access controls can all impact the applicability and level of
   detail the NETCONF server sends to a client during session setup.
   The methods defined in this document address the need for further
   means to query and retrieve schema and NETCONF state information from
   a NETCONF server.  These are provided to complement existing base
   NETCONF capabilities and operations and in no way affect existing
   behaviour.

   A new <get-schema> operation is also defined to support explicit
   schema retrieval via NETCONF.

1.1.  Definition of Terms

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

   Schema:  A machine readable data model definition.

























Scott & Bjorklund         Expires June 3, 2010                  [Page 4]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


2.  Data Model to Monitor NETCONF

   The NETCONF monitoring data defined in this document provides
   operational information on the NETCONF server.  This includes details
   specific to the NETCONF protocol (e.g. protocol specific counters
   such as 'in-sessions') as well as data related to schema retrieval
   (e.g. schema list).  A server that implements the data model defined
   in this document MUST advertise the capability URI
   "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring".  An overview
   of the specific monitoring data defined in this document which MUST
   be present follows.  For detailed descriptions refer to the normative
   YANG module provided in this document (see section 5)..

2.1.  The /netconf-state Subtree


  The /netconf-state subtree is the root of the monitoring
  data model.  It acts as the container for the other monitored data.

    netconf-state
     /capabilities
     /datastores
     /schemas
     /sessions
     /statistics

  capabilities
    List of NETCONF capabilities supported by the server.

  datastores
    List of NETCONF datastores on the server.
    Includes all supported datastore types (running, candidate, startup)

  schemas
    List of schemas supported on the server.
    Includes all the information required to identify the schemas and
    to support their retrieval.

  sessions
    List of all active NETCONF sessions on the device.
    Includes per session counters for all NETCONF sessions.

  statistics (Container)
    Includes global counters for the NETCONF server.







Scott & Bjorklund         Expires June 3, 2010                  [Page 5]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


2.1.1.  The /netconf-state/capabilities Subtree

   The /netconf-state/capabilities subtree contains the capabilities
   supported by the NETCONF server.  The list MUST include all
   capabilities exchanged during session setup still applicable at the
   time of the request.

2.1.2.  The /netconf-state/datastores Subtree


  The /netconf-state/datastores subtree contains the list of
  available datastores for the NETCONF server and includes
  information on their lock state.

configuration
     /name
     /locks

name (container, netconf-datastore-type)
   Enumeration of supported datastores; candidate, running, startup.

locks (grouping, lock-info)
   List of locks for the datastore.  Information is provided for both
   global and partial locks.  For partial locks the list of locked nodes
   and the select expressions originally used to request the
   lock are returned.

2.1.3.  The /netconf-state/schemas Subtree























Scott & Bjorklund         Expires June 3, 2010                  [Page 6]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  The list of supported schema for the NETCONF server.

  schema
      /identifier   (key)
      /version      (key)
      /format       (key)
      /namespace
      /location

  The elements identifier, version, and format are used as a key in the
  schema list.  These are used in the <get-schema> operation.

  identifier (string)
    Identifier for the schema list entry.
    Identifier is used in the <get-schema> operation and may
    be used for other means such as file retrieval.

  version (string)
    Version of the schema supported.  Multiple versions MAY be supported
    simultaneously by a NETCONF server.

  format (identifyref, schema-format)
    The data modeling language of the file/module.  Current selection of
    xsd, yang, yin, rng and rnc.

  namespace(inet:uri)
    The XML namespace defined by the data model.

  location (union: enum, inet:uri)
    One of more locations from which this specific schema can be
    retrieved.  The list SHOULD contain at least one entry per schema.


2.1.4.  The /netconf-state/sessions Subtree


   Includes session specific data for NETCONF management sessions.
   The session list MUST include all currently active NETCONF sessions.

   sessions:

   session
          /session-id (key)
          /transport
          /username
          /source-host
          /login-time
          /in-rpcs



Scott & Bjorklund         Expires June 3, 2010                  [Page 7]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


          /in-bad-rpcs
          /out-rpc-errors
          /out-notifications

   session-id (session-id)
     Unique identifier for the session.
     This value is the NETCONF session identifier, as defined
     in [NETCONF Configuration Protocol].

   transport (identityref, transport)
     Identifies transport for each session, e.g. "netconf-ssh",
     "netconf-soap", etc.

   username (string)
     If present, the username contains an identifier which can be
     used to uniquely identify an individual client (human or
     machine).

   source-host (inet:host)
     Host identifier (IP address or name) of the client.

   login-time (yang:date-and-time)
     Time at which the session was established.

   in-rpcs (yang:zero-based-counter32)
     Number of correct <rpc> requests received.

   in-bad-rpcs (yang:zero-based-counter32)
     Number of messages received when a <rpc> message was expected,
     that were not correct <rpc> messages.  This includes XML parse
     errors and errors on the rpc layer.

   out-rpc-errors (yang:zero-based-counter32)
     Number of <rpc-reply> messages sent which contained an <rpc-error>
     element.

   out-notifications (yang:zero-based-counter32)
     Number of <notification> messages sent.

2.1.5.  The /netconf-state/statistics Subtree











Scott & Bjorklund         Expires June 3, 2010                  [Page 8]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  Statistical data pertaining to the NETCONF server.

  statistics
     /netconf-start-time
     /in-bad-hellos
     /in-sessions
     /dropped-sessions
     /in-rpcs
     /in-bad-rpcs
     /out-rpc-errors
     /out-notifications

  statistics:
    Contains management session related performance data for the NETCONF
    server.

  netconf-start-time (yang:date-and-time)
    Date and time at which the management subsystem was started.

  in-bad-hellos (yang:zero-based-counter32)
    Number of sessions silently dropped because an
    invalid <hello> message was received.

  in-sessions (yang:zero-based-counter32)
    Number of sessions started.

  dropped-sessions (yang:zero-based-counter32)
    Number of sessions that were abnormally terminated, e.g. due
    to idle timeout or transport close.

  in-rpcs (yang:zero-based-counter32)
    Number of correct <rpc> requests received.

  in-bad-rpcs (yang:zero-based-counter32)
    Number of messages received when a <rpc> message was expected,
    that were not correct <rpc> messages.

  out-rpc-errors (yang:zero-based-counter32)
    Number of <rpc-reply> messages sent which contained an <rpc-error>
    element.

  out-notifications (yang:zero-based-counter32)
    Number of <notification> messages sent.








Scott & Bjorklund         Expires June 3, 2010                  [Page 9]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


3.  Schema Specific Operations

3.1.  The <get-schema> Operation


   Description:

   This operation is used to retrieve a schema from the NETCONF server.

   Parameters:

     identifier (string):
       Identifier for the schema list entry.
       Mandatory parameter.

     version (string):
       Version of the schema requested.
       Optional parameter.

     format (identityref, schema-format):
       The data modeling language of the schema.
       Default value is 'yang' when not specified.
       Optional parameter.

   Positive Response:

     The NETCONF server returns the requested schema.

   Negative Response:

     If requested schema does not exist, the <error-tag> is
     'invalid-value'.

     If requested schema is not unique, the <error-tag> is
     'operation-failed', and <error-app-tag> is 'data-not-unique'.
















Scott & Bjorklund         Expires June 3, 2010                 [Page 10]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


4.  Examples

4.1.  Retrieving Schema List via <get> Operation


A NETCONF client retrieves the list of supported schema from
a NETCONF server by retrieving the /netconf-state/schemas
subtree via a <get> operation.

Available schema for the requesting session are returned in the
reply containing the <identifier>,<version>, <format>,
and <location> elements.

Since the same schema may be available in multiple locations
and/or have multiple versions and/or multiple formats no
particular attribute is unique.

The response data can be used to determine the available schema
and their versions.  The schema itself (i.e. schema content) is
not returned in the response.  The URL details returned in the
list SHOULD facilitate retrieval from a network location via a
means such as ftp or http.

Additionally the ability to retrieve a schema via NETCONF SHOULD be
supported.  When a schema is available on the device and the
<get-schema> operation is supported by the NETCONF server a
location value of 'NETCONF' MUST be used to indicate that it can be
retrieved via NETCONF using the <get-schema> operation described
in section 3.1.

Example:

<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get>
    <filter type="subtree">
      <netconf-state xmlns=
      "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
        <schemas/>
      </netconf-state>
    </filter>
  </get>
</rpc>


The NETCONF server returns a list of data models available for
retrieval.





Scott & Bjorklund         Expires June 3, 2010                 [Page 11]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


<rpc-reply message-id="101"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data>
    <netconf-state
    xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
      <schemas>
        <schema>
          <identifier>foo</identifier>
          <version>1.0</version>
          <format>xsd</format>
          <namespace>http://example.com/foo</namespace>
          <location>ftp://ftp.example.com/schemas/foo_1.0.xsd</location>
          <location>http://www.example.com/schema/foo_1.0.xsd</location>
          <location>NETCONF</location>
        </schema>
        <schema>
          <identifier>foo</identifier>
          <version>1.1</version>
          <format>xsd</format>
          <namespace>http://example.com/foo</namespace>
          <location>ftp://ftp.example.com/schemas/foo_1.1.xsd</location>
          <location>http://www.example.com/schema/foo_1.1.xsd</location>
          <location>NETCONF</location>
        </schema>
        <schema>
          <identifier>bar</identifier>
          <version>2008-06-01</version>
          <format>yang</format>
          <namespace>http://example.com/bar</namespace>
          <location>
            http://example.com/schema/bar-2008-06-01.yang
          </location>
          <location>NETCONF</location>
        </schema>
        <schema>
          <identifier>bar-types</identifier>
          <version>2008-06-01</version>
          <format>yang</format>
          <namespace>http://example.com/bar</namespace>
          <location>
            http://example.com/schema/bar-types-2008-06-01.yang
          </location>
          <location>NETCONF</location>
        </schema>
      </schemas>
    </netconf-state>
  </data>
</rpc-reply>



Scott & Bjorklund         Expires June 3, 2010                 [Page 12]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


4.2.  Retrieving Schema Instances

   Given the reply in the previous section, the following examples
   illustrate the retrieval of 'foo', 'bar', and 'bar-types' schema at
   multiple locations, with multiple formats, and in multiple locations.

     1.  foo,  version 1.0 in xsd format:

       a.  Via FTP using location
           ftp://ftp.example.com/schemas/foo_1.0.xsd

       b.  Via HTTP using location
           http://www.example.com/schema/foo_1.0.xsd

       c.  Via <get-schema> using identifier, version, and
       format parameters.


       <rpc message-id="101"
         xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
         <get-schema
         xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
           <identifier>foo</identifier>
           <version>1.0</version>
           <format>xsd</format>
         </get-schema>
       </rpc>

       <rpc-reply message-id="101"
         xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
         <data
         xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
           <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
             <!-- foo 1.0 xsd schema contents here -->
           </xs:schema>
         </data>
       </rpc-reply>

     2. bar, version 2008-06-01 in YANG format:

       a.  Via HTTP using location
           http://example.com/schema/bar-2008-06-01.yang

       b.  Via <get-schema> using identifer and version
           parameters:

         <rpc message-id="102"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">



Scott & Bjorklund         Expires June 3, 2010                 [Page 13]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


           <get-schema
           xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
             <identifer>bar</identifer>
             <version>2008-06-01</version>
           </get-schema>
         </rpc>

         <rpc-reply message-id="102"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
           <data
           xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
             module bar {
               //default format (yang) returned
               //bar version 2008-06-01 yang module
               //contents here ...
             }
           </data>
         </rpc-reply>


     3. bar-types, version 2008-06-01 in default YANG format:

       a. Via <get-schema> using identifer parameter:

       <rpc message-id="103"
         xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
         <get-schema
         xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
           <identifer>bar-types</identifer>
         </get-schema>
       </rpc>

       <rpc-reply message-id="103"
         xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
         <data
         xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
           module bar-types {
             //default format (yang) returned
             //latest revision returned
             //bar-types version 2008-06-01 yang module
             //contents here ...
           }
         </data>
       </rpc-reply>







Scott & Bjorklund         Expires June 3, 2010                 [Page 14]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


5.  NETCONF Monitoring Schema



The data model described in this memo is defined in the
following YANG module.

<CODE BEGINS>

module ietf-netconf-monitoring {

  namespace
  "urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring:DRAFT-10";
  prefix "ns";

  import ietf-yang-types { prefix yang; }
  import ietf-inet-types { prefix inet; }

  organization
    "IETF NETCONF (Network Configuration) Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/netconf/>
     WG List:  <mailto:netconf@ietf.org>

     WG Chair: Mehmet Ersue
               <mailto:mehmet.ersue@nsn.com>

     WG Chair: Bert Wijnen
               <mailto:bertietf@bwijnen.net>

     Editor:   Mark Scott
               <mailto:mark.scott@ericsson.com>";

  description
    "NETCONF Monitoring Module.
     All elements in this module are read-only.

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

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the Simplified BSD License
     set forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (http://trustee.ietf.org/license-info).




Scott & Bjorklund         Expires June 3, 2010                 [Page 15]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";
   // RFC Ed.: replace XXXX with actual RFC number and remove this note

  revision 2009-11-20 {
    description
      "Initial revision.";
    reference
      "RFC XXXX: NETCONF Monitoring Schema";
  // RFC Ed.: replace XXXX with actual RFC number and remove this note
  }

  // 'session-id-type' from 'ietf-netconf' module
  // can be replaced with import when 4741bis is published
  typedef session-id {
    type uint32 {
      range "1..max";
    }
    description
      "NETCONF Session Id.";
    reference
      "RFC 4741: NETCONF Configuration Protocol";
  }

  // to be added to base protocol 'ietf-netconf' module
  // and imported when 4741bis is published
  grouping netconf-datastore-type {
    description
      "Enumeration of possible NETCONF datastore types.";
    reference
      "RFC 4741: NETCONF Configuration Protocol";
    choice datastore {
      mandatory true;
      leaf running {
        type empty;
      }
      leaf candidate {
        type empty;
      }
      leaf startup {
        type empty;
      }
    }
  }

  identity transport {
    description
      "Base identity for NETCONF transport types.";



Scott & Bjorklund         Expires June 3, 2010                 [Page 16]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  }

  identity netconf-ssh {
    base transport;
    reference
      "RFC 4742: Using the NETCONF Configuration Protocol
                 over Secure SHell (SSH)";
  }

  identity netconf-soap-over-beep {
    base transport;
    reference
      "RFC 4743: Using NETCONF over the Simple Object
                 Access Protocol (SOAP)";
  }

  identity netconf-soap-over-https {
    base transport;
    reference
      "RFC 4743: Using NETCONF over the Simple Object
                 Access Protocol (SOAP)";
  }

  identity netconf-beep {
    base transport;
    reference
      "RFC 4744: Using the NETCONF Protocol over the
                 Blocks Extensible Exchange Protocol (BEEP)";
  }

  identity netconf-tls {
    base transport;
    reference
      "RFC 5539: NETCONF over Transport Layer Security (TLS)";
  }

  identity schema-format {
    description
      "Base identity for data model schema languages.";
  }

  identity xsd {
    base schema-format;
    reference
      "W3C REC REC-xmlschema-1-20041028: XML Schema Part 1: Structure
       W3C REC REC-xmlschema-2-20041028: XML Schema Part 2: Datatypes";
  }




Scott & Bjorklund         Expires June 3, 2010                 [Page 17]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  identity rng {
    base schema-format;
    reference
      "ISO/IEC 19757-2: RELAX NG";
  }

  identity yang {
    base schema-format;
    reference
      "RFC XXXX:  YANG - A data modeling language for NETCONF";
   // RFC Ed.: replace XXXX with actual RFC number and remove this note
  }

  identity yin {
    base schema-format;
    reference
      "RFC XXXX:  YANG - A data modeling language for NETCONF";
   // RFC Ed.: replace XXXX with actual RFC number and remove this note
  }

  identity rnc {
    base schema-format;
    reference
      "ISO/IEC 19757-2: RELAX NG";
  }

  grouping common-counters {
    description
      "Counters that exist both per session, and also globally,
       accumulated from all sessions.";

    leaf in-rpcs {
      type yang:zero-based-counter32;
      description
        "Number of correct <rpc> messages received.";
    }
    leaf in-bad-rpcs {
      type yang:zero-based-counter32;
      description
        "Number of messages received when a <rpc> message was expected,
         that were not correct <rpc> messages.  This includes XML parse
         errors and errors on the rpc layer.";
    }
    leaf out-rpc-errors {
      type yang:zero-based-counter32;
      description
        "Number of <rpc-reply> messages sent which contained an
         <rpc-error> element.";



Scott & Bjorklund         Expires June 3, 2010                 [Page 18]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


    }
    leaf out-notifications {
      type yang:zero-based-counter32;
      description
        "Number of <notification> messages sent.";
    }
  }

  container netconf-state {
    config false;
    description
      "The /netconf-state subtree is the root of the monitoring
       data model.  It acts as the container for the other
       monitored data.";

    container capabilities {
      description
        "The list of currently provided NETCONF capabilities
         exchanged during session setup (i.e. hello).";

      leaf-list capability {
        type inet:uri;
      }
    }

    container datastores {
      description
        "List of NETCONF configuration datastores (e.g. running,
         startup, candidate) supported on this device and related
         information.";

      list datastore {
        container name {
          uses netconf-datastore-type;
        }
        container locks {
          description
            "The NETCONF <lock> and <partial-lock> operations allow
             a client to lock specific resources in a datastore.  The
             NETCONF server will prevent changes to the locked
             resources by all sessions except the one which acquired
             the lock(s).

             Monitoring information is provided for each datastore
             entry including details such as the session which acquired
             the lock, the type of lock (global or partial) and the
             list of locked resources.  Multiple locks per datastore
             are supported.";



Scott & Bjorklund         Expires June 3, 2010                 [Page 19]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


          grouping lock-info {
            leaf locked-by-session {
              type session-id;
              description
                "The session ID of the session that has locked
                 this resource.  Both a global lock and a partial
                 lock MUST contain the NETCONF session-id.";
            }
            leaf locked-time {
              type yang:date-and-time;
              description
                "The date and time of when the resource was
                 locked.";
            }
          }

          choice lock-type {
            container global-lock {
              description
                "Present if the global lock is set.";

              uses lock-info;
            }

            list partial-locks {
              key lock-id;
              description
                "List of partial locks.";

              leaf lock-id {
                type uint32;
                description
                  "For a partial lock this is the lock id returned
                   in the <partial-lock> response.";
              }
              uses lock-info;
              leaf-list select {
                type string;
                min-elements 1;
                description
                  "The xpath expression which was used to request
                   the lock.  The select expression indicates the
                   original intended scope of the lock.";
              }
              leaf-list locked-nodes {
                type instance-identifier;
                description
                  "The list of instance-identifiers (i.e. the



Scott & Bjorklund         Expires June 3, 2010                 [Page 20]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


                   locked nodes).

                   The scope of the partial lock is defined by the list
                   of locked nodes.  This list can change over time.";
              }
            }
          }
        }
      }
    }

    container schemas {
      list schema {
        key "identifier version format";

        leaf identifier {
          type string;
          description
            "Identifier to uniquely reference the schema.  Identifier is
             used in the <get-schema> operation and may be used for
             other purposes such as file retrieval.

             For modeling languages which support or require a data
             model name (eg: YANG module name) the identifier MUST match
             that name.  For YANG data models, the identifier is the
             name of the module or submodule.  In other cases an
             identifier such as a filename MAY be used instead.";
        }
        leaf version {
          type string;
          description
            "Version of the schema supported.  Multiple versions MAY be
             supported simultaneously by a NETCONF server.  Each version
             MUST be reported individually in the schema list, i.e. with
             same identifier, possibly different location, but different
             version.

             For YANG data models, version is the value of the most
             recent YANG 'revision' statement in the module or
             submodule, or the empty string if no revision statement
             is present.";
        }
        leaf format {
          type identityref {
            base schema-format;
          }
          description
            "The data modeling language of the file/module.



Scott & Bjorklund         Expires June 3, 2010                 [Page 21]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


             Current selection of xsd, yang, yin, rng and rnc.

             For YANG data models, 'yang' format MUST be supported and
             'yin' format MAY also be provided.";
        }
        leaf namespace {
          type inet:uri;
          description
            "The XML namespace defined by the data model.

             For YANG data models, this is the module's namespace.
             If the list entry describes a submodule, this field
             contains the namespace of the module to which the
             submodule belongs.";
        }
        leaf-list location {
          type union {
            type enumeration {
              enum "NETCONF";
            }
            type inet:uri;
          }
          description
            "One or more locations from which the schema can be
             retrieved. This list SHOULD contain at least one
             entry per schema.

             A schema entry may be located on a remote file system
             (eg: reference to file system for ftp retrieval) or
             retrieved directly from a server supporting the
             <get-schema> operation (denoted by the value 'NETCONF').";
        }
      }
    }

    container sessions {
      description
        "Includes session specific data for NETCONF management sessions.
         The session list MUST include all currently active NETCONF
         sessions.";

      list session {
        key session-id;
        description
          "Unique identifier for the session.  If the session is a
           NETCONF session, this value is the NETCONF session
           identifier.




Scott & Bjorklund         Expires June 3, 2010                 [Page 22]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


           For purposes of NETCONF management all sessions are one of:

            Known session:  any session which can be managed by the
              NETCONF server SHOULD be reported in this table.

            Unknown session:  such sessions are not managed by the
              NETCONF server and map to NETCONF session identifier 0.
                 These MUST be excluded from the list as a result.";

        leaf session-id {
          type session-id;
        }
        leaf transport {
          type identityref {
            base transport;
          }
          mandatory true;
          description
            "Identifies the transport for each session, e.g.
            'netconf-ssh', 'netconf-soap', etc.";
        }
        leaf username  {
          type string;
          description
            "If present, the username contains an identifier which can
             be used to uniquely identify an individual client (human
             or machine).  This is likely to be implementation specific
             and subject to the security requirements of the device
             vendor and/or operators,  e.g., an SSH user, a host RSA
             fingerprint or other identifier deemed acceptable.";
        }
        leaf source-host {
          type inet:host;
          description
            "Host identifier (IP address or name) of the client.";
        }
        leaf login-time {
          type yang:date-and-time;
          mandatory true;
          description
            "Time at which the session was established.";
        }
        uses common-counters {
          description
            "Per-session counters.  Zero based with following reset
             behaviour:
               - at start of a session
               - when max value is reached";



Scott & Bjorklund         Expires June 3, 2010                 [Page 23]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


        }
      }
    }

    container statistics {

      leaf netconf-start-time {
        type yang:date-and-time;
        description
          "Date and time at which the management subsystem was
           started.";
      }
      leaf in-bad-hellos {
        type yang:zero-based-counter32;
        description
          "Number of sessions silently dropped because an
          invalid <hello> message was received.  This includes hello
          messages with a 'session-id' attribute, bad namespace, and
          bad capability declarations.";
      }
      leaf in-sessions {
        type yang:zero-based-counter32;
        description
          "Number of sessions started.  This counter is incremented
           when a <hello> message with a <session-id> is sent.

          'in-sessions' - 'in-bad-hellos' = 'number of correctly started
                                             netconf sessions'";
      }
      leaf dropped-sessions {
        type yang:zero-based-counter32;
        description
          "Number of sessions that were abnormally terminated, e.g. due
           to idle timeout or transport close.  This counter is not
           incremented when a session is properly closed by a
           <close-session> operation, or killed by a <kill-session>
           operation.";
      }
      uses common-counters {
        description
          "Global counters, accumulated from all sessions.
           Zero based with following reset behaviour:
             - re-initialization of NETCONF server
             - when max value is reached";
      }
    }
  }




Scott & Bjorklund         Expires June 3, 2010                 [Page 24]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  rpc get-schema {
    description
      "This operation is used to retrieve a schema from the
       NETCONF server.

       Positive Response:
         The NETCONF server returns the requested schema.

       Negative Response:
         If requested schema does not exist, the <error-tag> is
         'invalid-value'.

         If more than one schema matches the requested parameters, the
         <error-tag> is 'operation-failed', and <error-app-tag> is
         'data-not-unique'.";

    input {
      leaf identifier {
        type string;
        mandatory true;
        description
          "Identifier for the schema list entry.";
      }
      leaf version {
        type string;
        description
          "Version of the schema requested.  If this parameter is not
           present, and more than one version of the schema exists on
           the server, a 'data-not-unique' error is returned, as
           described above.";
      }
      leaf format {
        type identityref {
          base schema-format;
        }
        description
           "The data modeling language of the schema.  If this parameter
            is not present, and more than one formats of the schema
            exists on the server, a 'data-not-unique' error is returned,
            as described above.";
      }
    }
    output {
        anyxml data {
          description
            "Contains the schema content.";
      }
    }



Scott & Bjorklund         Expires June 3, 2010                 [Page 25]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  }
}

<CODE ENDS>















































Scott & Bjorklund         Expires June 3, 2010                 [Page 26]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


6.  Security Considerations

   The NETCONF monitoring schema as defined in this document provides
   information about a NETCONF system that could be used to aid an
   attack on that system.  The same considerations as for the base
   [RFC4741] are valid.  It is assumed that access to the data and
   operations defined in this document are subject to appropriate access
   control on the device.











































Scott & Bjorklund         Expires June 3, 2010                 [Page 27]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


7.  Acknowledgements

   The authors would like to thank Andy Bierman, Sharon Chisholm, Mehmet
   Ersue, Washam Fan, David Harrington, Balazs Lengyel, Hideki Okita,
   Juergen Schoenwaelder, Bert Wijnen and many other members of the
   NETCONF WG for providing important input to this document.













































Scott & Bjorklund         Expires June 3, 2010                 [Page 28]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


8.  IANA Considerations

   -- Editor note to IANA/RFC-Editor: we request that you make these
   assignments, in which case it is to be documented as below replacing
   'rfcXXXX' as appropriate

   This document registers one URI in the IETF XML registry.

   Following the format in [The IETF XML Registry], the following
   registration is requested.


  URI: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring
  Registrant Contact: The IESG.
  XML: N/A, the requested URI is an XML namespace.

This document registers one YANG module in the YANG Module Names
registry [RFC XXXX].

  name: ietf-netconf-monitoring
  namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring:rfcXXXX
  prefix: ns
  reference: rfcXXXX




























Scott & Bjorklund         Expires June 3, 2010                 [Page 29]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


9.  Appendix A - Change Log

   [-- Editor note to IANA/RFC-Editor: Please remove this section upon
   publication.]

9.1.  draft-ietf-netconf-monitoring-10



- sec 1.1, updated schema definition, removed YANG definition (it is
  in references instead)
- reworded text in Intro about NETCONF clients adjusting 'capabilities',
  per agreement that capacbilities can not change in a session (per
  4741bis)
- introduction, removed description of NETCONF behaviour for schema
  changes on active sesssions.  Has been moved to 4741bis
- updated namespace from '*:ns:netconf::state' to
  '*:yang:ns:ietf-netconf-monitoring:DRAFT-10'
  For details see ML archive:
  'http://www.ietf.org/mail-archive/web/netconf/current/msg05296.html'
- moved majority of sec 2 into the yang module (making module self
  describing), leaving only overview text in the RFC body.
  For details see ML archive:
  'http://www.ietf.org/mail-archive/web/netconf/current/msg05209.html'
- reworded definition of 'schema'
- removed residual references to XSD types (i.e. xs:string)
- reworded text that schema may not always be retrievable
- will add additional text that yang format is both the default
  and mandatory;  yin is optional
- updated text per Juergen's WGLC comments on v09.
  For details see ML arhive:
  'http://www.ietf.org/mail-archive/web/netconf/current/msg05306.html'
- updated reference in sec 1.1 for RFC2119
- title change to 'YANG Module for NETCONF Monitoring'

9.2.  draft-ietf-netconf-monitoring-09















Scott & Bjorklund         Expires June 3, 2010                 [Page 30]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


   - reversion of 'session-type' to 'transport'
   - element naming consistency.  All lowerCamelCase names have been
     converted to 'hyphen-delimited' or 'netconf-style-naming' as it is
     sometimes referred to on the ML.  E.g.  'sessionType' ->
     'session-type'.  This change impacts both the draft text and yang
     module.
   - &lt;get-schema&gt; operation updated:
           - now has only one mandatory parameter, 'identifier'
           - updated negative responses, including the rpc operation
           description in yang module
   - comments added to the yang module indicating that the definition of
     'session-id' is consistent with 4741bis 'session-id-type' and could
     be imported from that pending RFC.  Similar for
     'netconf-datastore-type'. This was in favour of adding further
     dependencies and delays by waiting for 4741bis to complete.

9.3.  draft-ietf-netconf-monitoring-08



   - Addresses action items from IETF75 and mailing list comments
   - Most significant is the decision to adopt YANG as normative
     As a result the publication of this draft depends on:
       o WGLC updates (if required)
       o updates to the normative model as result of netmod YANG
         changes (if required)
       o data organization changes if WG adopts a new data
         hierarchy for netmod (this draft uses "/netconf-state/")
   - XML Schema of model and IP host definition have been removed

9.4.  draft-ietf-netconf-monitoring-07



   - updates the examples in sec 4.2 per ML discussion

9.5.  draft-ietf-netconf-monitoring-06














Scott & Bjorklund         Expires June 3, 2010                 [Page 31]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


  - replaced references to 'schema-retrieval capability' with
  '&lt;get-schema&gt; operation'
  - upper/lowercase alignment on references to 'format'
  - changed negative response for &lt;get-schema&gt; to 'data-missing'
  - ML comments on v05 which required changes in the draft:
    o 2.1.2:  reworded to avoid suggestion that configurable data was
      contained in the sub-tree (per Balazs' request)
    o 2.1.2:  reworded paragraph partial lock and select statements
      (per Balazs' suggested text)
    o Fixed examples in 3.1 and added negative response (per Balazs'
      comment)
    o YANG:  location changed to leaf-list (per Balazs' comment)
    o added non-normative references to yang and yang-types (per Balazs'
      comment)
    o 2.1.3:  added YIN and RNC to format 'enums' text and models


9.6.  draft-ietf-netconf-monitoring-05



  This version addresses action items from IETF74 and comments on v4.
  - updated statistics (and counter definitions) per offline discussion:
  - updated counter definitions
  - updated data types  (addition of ZeroBasedCounter32)
  - per session counters;  see section 2.1.4
  - global counters;  see section 2.1.5
  - unique sessionId handling and WG consensus:
    o expected handling of NETCONF and non-NETCONF sessions defined
    o explicit exclusion of sessionId=0 added
    o see section 2.1.4
  - removal of subscriptions subtree;  was sec 2.1.5 in v4
  - revised XSD and YANG models

9.7.  draft-ietf-netconf-monitoring-04



   - New RPC operation defined &lt;get-schema&lt;, replacing
     &lt;list-schema&gt;.
   - Updated Abstract and Introduction:  new text, removed NETCONF
     protocol diagram.
   - Changed /netconfstate/ to /netconf-state
   - Added netconf-state/datastores
   - Changed /netconf-state/schema to /netconf-state/schemas
   - Added /netconf-state/statistics
   - Added /schema/format (and added to key)
   - Added /schema/namespace (and added to key)



Scott & Bjorklund         Expires June 3, 2010                 [Page 32]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


   - Updated examples.
   - More detailed monitored data descriptions per ML comments.

9.8.  draft-ietf-netconf-monitoring-03



   - incorporates ML list comments on v-02.

9.9.  draft-ietf-netconf-monitoring-02



- Merged content from 'draft-scott-netconf-schema-query' into this draft
- this draft now covers both schema retrievel and monitoring

9.10.  draft-ietf-netconf-monitoring-01



   - WG first draft, 'draft-ietf-netconf-monitoring-01'.
   - Related draft 'draft-scott-netconf-schema-query-00' also presented
     covering schema retrieval.  Query draft proposes new NETCONF
     operations to retrieve schema defined in this draft.

9.11.  draft-scott-netconf-monitoring-00



   - Initial draft, 'draft-scott-monitoring-00'
   - based on 'draft-netconf-chisholm-monitoring-02'
   - adopted as working group document at IETF69.



















Scott & Bjorklund         Expires June 3, 2010                 [Page 33]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


10.  References

10.1.  Normative References

   [ISO/IEC 19757-2:2008]
              ISO/IEC, "Document Schema Definition Language (DSDL) --
              Part 2: Regular-grammar-based validation -- RELAX NG",
              December 2008, <http://www.iso.org/iso/
              catalogue_detail.htm?csnumber=37605>.

   [Partial Lock RPC for NETCONF]
              Lengyel, Balazs., "Partial Lock RPC for NETCONF",
              February 2009, <http://tools.ietf.org/html/
              draft-ietf-netconf-partial-lock-09>.

   [RFC2119]  Bradner, s., ""Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14", RFC 2119, March 1997,
              <http://www.ietf.org/rfc/rfc2119.txt>.

   [RFC4741]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
              February 2006, <http://www.ietf.org/rfc/rfc4741.txt>.

   [RFC4742]  Wasserman, M. and T. Goddard, "Using the NETCONF
              Configuration Protocol over Secure SHell (SSH)",
              December 2006, <http://tools.ietf.org/html/rfc4742>.

   [RFC4743]  Goddard, T., "Using NETCONF over the Simple Object Access
              Protocol (SOAP)", December 2006,
              <http://tools.ietf.org/html/rfc4743>.

   [RFC4744]  Lear, E. and K. Crozier, "Using the NETCONF Protocol over
              the Blocks Extensible Exchange Protocol (BEEP)",
              December 2008, <http://tools.ietf.org/html/rfc4744>.

   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
              Notifications", ID draft-ietf-netconf-notification-14,
              July 2008, <http://www.ietf.org/rfc/rfc4741.txt>.

   [RFC5539]  Badra, M., "NETCONF over Transport Layer Security (TLS)",
              May 2009, <http://tools.ietf.org/html/rfc5539>.

   [The IETF XML Registry]
              Bradner, s., ""Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14", RFC 2119, March 1997,
              <http://tools.ietf.org/html/rfc3688>.

   [XML]      World Wide Web Consortium, "Extensible Markup Language
              (XML) 1.0", W3C XML, February 1998,



Scott & Bjorklund         Expires June 3, 2010                 [Page 34]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


              <http://www.w3.org/TR/1998/REC-xml-19980210>.

   [xmlschema-2]
              Biron, Paul V. and Ashok. Malhotra, "XML Schema Part 2:
              Datatypes Second Edition W3C Recommendation 28 October
              2004", RFC 2119, October 2004,
              <http://www.w3.org/TR/xmlschema-2>.

10.2.  Informative References

   [Common YANG Data Types]
              Schoenwaelder, J., "Common YANG Data Types", June 2009, <h
              ttp://tools.ietf.org/html/
              draft-ietf-netmod-yang-types-03>.

   [YANG]     Bjorklund, M., "YANG - A data modeling language for
              NETCONF", June 2009,
              <http://tools.ietf.org/html/draft-ietf-netmod-yang-07>.

































Scott & Bjorklund         Expires June 3, 2010                 [Page 35]


Internet-Draft     YANG Module for NETCONF Monitoring      November 2009


Authors' Addresses

   Mark Scott
   Ericsson
   3500 Carling Ave
   Nepean, Ontario  K2H 8E9
   Canada

   Email: mark.scott@ericsson.com


   Martin Bjorklund
   Tail-f Systems
   Klara Norra Kyrkogata 31
   SE-111 22 Stockholm,
   Sweden

   Email: mbj@tail-f.com

































Scott & Bjorklund         Expires June 3, 2010                 [Page 36]


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/