--- 1/draft-ietf-netmod-nmda-diff-02.txt 2019-11-04 16:14:21.241190129 -0800 +++ 2/draft-ietf-netmod-nmda-diff-03.txt 2019-11-04 16:14:21.277191043 -0800 @@ -1,22 +1,22 @@ Network Working Group A. Clemm Internet-Draft Y. Qu Intended status: Standards Track Futurewei -Expires: January 9, 2020 J. Tantsura +Expires: May 7, 2020 J. Tantsura Apstra A. Bierman YumaWorks - July 8, 2019 + November 4, 2019 Comparison of NMDA datastores - draft-ietf-netmod-nmda-diff-02 + draft-ietf-netmod-nmda-diff-03 Abstract This document defines an RPC operation to compare management datastores that comply with the NMDA architecture. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. @@ -24,21 +24,21 @@ 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 January 9, 2020. + This Internet-Draft will expire on May 7, 2020. Copyright Notice Copyright (c) 2019 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 @@ -47,23 +47,23 @@ 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 3 4. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 4 - 5. YANG Data Model . . . . . . . . . . . . . . . . . . . . . . . 5 + 5. YANG Data Model . . . . . . . . . . . . . . . . . . . . . . . 6 6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 7. Performance Considerations . . . . . . . . . . . . . . . . . 12 8. Possible Future Extensions . . . . . . . . . . . . . . . . . 13 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 9.1. Updates to the IETF XML Registry . . . . . . . . . . . . 13 9.2. Updates to the YANG Module Names Registry . . . . . . . . 14 10. Security Considerations . . . . . . . . . . . . . . . . . . . 14 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 12.1. Normative References . . . . . . . . . . . . . . . . . . 15 12.2. Informative References . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 @@ -173,28 +173,32 @@ nodes that exist in only one of the datastores. When this parameter is not included, a prefiltering step is automatically applied to exclude data from the comparison that does not pertain to both datastores: if the same schema node is not present in both datastores, then all instances of that schema node and all its descendants are excluded from the comparison. This allows client applications to focus on the differences that constitute true mismatches of instance data without needing to specify more complex filter constructs. + o exclude-origin: When set, this parameter indicates that origin + metadata should not not be included as part of RPC output. When + this parameter is omitted, origin metadata in comparisons that + involve is by default included. + The operation provides the following output parameter: o differences: This parameter contains the list of differences. Those differences are encoded per YANG-Patch data model defined in RFC8072. The YANG-Patch data model is augmented to indicate the value of source datastore nodes in addition to the patch itself that would need to be applied to the source to produce the target. - When the target datastore is , "origin" metadata is included as part of the patch. Including origin metadata can help in some cases explain the cause of a difference, for example when a data node is part of but the origin of the same data node in is reported as "system". The data model is defined in the ietf-nmda-compare YANG module. Its structure is shown in the following figure. The notation syntax follows [RFC8340]. @@ -198,20 +202,21 @@ structure is shown in the following figure. The notation syntax follows [RFC8340]. module: ietf-nmda-compare rpcs: +---x compare +---w input | +---w source identityref | +---w target identityref | +---w all? empty + | +---w exclude-origin? empty | +---w (filter-spec)? | +--:(subtree-filter) | | +---w subtree-filter? | +--:(xpath-filter) | +---w xpath-filter? yang:xpath1.0 {nc:xpath}? +--ro output +--ro (compare-response)? +--:(no-matches) | +--ro no-matches? empty +--:(differences) @@ -225,21 +230,21 @@ +--ro target target-resource-offset +--ro point? target-resource-offset +--ro where? enumeration +--ro value? +--ro source-value? Structure of ietf-nmda-compare 5. YANG Data Model - file "ietf-nmda-compare@2019-07-08.yang" + file "ietf-nmda-compare@2019-11-04.yang" module ietf-nmda-compare { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-nmda-compare"; prefix cp; import ietf-yang-types { prefix yang; } @@ -265,23 +270,42 @@ Author: Jeff Tantsura Author: Andy Bierman "; description "The YANG data model defines a new operation, , that - can be used to compare NMDA datastores."; + can be used to compare NMDA datastores. - revision 2019-07-08 { + 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 (RFC 2119) (RFC 8174) when, and only when, + they appear in all capitals, as shown here. + + Copyright (c) 2019 IETF Trust and the persons identified as + authors of the code. 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 + (https://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC XXXX; see the + RFC itself for full legal notices."; + + revision 2019-11-04 { description "Initial revision"; reference "RFC XXXX: Comparison of NMDA datastores"; } /* RPC */ rpc compare { description "NMDA compare operation."; @@ -308,20 +332,28 @@ "When this leaf is provided, all data nodes are compared, whether their schema node pertains to both datastores or not. When this leaf is omitted, a prefiltering step is automatically applied that excludes data nodes from the comparison that can occur in only one datastore but not the other. Specifically, if one of the datastores (source or target) contains only configuration data and the other datastore is , data nodes for which config is false are excluded from the comparison."; } + leaf exclude-origin { + type empty; + description + "When this leaf is provided, origin metadata is not + included as part of RPC output. When this leaf is + omitted, origin metadata in comparisons that involve + is by default included."; + } choice filter-spec { description "Identifies the portions of the datastores to be compared."; anydata subtree-filter { description "This parameter identifies the portions of the target datastore to retrieve."; reference "RFC 6241, Section 6."; } @@ -521,31 +551,32 @@ "@ietf-ospf:preference" : { "ietf-origin:origin" : "ietf-origin:system" } } ] } } } } -7. Open Issues - - Currently, origin metadata is included in RPC output per default in - comparisons that involve . It is conceivable to - introduce an input parameter that controls whether this origin - metadata should in fact be included. +7. Performance Considerations - Currently the comparison filter is defined using subtree and XPath as - in NETCONF[RFC6241]. It is not clear whether there is a requirement - to allow for the definition of filters that relate instead to target - resources per RESTCONF [RFC7950]. + The compare operation can be computationally expensive. While + responsible client applications are expected to use the operation + responsibly and sparingly only when warranted, implementations need + to be aware of the fact that excessive invocation of this operation + will burden system resources and need to ensure that system + performance will not be adversely impacted. One possibility for an + implementation to mitigate against such a possibility is to limit the + number of requests that is served to a client in any one time + interval, rejecting requests made at a higher frequency than the + implementation can reasonably sustain. 8. Possible Future Extensions It is conceivable to extend the compare operation with a number of possible additional features in the future. Specifically, it is possible to define an extension with an optional feature for dampening. This will allow clients to specify a minimum time period for which a difference must persist for it to be reported. This will enable clients to distinguish between @@ -621,22 +652,22 @@ ways. For one, they can implement the NETCONF access control model in order to require proper authorization for requests to be made. Second, server implementations can limit the number of requests that they serve to a client in any one time interval, rejecting requests made at a higher frequency than the implementation can reasonably sustain. 11. Acknowledgments We thank Rob Wilton, Martin Bjorklund, Mahesh Jethanandani, Lou - Berger, Kent Watsen, Phil Shafer, Ladislav Lhotka for valuable - feedback and suggestions. + Berger, Kent Watsen, Phil Shafer, Ladislav Lhotka, and Tim Carey for + valuable feedback and suggestions. 12. References 12.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . @@ -685,21 +716,21 @@ [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . 12.2. Informative References [I-D.ietf-ospf-yang] Yeung, D., Qu, Y., Zhang, Z., Chen, I., and A. Lindem, "YANG Data Model for OSPF Protocol", draft-ietf-ospf- - yang-23 (work in progress), July 2019. + yang-29 (work in progress), October 2019. Authors' Addresses Alexander Clemm Futurewei 2330 Central Expressway Santa Clara, CA 95050 USA Email: ludwig@clemm.org