With System Capability for NETCONF

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 https://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 6 May 2021.¶

Copyright Notice

Copyright (c) 2020 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

Table of Contents

1. Introduction

The NETCONF protocol [RFC6241] defines ways to read configuration and state data from a NETCONF server.¶

In some cases, a client-configured data item refers to a nonexistent system generated data item (e.g.,the auto-create interfaces ("eth1") is not yet present).¶

• In many situations, the system configured data item doesn't need to be known to the client and client-configured data item will automatically be removed from the operational state datastore and thus only appear in the intended datastore if client-configured data item doesn't exist.¶
• In other situations system configured data item needs to be known and overriden by the client. Without system configuration datastore, the duplicated system configured data item in the system configuration need to be created and overriden by the client each time there is a system configured data item being referenced.¶

Therefore not all server implementations treat the system configuration data in the same way.¶

This document defines a capability-based extension to the NETCONF protocol that allows the NETCONF client to identify how system configuration are processed by the server, and also defines new mechanism for client control of server processing of system configuration data.¶

3. System Configuration data handling Basic Modes

Not all server implementations treat system configuration data in the same way. Instead of forcing a single implementation strategy, this document allows a server to advertise a particular style of system configuration data handling, and the client can adjust accordingly.¶

NETCONF servers report system configuration data in different ways. This document specifies two standard defaults handling basic modes that a server implementor may choose from:¶

• report-all¶
• explicit¶

A server that uses the 'report-all' basic mode MUST automatically¶

• Update <running> with the system configuration, after the "system" configuration has been altered as a consequence of a plug and play operation or device powering on operation. However the configurations in <running> can not be removed automatically when configuration data nodes in <system> is deleted since those configurations in <running> are likely to have already been modified or referenced.¶
• The system configuration doesn't need to be explicitly set by the client first before the system configuration needs to be updated with client set configuration or referenced by client set configuration.¶

A server that uses the 'explicit' basic mode¶

• MUST not update <running> with the system configuration,¶
• The system configuration MUST be explicitly set by the client first before the system configuration needs to be updated with client set configuration or referenced by client set configuration.¶

6. YANG Module for the <with-system> Parameter

The following YANG module defines the addition of the with-system element to the <get>, <get-config>, and <copy-config> operations. The YANG language is defined in [RFC6020]. The above operations are defined in YANG in [RFC6241]. Every NETCONF server which supports the :with-system capability MUST implement this YANG module.¶

<CODE BEGINS> file="ietf-netconf-with-system@2019-12-31.yang"
 module ietf-netconf-with-system {
    namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-system";
    prefix ncws;
    import ietf-netconf { prefix nc; }

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

    contact
     "WG Web:   <http://tools.ietf.org/wg/netconf/>
      WG List:  <mailto:netconf@ietf.org>
      WG Chair:
      Editor:
                                                 ";
    description
     "This module defines an extension to the NETCONF protocol
      that allows the NETCONF client to control how system configuration
      data are handled by the server in particular NETCONF operations.

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

      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 2019-12-31 {
      description
        "Initial version.";
      reference
       "RFC XXXX: With-system capability for NETCONF";
    }

    typedef with-system-mode {
       description
         "Possible modes to report system configuration data.";
       reference
          "RFC XXXX; section 3.";
          // RFC Ed.: replace XXXX with actual
          // RFC number and remove this note

       type enumeration {
          enum report-all {
              description
                "All system configuration data is reported.";
              reference
                "RFC XXXX; section 3.1";
                // RFC Ed.: replace XXXX with actual
                // RFC number and remove this note

          }
          enum report-all-tagged {
              description
                "All system configuration data is reported.
                 Any nodes considered to be system configuration
                 data will contain a 'origin' XML attribute,
                 set to 'system'.";
              reference
                "RFC XXXX; section 3.4";
                // RFC Ed.: replace XXXX with actual
                // RFC number and remove this note
          }
          enum trim {
              description
                "Values are not reported if they contain the system
                configuration data.";
              reference
                "RFC XXXX; section 3.2";
                // RFC Ed.: replace XXXX with actual
                // RFC number and remove this note

          }
          enum explicit {
              description
                "Report values that contain the definition of
                 explicitly set data.";
              reference
                "RFC XXXX; section 3.3";
                // RFC Ed.: replace XXXX with actual
                // RFC number and remove this note
          }
      }
    }

    grouping with-system-parameters {
      description
        "Contains the <with-system> parameter for control
         of system configuration data in NETCONF retrieval
         operations.";

      leaf with-system {
        description
          "The explicit system configuration data processing
           mode requested.";
        reference
          "RFC XXXX; section 4.6.1";
          // RFC Ed.: replace XXXX with actual
          // RFC number and remove this note

        type with-system-mode;
      }
    }

    // extending the get-config operation
    augment /nc:get-config/nc:input {
        description
          "Adds the <with-system> parameter to the
           input of the NETCONF <get-config> operation.";
        reference
          "RFC XXXX; section 4.6.1";
          // RFC Ed.: replace XXXX with actual
          // RFC number and remove this note

        uses with-system-parameters;
    }

    // extending the get operation
    augment /nc:get/nc:input {
        description
          "Adds the <with-system> parameter to
           the input of the NETCONF <get> operation.";
        reference
          "RFC XXXX; section 4.6.1";
          // RFC Ed.: replace XXXX with actual
          // RFC number and remove this note

        uses with-system-parameters;
    }
 }

<CODE ENDS>

7. IANA Considerations

This document registers the following capability identifier URN in the 'Network Configuration Protocol Capability URNs registry':¶

urn:ietf:params:netconf:capability:with-system:1.0

This document registers two XML namespace URNs in the 'IETF XML registry', following the format defined in [RFC3688].¶

      URI: urn:ietf:params:xml:ns:netconf:system:1.0
      URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system

   Registrant Contact: The NETCONF WG of the IETF.

   XML: N/A, the requested URIs are XML namespaces.

This document registers one module name in the 'YANG Module Names' registry, defined in [RFC6020] .¶

      name: ietf-netconf-with-system
      prefix: ncws
      namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system
      RFC: XXXX // RFC Ed.: replace XXXX and remove this comment

8. Acknowledgements

Authors' Addresses