NETCONF                                                       A. Bierman
Internet-Draft                                        netconfcentral.org
Intended status: Standards Track                              B. Lengyel
Expires: February 28, 2009                                      Ericsson
                                                         August 27, 2008


                  With-defaults capability for NETCONF
                 draft-bierman-netconf-with-defaults-00

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   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 February 28, 2009.

Copyright Notice

   Copyright (C) The IETF Trust (2008).

Abstract

   The NETCONF protocol defines ways to read configuration data from a
   NETCONF agent.  Part of this data is not set by the NETCONF manager,
   but rather set to a default value by the NETCONF agent.  In many
   situations the NETCONF manager has a priori knowledge about this
   data, so the NETCONF agent does not need to send it to the manager.
   In other situations the NETCONF manger will need this data as part of
   the NETCONF rpc reply messages.  This document defines a capability-



Bierman & Lengyel       Expires February 28, 2009               [Page 1]


Internet-Draft                with-defaults                  August 2008


   based extension to the NETCONF protocol that allows the NETCONF
   manager to control whether default values are part of NETCONF rpc
   reply messages.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  3
       1.1.1.  Requirements Notation  . . . . . . . . . . . . . . . .  3
       1.1.2.  NETCONF Terms  . . . . . . . . . . . . . . . . . . . .  3
   2.  With-defaults Capability . . . . . . . . . . . . . . . . . . .  4
     2.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . .  4
       2.1.1.  Basic handling of default data . . . . . . . . . . . .  4
     2.2.  Dependencies . . . . . . . . . . . . . . . . . . . . . . .  5
     2.3.  Capability Identifier  . . . . . . . . . . . . . . . . . .  5
     2.4.  New Operations . . . . . . . . . . . . . . . . . . . . . .  5
     2.5.  Modifications to Existing Operations . . . . . . . . . . .  5
   3.  Interactions with Other Capabilities . . . . . . . . . . . . .  7
   4.  Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . .  7
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  8
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . .  9
   7.  Open Issues  . . . . . . . . . . . . . . . . . . . . . . . . . 10
     7.1.  Augmenting the base RPCs . . . . . . . . . . . . . . . . . 10
     7.2.  Third option: Trim . . . . . . . . . . . . . . . . . . . . 10
     7.3.  List affected operations or generalize . . . . . . . . . . 10
   8.  Normative References . . . . . . . . . . . . . . . . . . . . . 11
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12
   Intellectual Property and Copyright Statements . . . . . . . . . . 13






















Bierman & Lengyel       Expires February 28, 2009               [Page 2]


Internet-Draft                with-defaults                  August 2008


1.  Introduction

   The NETCONF protocol defines ways to read configuration data from a
   NETCONF agent.  Part of this data is not set by the NETCONF manager,
   but rather set to a default value by the NETCONF agent.  In many
   situations the NETCONF manager has a priori knowledge about this
   data, so the NETCONF agent does not need to send it to the manager.
   A priori knowledge can be e.g. a document formally describing the
   data models supported by the NETCONF agent.  It is quite common for
   networking devices to suppress the output of parameters set to the
   default value.  This is done to save CPU time and non-volatile
   memory.  In addition, there are likely to be a large number of such
   parameters.  Is is often not useful for network operators to view all
   these default values.  It is usually more interesting to view just
   the parameters which have been explicitly set by the network
   operator.

   However there are perfectly valid use-cases when a NETCONF manager
   will need the default data from the node.  Documentation about
   default values is often unreliable or unavailable.  Some management
   applications might not have the capabilities to correctly parse and
   interpret formal data models.  Human users might want to understand
   the received data without extensive consultation of the
   documentation.  In all theses cases the NETCONF manager will need
   default data as part of the NETCONF rpc reply messages.

   This document defines a capability-based extension to the NETCONF
   protocol that allows the NETCONF manager to control whether default
   data is part of NETCONF rpc reply messages.

1.1.  Terminology

1.1.1.  Requirements Notation

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

1.1.2.  NETCONF Terms

   o  Default data: Data that is set by the NETCONF agent whenever the
      NETCONF manager does not provide a specific value for the relevant
      data item.  In the context of this document only configuration
      data is considered, state data is excluded.

   o  Explicitly set default data: Data that is explicitly set by the
      NETCONF manager to it's default value.  Some agents MIGHT treat
      explicitly set default data as default data, as they might not be



Bierman & Lengyel       Expires February 28, 2009               [Page 3]


Internet-Draft                with-defaults                  August 2008


      able to differentiate between them.

   In addition the following terms are defined in RFC 4741 and are not
   redefined here:
   o  agent
   o  application
   o  manager
   o  operation
   o  RPC
   o  RPC request
   o  RPC response


2.  With-defaults Capability

2.1.  Overview

   The :with-defaults capability indicates that the NETCONF agent makes
   it possible for the NETCONF manager to control whether default data
   is part of NETCONF rpc reply messages.  The capability only effects
   configuration data not state data.  Sending of default data is
   controlled for each individual operation separately.  The NETCONF
   agent MUST also indicate it's default behavior, whether it sends
   default data in the absence of any specific request from the NETCONF
   manager.

   This capability effects the <get>, <get-config> and <copy-config>
   operations.  Other operations that might return configuration data
   are not effected unless this is specified in the document defining
   the respective operation.

   TODO: what about model defined RPCs?  Will they be effected?  How can
   it be stated in YANG whether yes or no?

2.1.1.  Basic handling of default data

   It is not defined in [RFC4741] whether default data is part of the
   datastore/data model, or if it meta data that influences the behavior
   of the NETCONF server device but is not actually part of the
   datastore.  This document intentionally avoids deciding this
   question.  The described functionality should work in both cases.

   As a consequence of this issue basic NETCONF servers that do not
   implement the :with-defaults capability may or may not return default
   data in NETCONF rpc reply messages.






Bierman & Lengyel       Expires February 28, 2009               [Page 4]


Internet-Draft                with-defaults                  August 2008


2.2.  Dependencies

   None

2.3.  Capability Identifier

   urn:ietf:params:netconf:capability:with-defaults

   The identifier MUST have an additional parameter indicating the
   default value of with-defaults for the NETCONF agent.  The allowed
   values of with-defaults attribute can be used as a default value see
   Section 2.5.

   urn:ietf:params:netconf:capability:with-defaults?default=false

   The identifier MAY have a second parameter indicating how it treats
   explicitly set default data.  If the explicit-default parameter is
   set to "unrecognized" the agent MUST treat explicitly set default
   data as normal default data.  If the parameter is set to recognized
   this means that such data is not treated as default data.  All other
   values for the parameter or a missing parameter is handled as the
   value unrecognized.

   urn:ietf:params:netconf:capability:with-defaults?default=false&
   explicit-default=recognized

2.4.  New Operations

   None

2.5.  Modifications to Existing Operations

   A new 'with-defaults' XML attribute is used to control the generation
   of default data.  If the 'with-defaults' attribute is present in the
   <rpc> element, of the affected operations, the agent will use it's
   value to control whether default data is returned in the NETCONF rpc
   reply messages.

   Allowed values of the with-defaults attribute are:
   o  true: indicates that all default data MUST be returned.
   o  false: indicates that default data MUST NOT be returned.

   The 'with-defaults' attribute is defined in the namespace specified
   as the 'targetNamespace' in Section 4.  However, an agent should
   accept it even if no namespace is used.

   If the 'with-defaults' attribute is not present it's default value as
   specified in the capability string Section 2.3 will be used.



Bierman & Lengyel       Expires February 28, 2009               [Page 5]


Internet-Draft                with-defaults                  August 2008


   Affected operations:
   o  <get>
   o  <get-config>
   o  <copy-config>

   Index clause components are not subject to default suppression.  If
   an element within the configuration database is considered to be part
   of a key, and represents one of the naming components for a
   conceptual data structure which allows multiple named instances of an
   ancestor node, then this element is never suppressed, regardless of
   the value of the 'with-defaults' attribute.

   The following example shows a <get> operation which is using the
   'with-defaults' attribute.  The manager is retrieving the
   'interfaces' object, defined in the example.com Interfaces data
   model.  (In this simple example, the 'name' field is defined as the
   key, and the 'mtu' field is the only other data in the <interface>
   element).  The default MTU value of '1500' is not returned for the
   interface named 'Eth1' because it is set to the default value, and
   the 'with-defaults' attribute is set to 'false'.































Bierman & Lengyel       Expires February 28, 2009               [Page 6]


Internet-Draft                with-defaults                  August 2008


      <rpc message-id="102" with-defaults="false"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
        <get>
          <filter type="subtree">
            <interfaces xmlns="http://example.com/interfaces/1.2"/>
          </filter>
        </get>
      </rpc>

      <rpc-reply message-id="102" with-defaults="false"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
        <data>
          <interfaces xmlns="http://example.com/interfaces/1.2">
            <interface>
              <name>Eth0</name>
              <mtu>8192</mtu>
            </interface>
            <interface>
              <name>Eth1</name>
            </interface>
            <interface>
              <name>loopback</name>
              <mtu>8192</mtu>
            </interface>
          </interfaces>
        </data>
      </rpc-reply>


                                 Figure 1


3.  Interactions with Other Capabilities

   None


4.  Data Model XSD

   This section contains an XML Schema Definition
   [W3C.REC-xmlschema-2-20041028] which defines the XML syntax
   associated for the with-defaults XML attribute..









Bierman & Lengyel       Expires February 28, 2009               [Page 7]


Internet-Draft                with-defaults                  August 2008


   BEGIN

   <?xml version="1.0" encoding="UTF-8"?>
   <xs:schema xmlns="urn:ietf:params:xml:ns:netconf:with-defaults:1.0"
    targetNamespace="urn:ietf:params:xml:ns:netconf:with-defaults:1.0"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified"
    xml:lang="en" version="1.0" >

    <xs:annotation>
     <xs:documentation>
       Schema defining the partial-lock and unlock operations.
           organization "IETF NETCONF Working Group"
        Version: 1.0
        Contact Info: ietf@andybierman.com
                           balazs.lengyel@ericsson.com
     </xs:documentation>
    </xs:annotation>

    <xs:attribute name="with-defaults"
       type="xs:boolean"/>

    </xs:schema>

   END


                                 Figure 2


5.  IANA Considerations

   This document registers two URIs for the NETCONF XML namespace in the
   IETF XML registry [RFC3688].  Note that the capability URN is
   compliant to [RFC4741] section 10.3.

   +---------------+---------------------------------------------------+
   | Index         | Capability Identifier                             |
   +---------------+---------------------------------------------------+
   | :with-default | urn:ietf:params:netconf:capability:with-defaults: |
   | s             | 1.0                                               |
   +---------------+---------------------------------------------------+

   URI: urn:ietf:params:xml:ns:netconf:with-defaults:1.0

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.



Bierman & Lengyel       Expires February 28, 2009               [Page 8]


Internet-Draft                with-defaults                  August 2008


6.  Security Considerations

   This document defines a minor extension to existing NETCONF protocol
   operations. it does not introduce any new or increased security risks
   into the management system.

   The 'with-defaults' capability provides manager controls over the
   retrieval of particular types of XML data from a configuration
   database.  They only suppress data that can already be retrieved with
   the standard protocol operations, and do not add any data to the
   configuration database.








































Bierman & Lengyel       Expires February 28, 2009               [Page 9]


Internet-Draft                with-defaults                  August 2008


7.  Open Issues

7.1.  Augmenting the base RPCs

   Instead of using an attribute on the RPC element we could "augment"
   the relevant NETCONF operations with an extra XML element with a
   similar meaning.

   Pro: parameters on RPC are for vendor extensions.  We should not put
   standard stuff there.

   Contra: Some people might consider this a violation of [RFC4741] as
   the XSD does not allow adding new elements.  As there is no NETCONF
   YAM (at least not yet), what do we actually augment?  Also there are
   multiple ways of defining RFC4741 in YANG.  The description will be
   perfectly clear, but it can never be fed into YANG tools.

   Conclusion: While augmenting has a certain elegance, we should stick
   to the attribute based solution.

7.2.  Third option: Trim

   This is another can o' worms.  I preserve user specified values even
   when the value matches the default.  This allows users complete
   control over what appears in their config.  Values to not disappear
   simply because the match the default.

   If you want this behavior, I'd suggest making your "with-defaults" a
   tri-state value:


      "all" -- report all default values

      "trim" -- do not report values if they match the default

      "explicit" -- report any values explicitly set

   Do we need the trim option ?

7.3.  List affected operations or generalize

   Should we list affected operations <get>, <get-config>, <copy-config>
   or should we just say "any of the protocol operations which return
   the contents of a configuration database", or should we do both?







Bierman & Lengyel       Expires February 28, 2009              [Page 10]


Internet-Draft                with-defaults                  August 2008


8.  Normative References

   [W3C.REC-xmlschema-2-20041028]
              Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
              Second Edition", World Wide Web Consortium
              Recommendation REC-xmlschema-2-20041028, October 2004,
              <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

   [RFC4741]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
              December 2006.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.



































Bierman & Lengyel       Expires February 28, 2009              [Page 11]


Internet-Draft                with-defaults                  August 2008


Authors' Addresses

   Andy Bierman
   netconfcentral.org
   Simi Valley, CA
   USA

   Email: ietf@andybierman.com


   Balazs Lengyel
   Ericsson
   Hungary

   Email: balazs.lengyel@ericsson.com




































Bierman & Lengyel       Expires February 28, 2009              [Page 12]


Internet-Draft                with-defaults                  August 2008


Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.


Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).





Bierman & Lengyel       Expires February 28, 2009              [Page 13]