[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 draft-nmdsdt-netmod-revised-datastores

Internet Engineering Task Force                                R. Wilton
Internet-Draft                                             Cisco Systems
Intended status: Experimental                          December 21, 2015
Expires: June 23, 2016


          "With-config-state" Capability for NETCONF/RESTCONF
                  draft-wilton-netmod-opstate-yang-02

Abstract

   This document proposes a possible alternative solution for handling
   applied configuration state in YANG as described in draft-openconfig-
   netmod-opstate-01.  The proposed solution, roughly modelled on the
   with-defaults NETCONF/RESTCONF capability, aims to meet the key
   requirements set out in draft-ietf-netmod-opstate-reqs-01 without the
   need for YANG module authors to explicitly duplicate configuration
   nodes in both configuration and operational containers.  This draft
   does not address the issue of co-location of configuration and
   operational state for interfaces, nor does it provide a NETCONF
   mechanism to retrieve operational data separately from configuration
   data.

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 June 23, 2016.

Copyright Notice

   Copyright (c) 2015 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



Wilton                    Expires June 23, 2016                 [Page 1]


Internet-Draft              With-config-state              December 2015


   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Change history  . . . . . . . . . . . . . . . . . . . . .   4
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Objectives  . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  "With-config-state" encoding scheme . . . . . . . . . . . . .   4
     3.1.  cfg-intended  . . . . . . . . . . . . . . . . . . . . . .   5
     3.2.  cfg-applied . . . . . . . . . . . . . . . . . . . . . . .   5
     3.3.  cfg-status  . . . . . . . . . . . . . . . . . . . . . . .   6
     3.4.  cfg-status-reason . . . . . . . . . . . . . . . . . . . .   6
     3.5.  Non-leaf config nodes . . . . . . . . . . . . . . . . . .   6
   4.  Retrieval of intended and applied configuration . . . . . . .   7
     4.1.  all-cfg . . . . . . . . . . . . . . . . . . . . . . . . .   8
     4.2.  intended-cfg-only . . . . . . . . . . . . . . . . . . . .   8
     4.3.  applied-cfg-only  . . . . . . . . . . . . . . . . . . . .   8
     4.4.  diff-cfg-only . . . . . . . . . . . . . . . . . . . . . .   8
   5.  "With-config-state" Capability  . . . . . . . . . . . . . . .   8
     5.1.  Overview  . . . . . . . . . . . . . . . . . . . . . . . .   8
     5.2.  Dependencies  . . . . . . . . . . . . . . . . . . . . . .   8
     5.3.  Capability Identifier . . . . . . . . . . . . . . . . . .   8
   6.  Suggested layout of data models . . . . . . . . . . . . . . .   9
   7.  Addressing the requirements of the NETMOD Operational State
       Requirements draft  . . . . . . . . . . . . . . . . . . . . .   9
     7.1.  Addressing requirement 1: 'Ability to interact with both
           intended and applied configuration' . . . . . . . . . . .   9
     7.2.  Addressing requirement 2: Support for both synchronous
           and asynchronous configuration operations . . . . . . . .  10
     7.3.  Addressing requirement 3: Separation of the applied
           configuration and derived state aspects of operational
           state; ability to retreive them independently and
           together  . . . . . . . . . . . . . . . . . . . . . . . .  10
     7.4.  Addressing requirement 4: Ability to relate configuration
           with its corresponding operational state  . . . . . . . .  11
     7.5.  Addressing requirement 5: Ability for distinct modules to
           leverage a common model-structure . . . . . . . . . . . .  11
     7.6.  Other benefits of the solution proposed in this draft . .  11
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  11
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  12
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  12
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  12



Wilton                    Expires June 23, 2016                 [Page 2]


Internet-Draft              With-config-state              December 2015


     11.1.  Normative References . . . . . . . . . . . . . . . . . .  12
     11.2.  Informative References . . . . . . . . . . . . . . . . .  13
   Appendix A.  Encoding examples for NETCONF and RESTCONF . . . . .  13
     A.1.  NETCONF get-config request using with-config-state with
           all-cfg option  . . . . . . . . . . . . . . . . . . . . .  14
     A.2.  NETCONF get-config request using with-config-state with
           diff-cfg-only option  . . . . . . . . . . . . . . . . . .  16
     A.3.  NETCONF get-config request using with-config-state with
           applied-cfg-only option . . . . . . . . . . . . . . . . .  18
     A.4.  RESTCONF GET request using with-config-state with all-cfg
           option (JSON) . . . . . . . . . . . . . . . . . . . . . .  20
   Appendix B.  Alternative meta-data solution using attributes  . .  22
     B.1.  Rough solution outline  . . . . . . . . . . . . . . . . .  23
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  24

1.  Introduction

   The NETMOD Operational State Requirements
   [I-D.ietf-netmod-opstate-reqs] sets out a number of operational
   requirements and proposed solutions for handling intended and applied
   config state when using YANG models.  This document sets out a
   possible alternative solution for some of those requirements.

   The solution proposed in this document does not require any changes
   to any existing YANG modules to support intended and applied config
   state.  In particular: the proposed solution does not require the
   data models to be explicitly modelled with separate configuration and
   operational containers, and it does not require that all
   configuration and operational state nodes and leaves to be defined as
   groupings.

   Nor does the proposed solution make explicit use of separate
   datastores to model intended configuration separately from applied
   configuration.

   Instead, the solution proposed here is a method for generating an
   enhanced schema based on any YANG model that is optionally used by
   network management protocols.  This enhanced schema includes up to
   four data leaves for each configuration node defined in the YANG
   model.  These cover both the intended and applied values, along with
   an additional reason code and message if the applied configuration
   does not match the intended configuration.

   Although the solution described here is only defined in the context
   of NETCONF and RESTCONF, it should be possible to extend the same
   YANG config data encoding mechanism to other protocol schemes used to
   access YANG data if required.




Wilton                    Expires June 23, 2016                 [Page 3]


Internet-Draft              With-config-state              December 2015


1.1.  Change history

   The changes from draft version 00 to 01 is to fix a couple of
   mistakes in the example YANG module.

   The changes from draft version 01 to 02 primarily updates Section 7
   to reflect the refinements to the requirements specification.  In
   addition an overview of a YANG Metadata based variant of the original
   solution is described in Appendix B.

1.2.  Terminology

   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 RFC 2119 [RFC2119].

   The terms 'intended configuration', 'applied configuration' and
   'derived state' are defined in NETMOD Operational State Requirements
   [I-D.ietf-netmod-opstate-reqs].

   The following additional terms are used in this document:

      operational nodes - this term is colloquially used in this draft
      to refer to "config false" YANG nodes.

2.  Objectives

   The aim of this draft is to provide a partial alternative solution to
   the requirements set out in NETMOD Operational State Requirements
   [I-D.ietf-netmod-opstate-reqs].  An explanation of how the specific
   requirements are addressed is described in Section 7.

3.  "With-config-state" encoding scheme

   The solution proposed in this document makes use of a new encoding
   scheme that is used to represent YANG configuration nodes in NETCONF
   and RESTCONF.  An optional parameter, called <with-config-state> and
   defined below, indicates when this new encoding scheme is used.

   When the with-config-state option is used each YANG configuration
   leaf in the datastore is returned in a different format.  Rather than
   being encoded as an XML or JSON leaf element that holds the
   configured value, it is instead returned as a node element, with the
   same name as the YANG config leaf, that contains up to four separate
   leaf elements.  The four leaf elements that the node may contain are
   'cfg-intended', 'cfg-applied', 'cfg-status', and 'cfg-status-reason'.
   Theses leaves are externally addressable through using the full path
   of the leaf, providing explicit distinct paths for intended



Wilton                    Expires June 23, 2016                 [Page 4]


Internet-Draft              With-config-state              December 2015


   configuration vs applied configuration.  These elements are described
   in more detail in the following sub-sections.  Concrete examples of
   the encoding for NETCONF and RESTCONF requests are given in
   Appendix A.

3.1.  cfg-intended

   The cfg-intended leaf represents the intended configuration of the
   device, and is of the same datatype and holds the same value as the
   normal YANG data model configuration leaf.  The cfg-intended leaf is
   only present if the associated configuration node exists in the YANG
   data model.

   The cfg-intended leaf is semantically equivalent to the config leaf
   in the YANG data model that is based on, and hence is logically read/
   writable.  In particular, when the <with-config-state> parameter is
   used, management requests to modify the configuration may also use
   the full path to the cfg-intended leaf.  The server semantics for
   writing to the cfg-intended leaf are exactly the same as for writing
   to the standard YANG config node path - the flexibility is provided
   as a convenience to the NMS client.

3.2.  cfg-applied

   The cfg-applied leaf represents the applied configuration, and is of
   the same datatype as a normal YANG data model configuration leaf.  If
   there is no configuration currently in effect then the cfg-applied
   leaf is not present.

   The cfg-applied leaf is read only.

   To give some examples:

      If the configuration has been successfully applied then the cfg-
      applied leaf would exactly match the cfg-intended leaf.

      If a new item of configuration is in the process of being applied
      then the cfg-intended leaf holds the intended configuration value,
      and the cfg-applied leaf would not be present until the
      configuration is in effect.

      If an existing item of configuration is in the process of being
      deleted then the cfg-applied leaf would hold the current
      configuration value, and the cfg-intended leaf would not be
      present.  Once the delete operation has completed, the
      configuration node element itself would logically be deleted.





Wilton                    Expires June 23, 2016                 [Page 5]


Internet-Draft              With-config-state              December 2015


      If the configuration value of an existing item of configuration is
      in the process of being changed, then the cfg-intended leaf would
      hold the new proposed value, and the cfg-applied leaf would hold
      the existing value that is currently in effect.

3.3.  cfg-status

   The cfg-status leaf is used, when required, to indicate why the value
   of the cfg-applied leaf does not match the value of the cfg-intended
   leaf.  It is only present when the values of the cfg-intended and
   cfg-applied leaves do not match.

   The cfg-status leaf is read only.

   The cfg-status leaf can take one of following values:

      in-progress - the config operation is in the process of being
      applied.

      waiting - the config operation is waiting for other configuration
      to be applied or hardware to be available before it can be
      applied.  Additional specific information may be provided in the
      cfg-status-reason leaf.

      failed - the config operation failed to be applied.  Additional
      information may be provided in the cfg-status-reason leaf to
      indicate the reason for the failure.

3.4.  cfg-status-reason

   The cfg-status-reason leaf may be used to provide additional
   information as to why the value of the cfg-applied leaf does not
   match the value of the cfg-intended leaf.

   The cfg-status-reason leaf may only be present in the case that the
   cfg-status leaf is present and is set to either waiting or failed.

   The cfg-status-reason leaf is read only.

3.5.  Non-leaf config nodes

   Non-leaf config nodes require some special handling.  In particular,
   containers with presence and list elements must be considered.

   The proposed solution for both types of node is the same.  The cfg-
   intended, cfg-applied, cfg-status, and cfg-status-reason leaf nodes
   are implicitly added as direct descendants of the presence-container
   or list element.



Wilton                    Expires June 23, 2016                 [Page 6]


Internet-Draft              With-config-state              December 2015


   Note: There is an open issue that using these leaves directly opens
   up a potential naming clash between the "cfg-*" names above and
   existing explicitly defined child nodes in the YANG module
   definition.  There are a few possible ways that this might be
   addressed:

      Making the four "cfg-*" leaves reserved names.  I.e. to ensure
      that they are not used in general YANG modules.

      By inserting an implicit node between all child nodes under the
      container or list element.  This would automatically ensure that
      there can be no naming clash between the defined YANG nodes and
      the implicitly added "cfg-*" leaves.

      By using a reserved namespace for the "cfg-*" leaves to ensure
      that they cannot clash with any explicitly defined in the YANG
      module.

4.  Retrieval of intended and applied configuration

   To make use of the new encoding scheme defined above, this document
   defines a new parameter, called <with-config-state>, which can be
   added to specific NETCONF operation request messages, or as a
   RESTCONF query parameter, to control how retrieval of configuration
   nodes is treated by the server.

   The <with-config-state> parameter is supported for the following
   NETCONF operations: <get>, <get-config>, <edit-config>, <delete-
   config>.

   The <with-config-state> query parameter is supported for the
   following RESTCONF operations: GET, PUT, POST, PATCH, DELETE.

   Use of the <with-config-state> parameter ensures that all config
   nodes are always returned using the defined encoding.  It also allows
   servers to explicitly reference the cfg-* leaves in requests and
   updates.

   A server that implements this specification MUST accept the <with-
   config-state> parameter containing the enumeration for any of the
   with-config-state modes it supports.  The <with-config-state>
   parameter contains one of the four enumerated values defined in this
   section.








Wilton                    Expires June 23, 2016                 [Page 7]


Internet-Draft              With-config-state              December 2015


4.1.  all-cfg

   When data is retrieved with a <with-config-state> parameter equal to
   'all-cfg', all 'cfg-*' nodes are reported using the encoding scheme
   defined in Section 3.

4.2.  intended-cfg-only

   When data is retrieved with a <with-config-state> parameter equal to
   'intended-cfg', only the 'cfg-intended' leaves are reported using the
   encoding scheme defined in Section 3.  All other 'cfg-*' leaves are
   omitted.

4.3.  applied-cfg-only

   When data is retrieved with a <with-config-state> parameter equal to
   'applied-cfg-only', only the 'cfg-applied' leaves are reported using
   the encoding scheme defined in Section 3.  All other 'cfg-*' leaves
   are omitted.

4.4.  diff-cfg-only

   When data is retrieved with a <with-config-state> parameter equal to
   'diff-cfg-only', config nodes are only returned if the value of the
   cfg-intended leaf does not match the value of the cfg-applied leaf.
   If the config node is returned then all appropriate 'cfg-*' leaves
   are returned as per the encoding scheme defined in Section 3.

5.  "With-config-state" Capability

5.1.  Overview

   The :with-config-state capability indicates whether a server supports
   the with-config-state functionality.  For a server that indicates
   support for the :with-config-state capability it must support at
   least the 'all-cfg' option.  It may also indicate support for the
   additional with-config-state retrieval modes.

5.2.  Dependencies

   None

5.3.  Capability Identifier

   urn:ietf:params:netconf:capability:with-config-state:1.0

   The identifer has a paramater: "also-supported".  This parameter
   indicates which additional enumeration values (besides 'all-cfg') the



Wilton                    Expires June 23, 2016                 [Page 8]


Internet-Draft              With-config-state              December 2015


   server will accept for the <with-config-state> parameter in
   Section 4.  The value of the parameter is a comma-separated list of
   one or more modes that are supported.  Possible modes are 'intended-
   cfg-only', 'applied-cfg-only', 'diff-cfg-only' as defined in
   Section 4.

6.  Suggested layout of data models

   Generally, to ensure that operational data and configuration data can
   be easily related, this draft recommends that configuration and
   associated operational nodes either be co-located in the same YANG
   container, or that operational nodes should be placed as descendants
   nodes of the configuration nodes on which they are related to.

   YANG clients should be able to assume that configuration and
   operational nodes within the same container (and defined in the same
   namespace) are implicitly related.  Likewise any descendant
   operational nodes are also implicitly related to any parent
   configuration node.

   This draft also supports a variant of the "related-state" statement
   defined in Operational State Enhancements for YANG, NETCONF, and
   RESTCONF.  [I-D.kwatsen-netmod-opstate], but proposes that the
   statement be called "related-config" instead and that the same
   logical two-way binding between a config and operational node should
   be expressed in the reverse direction.  I.e. it should be modelled as
   an extension statement on an operational node which refers back to
   the configuration node upon which it depends.  Expressing the
   dependency this way round is anticipated to be much easier to use by
   model authors, avoiding the perceived likely heavy use of
   augmentation statements that a 'related-state' statement would
   probably entail.

7.  Addressing the requirements of the NETMOD Operational State
    Requirements draft

   When reading this section, please refer back to NETMOD Operational
   State Requirements [I-D.ietf-netmod-opstate-reqs] for the definition
   of those requirements.  They are not reproduced here.

7.1.  Addressing requirement 1: 'Ability to interact with both intended
      and applied configuration'

   This requirement (and associated subpoints) are met in the following
   ways:

   Requirement 1.A: The applied configuration can be retrieved via
   making a NETCONF (or management protocol equivalent) <get-config>



Wilton                    Expires June 23, 2016                 [Page 9]


Internet-Draft              With-config-state              December 2015


   request with the 'all-cfg' or 'applied-cfg-only' option of the <with-
   config-state> parameter.

   Requirement 1.B: This would be enforced by the protocol and/or the
   backing datastore.

   Requirement 1.C: The schema encoding scheme proposed in this solution
   trivially meets this requirement.

   Requirement 1.D: Not directly appicable since this is a requirement
   on the backend server providing the data rather than the encoding
   schema.

7.2.  Addressing requirement 2: Support for both synchronous and
      asynchronous configuration operations

   This requirement (and associated subpoints) are met in the following
   ways:

   Requirement 2.A: This requirement is not addressed by this draft.  It
   is anticipated that this would be solved by protocols specific
   extentions, and isn't directly concerned with how applied
   configuration is represented to management clients.

   Requirement 2.B: This optional requirement is supported by using
   either the 'all-cfg' or 'diff-cfg-only' option of the <with-config-
   state> parameter.

   Requirement 2.C: This requirement is not addressed by this draft.
   This requirement depends on the underlying protocol that is being
   used to configure the system.

7.3.  Addressing requirement 3: Separation of the applied configuration
      and derived state aspects of operational state; ability to
      retreive them independently and together

   This requirement (and associated subpoints) are met in the following
   ways:

   Requirement 3.A: This requirement is supported via making a NETCONF
   (or management protocol equivalent) <get-config> request with the
   'applied-cfg-only' option of the <with-config-state> parameter.

   Requirement 3.B: This requirement is not directly supported by this
   draft.  The proposed protocol extension allows for just the intended
   config vs applied config nodes to be returned.  RESTCONF already
   supports querying config separately from operational state through
   use of the 'content' query paremeter.  A separate NETCONF protocol



Wilton                    Expires June 23, 2016                [Page 10]


Internet-Draft              With-config-state              December 2015


   extension would be required to return just the operational nodes
   without any of the configuration nodes, such as the <get-state>
   enhancement described in Operational State Enhancements for YANG,
   NETCONF, and RESTCONF [I-D.kwatsen-netmod-opstate].

   Requirement 3.C: This requirement is supported via making a NETCONF
   (or mgmt protocol equivalent) <get> request with the 'applied-cfg-
   only' option of the <with-config-state> parameter.

7.4.  Addressing requirement 4: Ability to relate configuration with its
      corresponding operational state

   This requirement (and associated subpoints) are met in the following
   ways:

   Requirement 4.A: This requirement is trivially met using the encoding
   scheme presented in this draft.

   Requirement 4.B: This requirement is met using the scheme described
   in Section 6.

   Requirement 4.C: The solution described in requirement 4.B meets this
   requirement.

7.5.  Addressing requirement 5: Ability for distinct modules to leverage
      a common model-structure

   This requirement is not addressed by this draft, it is covered by
   Network Device YANG Organizational Model
   [I-D.rtgyangdt-rtgwg-device-model].

7.6.  Other benefits of the solution proposed in this draft

   In additional to the formal requirements expressed as part of the
   requirements draft, the solution proposed in this draft also meets
   the desirable property expressed in the original OpenConfig opstate
   requirements draft of ensuring that there is a separate unique schema
   path to both the intended and applied configuration nodes.

8.  Acknowledgements

   The authors wish to thank Andy Bierman, Einar Nilsen-Nygaard, Neil
   Ketley, Peyman Owladi and Juergen Schoenwaelder for their helpful
   comments, ideas and expertise contributing to this draft.







Wilton                    Expires June 23, 2016                [Page 11]


Internet-Draft              With-config-state              December 2015


9.  IANA Considerations

   TBD.  This document would at least need to register a new capability
   identifier URN in the 'Network Configuration Protocol (NETCONF)
   Capability URNs' registry for the with-config-state optional
   capability.'".

10.  Security Considerations

   The proposal in this document does not have any security
   considerations beyond the existing NETCONF/RESTCONF/YANG security
   considerations.

11.  References

11.1.  Normative References

   [I-D.ietf-netconf-restconf]
              Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", draft-ietf-netconf-restconf-09 (work in
              progress), December 2015.

   [I-D.ietf-netmod-opstate-reqs]
              Watsen, K. and T. Nadeau, "NETMOD Operational State
              Requirements", draft-ietf-netmod-opstate-reqs-01 (work in
              progress), December 2015.

   [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>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <http://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <http://www.rfc-editor.org/info/rfc6241>.

   [RFC6243]  Bierman, A. and B. Lengyel, "With-defaults Capability for
              NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
              <http://www.rfc-editor.org/info/rfc6243>.






Wilton                    Expires June 23, 2016                [Page 12]


Internet-Draft              With-config-state              December 2015


11.2.  Informative References

   [I-D.ietf-netmod-yang-metadata]
              Lhotka, L., "Defining and Using Metadata with YANG",
              draft-ietf-netmod-yang-metadata-02 (work in progress),
              September 2015.

   [I-D.kwatsen-netmod-opstate]
              Watsen, K., Bierman, A., Bjorklund, M., and J.
              Schoenwaelder, "Operational State Enhancements for YANG,
              NETCONF, and RESTCONF", draft-kwatsen-netmod-opstate-00
              (work in progress), September 2015.

   [I-D.rtgyangdt-rtgwg-device-model]
              Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps,
              "Network Device YANG Organizational Model", draft-
              rtgyangdt-rtgwg-device-model-01 (work in progress),
              September 2015.

Appendix A.  Encoding examples for NETCONF and RESTCONF

   A sample encoding of the <with-config-state> enhancement is described
   below.

   A simple example module is provided to illustrate the subsequent
   examples.  This is not a real module, and is not intended for any
   real use.
























Wilton                    Expires June 23, 2016                [Page 13]


Internet-Draft              With-config-state              December 2015


   module example-interfaces {

     namespace "http://example.com/ns/interfaces";

     prefix exam;

     container interfaces {
       description "Example interfaces group";

       list interface {
         key name;
         description "Example interface entry";

         leaf name {
           type string {
             length "1 .. max";
           }
           description
             "The administrative name of the interface.";
         }

         leaf mtu {
           type uint32;
           default 1514;
           description
             "The maximum transmission unit (MTU) value assigned to
              this interface.";
         }
       }
     }
   }

A.1.  NETCONF get-config request using with-config-state with all-cfg
      option

   A get-config request is made for the interfaces subtree using the
   <with-config-state> enhancement and 'all-cfg' option that returns all
   config nodes with explicit cfg-intended and cfg-applied leaves, and
   cfg-status and cfg-status-reason leaves when appropriate.

   In this example, at the time of processing the get-config request,
   the NETCONF server is also asynchronously processing a request to set
   the MTU leaf to 9000 for 4 interface config nodes.








Wilton                    Expires June 23, 2016                [Page 14]


Internet-Draft              With-config-state              December 2015


<rpc message-id="101"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <filter type="subtree">
      <interfaces xmlns="http://example.com/ns/interfaces"/>
    </filter>
    <with-config-state
     xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-config-state">
      all-cfg
    </with-config-state>
  </get>
</rpc>

   The response indicates that at the time of the reply:

      The request to set the MTU leaf on eth0/0 to 9000 has completed.

      The request to change the MTU leaf on eth0/1 from 2000 to 9000 is
      in progress.

      The request to set the MTU leaf on eth0/2 to 9000 is in progress.

      The request to set the MTU leaf on eth1/0 to 9000 is blocked
      because the necessary hardware is not present.

   <rpc-reply message-id="101"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <data>
       <interfaces xmlns="http://example.com/ns/interfaces">
         <interface>
           <cfg-intended/>
           <cfg-actual/>
           <name>
             <cfg-intended>eth0/0</cfg-intended>
             <cfg-actual>eth0/0</cfg-actual>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-actual>9000</cfg-actual>
           </mtu>
         </interface>
         <interface>
           <cfg-intended/>
           <cfg-actual/>
           <name>
             <cfg-intended>eth0/1</cfg-intended>
             <cfg-actual>eth0/1</cfg-actual>
           </name>



Wilton                    Expires June 23, 2016                [Page 15]


Internet-Draft              With-config-state              December 2015


           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-actual>2000</cfg-actual>
             <cfg-status>in-progress</cfg-status>
           </mtu>
         </interface>
         <interface>
           <cfg-intended/>
           <cfg-actual/>
           <name>
             <cfg-intended>eth0/2</cfg-intended>
             <cfg-actual>eth0/2</cfg-actual>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-status>in-progress</cfg-status>
           </mtu>
         </interface>
         <interface>
           <cfg-intended/>
           <cfg-status>waiting</cfg-status>
           <cfg-status-reason>Linecard 1 is not available
           </cfg-status-reason>
           <name>
             <cfg-intended>eth1/0</cfg-intended>
             <cfg-status>waiting</cfg-status>
             <cfg-status-reason>Linecard 1 is not available
             </cfg-status-reason>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-status>waiting</cfg-status>
             <cfg-status-reason>Linecard 1 is not available
             </cfg-status-reason>
           </mtu>
         </interface>
       </interfaces>
     </data>
   </rpc-reply>

A.2.  NETCONF get-config request using with-config-state with diff-cfg-
      only option

   A get-config request is made for the interfaces subtree using the
   <with-config-state> enhancement and 'diff-cfg-only' option that only
   returns nodes where the cfg-intended node does not match the cfg-
   applied node.  Appropriate parent nodes are also returned.




Wilton                    Expires June 23, 2016                [Page 16]


Internet-Draft              With-config-state              December 2015


   As per the previous examples, at the time of processing the get-
   config request, the NETCONF server is also asynchronously processing
   a request to set the MTU leaf to 9000 for 4 interface config nodes.

<rpc message-id="102"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <filter type="subtree">
      <interfaces xmlns="http://example.com/ns/interfaces"/>
    </filter>
    <with-config-state
     xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-config-state">
      diff-cfg-only
    </with-config-state>
  </get>
</rpc>

   The response indicates that the outstanding configuration requests
   still to be processed are:

      The request to change the MTU leaf on eth0/1 from 2000 to 9000 is
      in progress.

      The request to set the MTU leaf on eth0/2 to 9000 is in progress.

      The request to set the MTU leaf on eth1/0 to 9000 is blocked
      because the necessary hardware is not present.

   <rpc-reply message-id="102"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <data>
       <interfaces xmlns="http://example.com/ns/interfaces">
         <interface>
           <cfg-intended/>
           <cfg-actual/>
           <name>
             <cfg-intended>eth0/1</cfg-intended>
             <cfg-actual>eth0/1</cfg-actual>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-actual>2000</cfg-actual>
             <cfg-status>in-progress</cfg-status>
           </mtu>
         </interface>
         <interface>
           <cfg-intended/>
           <cfg-actual/>



Wilton                    Expires June 23, 2016                [Page 17]


Internet-Draft              With-config-state              December 2015


           <name>
             <cfg-intended>eth0/2</cfg-intended>
             <cfg-actual>eth0/2</cfg-actual>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-status>in-progress</cfg-status>
           </mtu>
         </interface>
         <interface>
           <cfg-intended/>
           <cfg-status>waiting</cfg-status>
           <cfg-status-reason>Linecard 1 is not available
           </cfg-status-reason>
           <name>
             <cfg-intended>eth1/0</cfg-intended>
             <cfg-status>waiting</cfg-status>
             <cfg-status-reason>Linecard 1 is not available
             </cfg-status-reason>
           </name>
           <mtu>
             <cfg-intended>9000</cfg-intended>
             <cfg-status>waiting</cfg-status>
             <cfg-status-reason>Linecard 1 is not available
             </cfg-status-reason>
           </mtu>
         </interface>
       </interfaces>
     </data>
   </rpc-reply>

A.3.  NETCONF get-config request using with-config-state with applied-
      cfg-only option

   A get-config request is made for the interfaces subtree using the
   <with-config-state> enhancement and 'applied-cfg-only' option that
   only returns the currently applied configuration.

   As per the previous examples, At the time of processing the get-
   config request, the NETCONF server is also asynchronously processing
   a request to set the MTU leaf to 9000 for 4 interface config nodes.










Wilton                    Expires June 23, 2016                [Page 18]


Internet-Draft              With-config-state              December 2015


<rpc message-id="103"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-config>
    <filter type="subtree">
      <interfaces xmlns="http://example.com/ns/interfaces"/>
    </filter>
    <with-config-state
     xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-config-state">
      applied-cfg-only
    </with-config-state>
  </get>
</rpc>

   The response indicates that the current applied configuration of the
   selected nodes is:

      The MTU leaf of eth0/0 is 9000.

      The MTU leaf of eth0/1 is 2000.

      Eth0/2 has no MTU leaf applied.

      [Implicitly - there is no applied configuration for Eth1/0 since
      the hardware is not present.]



























Wilton                    Expires June 23, 2016                [Page 19]


Internet-Draft              With-config-state              December 2015


   <rpc-reply message-id="103"
              xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <data>
       <interfaces xmlns="http://example.com/ns/interfaces">
         <interface>
           <cfg-actual/>
           <name>
             <cfg-actual>eth0/0</cfg-actual>
           </name>
           <mtu>
             <cfg-actual>9000</cfg-actual>
           </mtu>
         </interface>
         <interface>
           <cfg-actual/>
           <name>
             <cfg-actual>eth0/1</cfg-actual>
           </name>
           <mtu>
             <cfg-actual>2000</cfg-actual>
           </mtu>
         </interface>
         <interface>
           <cfg-actual/>
           <name>
             <cfg-actual>eth0/2</cfg-actual>
           </name>
         </interface>
       </interfaces>
     </data>
   </rpc-reply>

A.4.  RESTCONF GET request using with-config-state with all-cfg option
      (JSON)

   An equivalent RESTCONF/JSON example to Appendix A.1 is provided to
   illustrate the equivalent JSON encoding.

   A REST GET request is made for all config data using the <with-
   config-state> enhancement and 'all-cfg' option that all returns all
   config nodes with explicit cfg-intended and cfg-applied leaves.

   In this example, at the time of processing the GET request, the
   RESTCONF server is also asynchronously processing a request to set
   the MTU leaf to 9000 for 4 interface config nodes.






Wilton                    Expires June 23, 2016                [Page 20]


Internet-Draft              With-config-state              December 2015


GET /restconf/data/example-events:events?content=config&with-config-state=all-cfg
  HTTP/1.1
Host: example.com
Accept: application/yang.data+json

   As per Appendix A.1, the response indicates that at the time of the
   reply:

      The request to set the MTU leaf on eth0/0 to 9000 has completed.

      The request to change the MTU leaf on eth0/1 from 2000 to 9000 is
      in progress.

      The request to set the MTU leaf on eth0/2 to 9000 is in progress.

      The request to set the MTU leaf on eth1/0 to 9000 is blocked
      because the necessary hardware is not present.

   HTTP/1.1 200 OK
   Date: Mon, 1 Apr 2015 04:01:00 GMT
   Server: example-server
   Content-Type: application/yang.data+json

   {
   "example:interfaces": [
     {
       "cfg-intended" = null,
       "cfg-actual" = null,
       "name" : {
         "cfg-intended" = "eth0/0",
         "cfg-actual" = "eth0/0"
       },
       "mtu" : {
         "cfg-intended" = 9000,
         "cfg-actual" = 9000
       },
     },
     {
       "cfg-intended" = null,
       "cfg-actual" = null,
       "name" : {
         "cfg-intended" = "eth0/1",
         "cfg-actual" = "eth0/1"
       },
       "mtu" : {
         "cfg-intended" = 9000,
         "cfg-actual" = 2000,
         "cfg-status" = "in-progress"



Wilton                    Expires June 23, 2016                [Page 21]


Internet-Draft              With-config-state              December 2015


       },
     },
     {
       "cfg-intended" = null,
       "cfg-actual" = null,
       "name" : {
         "cfg-intended" = "eth0/2",
         "cfg-actual" = "eth0/2"
       },
       "mtu" : {
         "cfg-intended" = 9000,
         "cfg-status" = "in-progress"
       },
     },
     {
       "cfg-intended" = null,
       "cfg-status" = "waiting",
       "cfg-status-reason" = "Linecard 1 is not available",
       "name" : {
         "cfg-intended" = "eth1/0",
         "cfg-status" = "waiting",
         "cfg-status-reason" = "Linecard 1 is not available",
       },
       "mtu" : {
         "cfg-intended" = 9000,
         "cfg-status" = "waiting",
         "cfg-status-reason" = "Linecard 1 is not available",
       },
     },
   ]
   }

Appendix B.  Alternative meta-data solution using attributes

   In addition to the solution written up in the draft, a variant of it
   has been proposed on the NETMOD WG email alias.  The variant,
   proposed by Andy Bierman, is to broadly encode the 'cfg-intended' vs
   'cfg-applied' meta-data using Defining and Using Metadata with YANG
   [I-D.ietf-netmod-yang-metadata].

   Using YANG Metadata certainly has the allure of a cleaner
   representation of the applied configuration state, particularly when
   using XML as the encoding where XML attributes can be used to
   represent the meta-data.  This cleaner representation doesn't
   directly apply to JSON or any other encodings that don't natively
   support attributes.





Wilton                    Expires June 23, 2016                [Page 22]


Internet-Draft              With-config-state              December 2015


B.1.  Rough solution outline

   To aid discussion, an outline of a possible YANG Metadata based
   solution follows.  Broadly, the solution is similar to the one that
   has been described in the main body of this draft, and the encoding
   proposed below would only be used when the client opt in to receive
   them via an appropriate protocol extension.

   Five YANG metadata attribute are defined:

      cfg-changing: this attribute has three values ('creating',
      'changing', 'deleting') and is only present for configuration
      nodes that are changing state.

      old-value: this attribute holds the currently applied leaf value
      only for the cases that the cfg-changing attribute has the value
      'changing' or 'deleting'.  This option is not used for the
      'applied-cfg' protocol option described subsequently.

      new-value: this attribute holds the intended leaf value only for
      the cases that the cfg-changing attribute has the value 'creating'
      or 'changing' and it is only used in conjunction with the
      'applied-cfg' protocol option described subsequently.

      cfg-status: this attribute holds either the value 'waiting' or
      'failed'.  It is only used in the case that a configuration change
      could not be completed for some reason.

      failure-reason: this attribute holds a string containing a system
      provided error message as to why applying the configuration
      failed.  It is only used if the cfg-status reason is 'failed'.

   Each of the five YANG metadata attributes above are only used when
   requried.  In particular if a configuration leaf is both intended and
   applied then no extra YANG metdata attributes are required at all.

   The same four protocol options defined previously in the main body of
   this draft are also supported.

      all-cfg: if this option is used then all config nodes are included
      if they are either intended or applied.  The value returned for
      the config leaf is always the intended value, unless the leaf is
      being deleted in which case it has no value.

      intended-cfg: this option indicates that only the intended
      configuration nodes are returned.  I.e. it excludes any leaves
      that are applied, but currently in the process of being deleted
      (and hence have no intended value)



Wilton                    Expires June 23, 2016                [Page 23]


Internet-Draft              With-config-state              December 2015


      applied-cfg: this option indicates that only the applied
      configuration nodes are returned.  I.e. it excludes any leaves
      that are intended, but not yet applied.  In contrast to the other
      three options, the value returned for the config leaves are the
      applied configuration values rather than the intended
      configuration values provided in all other cases.

      diff-cfg: this only includes config nodes that are changing state.
      I.e. the cfg-changing attribute will be set on all leaves that are
      returned.

Author's Address

   Robert Wilton
   Cisco Systems

   Email: rwilton@cisco.com


































Wilton                    Expires June 23, 2016                [Page 24]


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