NETCONF Working Group K. Watsen Internet-Draft Watsen Network Intended status: Standards Track Q. Wu Expires: May 6, 2021 Huawei O. Hagsand Netgate H. Li HPE November 2, 2020 NETCONF Extensions to Support List Pagination draft-wwlh-netconf-list-pagination-nc-01 Abstract In some circumstance, a server may contain many instances of a particular YANG list or leaf-list. Retrieval of the entire list or leaf-list at once can be extremely inefficient. This document defines a YANG data model with "get-pageable-list" RPC to allow a client to iterate through a large list, in a manner that is most efficient for the application. The YANG data model in this document conforms to the Network Management Datastore Architecture defined in RFC 8342. 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 May 6, 2021. Watsen, et al. Expires May 6, 2021 [Page 1] Internet-Draft NETCONF Pagination Support November 2020 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. NETCONF operation . . . . . . . . . . . . . . . . . . . . . . 4 2.1. The operation . . . . . . . . . . . 4 3. YANG Module for List Pagination . . . . . . . . . . . . . . . 6 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 4.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 13 4.2. The "YANG Module Names" Registry . . . . . . . . . . . . 13 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 5.1. The "ietf-netconf-list-pagination" YANG Module . . . . . 14 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.1. Normative References . . . . . . . . . . . . . . . . . . 14 6.2. Informative References . . . . . . . . . . . . . . . . . 15 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 16 Appendix B. Example YANG Module . . . . . . . . . . . . . . . . 16 B.1. "example-module" YANG Module . . . . . . . . . . . . . . 17 B.2. Data-Set for example-module . . . . . . . . . . . . . . . 23 Appendix C. NETCONF YANG Collection Examples . . . . . . . . . . 27 C.1. "count" Parameter . . . . . . . . . . . . . . . . . . . . 28 C.2. "skip" Parameter . . . . . . . . . . . . . . . . . . . . 28 C.3. "direction" Parameter . . . . . . . . . . . . . . . . . . 29 C.4. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 30 C.5. Combination of "where" and "count" Parameters . . . . . . 31 C.6. Combination of "where", "count" and "skip" Parameters . . 32 C.7. Combination of "where", "count","skip" and "sort" Parameters . . . . . . . . . . . . . . . . . . . . . . . 33 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 Watsen, et al. Expires May 6, 2021 [Page 2] Internet-Draft NETCONF Pagination Support November 2020 1. Introduction There is a need for standard mechanisms to control the filtering, sorting, and retrieval of data from the server. A server may contain many instances of a particular YANG list. Retrieval of the entire list or leaf-list at once can be extremely inefficient. This document defines a YANG module for Pagination mechanisms which allow a client to iterate through a large list or leaf-list, in a manner that is most efficient for the application. While the pagination mechanism defined in this document is designed for the NETCONF protocol [RFC6241], the RPC MAY be used by the RESTCONF protocol [RFC8040] if the RESTCONF server implements the "ietf-yang-list-pagination" module. The YANG data model in this document conforms to the Network Management Datastore Architecture defined in [RFC8342] 1.1. Terminology 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] [RFC8174] when, and only when, they appear in all capitals, as shown here. The following terms are defined in [RFC8342] [RFC7950] and are not redefined here: o server o startup configuration datastore o candidate configuration datastore o running configuration datastore o intended configuration datastore o operational state datastore o conventional configuration datastore o datastore schema o RPC operation Watsen, et al. Expires May 6, 2021 [Page 3] Internet-Draft NETCONF Pagination Support November 2020 The following terms are defined in this document as follows: 2. NETCONF operation This document define a new operation -- to support YANG based pagination. This operation is similar to the [RFC8526] in that it takes an input parameter to indicate the datastore that is the source of the data to be retrieved. 2.1. The operation The operation uses enhanced filtering features to retrieve data from a specific NMDA datastore. This operation is similar to operation defined in [RFC8526] and have the flexibility to select the different source datastore. +---x get-pageable-list +---w input | +---w datastore? string | +---w (filter-spec)? | | +--:(subtree-filter) | | | +---w subtree-filter? | | +--:(xpath-filter) | | +---w xpath-filter? yang:xpath1.0 {nc:xpath}? | +---w config-filter? boolean | +---w (origin-filters)? {origin}? | | +--:(origin-filter) | | | +---w origin-filter* or:origin-ref | | +--:(negated-origin-filter) | | +---w negated-origin-filter* or:origin-ref | +---w max-depth? union | +---w with-origin? empty {origin}? | +---w with-defaults? with-defaults-mode | +---w list-target string | +---w count? union | +---w skip? union | +---w direction? enumeration | +---w sort? string | +---w where? string +--ro output +--ro collection? The "datastore" parameter indicates the datastore that is the source of the data to be retrieved. This is a "datastore" identity. The operation accepts a content filter parameter, similar to the "filter" parameter of , but uses explicit nodes for list filtering or leaf-list filtering. Watsen, et al. Expires May 6, 2021 [Page 4] Internet-Draft NETCONF Pagination Support November 2020 The "config-filter" parameter can be used to retrieve only "config true" or "config false" nodes. The "origin-filter" parameter, which can be present multiple times, selects nodes equal to or derived from any of the given values. The "negated-origin-filter", which can be present multiple times, selects nodes that are not equal to or derived from any of the given values. The "origin-filter" and "negated-origin-filter" parameters cannot be used together. The "max-depth" parameter can be used by the client to limit the number of subtree levels that are returned in the reply. The "with-origin" parameter can be used to request the server to include "origin" metadata annotations in its response, as detailed in the NMDA. The 'with-origin' parameter is only valid for an operational datastore. See section 3.1.1.1 of [RFC8526] for the behavior of the "with-origin" parameter for . The "with-default"parameter can be used to control whether default data is returned by the server. The 'with-default' parameter is only valid for an operational datastore. See section 3.1.1.2 of [RFC8526] for the behavior of the "with-defaults" parameter for . The "list-target" parameter is used to specify that YANG list that will be retrieved. This must be a path expression used to represent a list data node. The "count" parameter can be used to specify the maximum number of list entries to return. The value of the "count" parameter is either an integer greater than or equal to 1, or the string "unbounded". The string "unbounded" is the default value. The "skip" parameter can be used to specify the first list item to return in response to NETCONF/Request requests on instances of a particular YANG list. YANG list instances are numbered with consecutive integers from 1 to the number of YANG list instances. The value of the "skip" parameter is an integer greater than or equal to 1. The default value is 1. If the "where" parameter is specified, the "skip" parameter MUST start with a set of selected list resources picked by using "where" parameter and specify the first list item resource to return. The "direction" parameter can be used to specify the direction relative to the 'sort' order through list or leaf-list. Watsen, et al. Expires May 6, 2021 [Page 5] Internet-Draft NETCONF Pagination Support November 2020 The "sort" parameter is used to indicates how the entries in a list are to be sorted. By default, the value of the "sort" is default, i.e., for 'ordered-by user' lists and leaf-lists, the default order is the user-configured order; for 'ordered-by system' lists and leaf- lists, the default order is specified by the system. The "where" parameter is used to specify the boolean filter to select data instances to return from the list or leaf-list target. The filter element contains boolean XPATH expression. The filter output is a set of selected list items. The server determines which node instances are included (or potentially included) in the filter output, and which node instances are excluded (pruned) from the filter output. The selected list instances are numbered with consecutive integers from 1 to the number of list instances. The expected processing order: filter -> sort -> direction -> skip -> count. 3. YANG Module for List Pagination The "ietf-netconf-list-pagination" module defines conceptual definitions within groupings, which are not meant to be implemented as datastore contents by a server. This module has normative references to [RFC6241], [RFC6243], [RFC6991], and [RFC8342]. file "ietf-netconf-list-pagination@2020-10-30.yang" module ietf-netconf-list-pagination { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination"; prefix ycoll; import ietf-netconf { prefix nc; reference "RFC 6241: Network Configuration Protocol (NETCONF)"; } import ietf-netconf-with-defaults { prefix ncwd; reference "RFC 6243: With-defaults Capability for NETCONF"; } import ietf-yang-types { prefix yang; reference Watsen, et al. Expires May 6, 2021 [Page 6] Internet-Draft NETCONF Pagination Support November 2020 "RFC 6991: Common YANG Data Types"; } import ietf-datastores { prefix ds; reference "RFC 8342: Network Management Datastore Architecture (NMDA)"; } import ietf-origin { prefix or; reference "RFC 8342: Network Management Datastore Architecture (NMDA)"; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: WG List: Editor: Editor: Editor: "; description "This module define a new operation -- to support YANG based pagination. 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 8526; see the RFC itself for full legal notices."; Watsen, et al. Expires May 6, 2021 [Page 7] Internet-Draft NETCONF Pagination Support November 2020 revision 2020-10-30 { description "Initial revision."; reference "RFC XXXX: YANG Based Pagination."; } feature origin { description "Indicates that the server supports the 'origin' annotation."; reference "RFC 8342: Network Management Datastore Architecture (NMDA)"; } feature with-defaults { description "NETCONF :with-defaults capability. If the server advertises the :with-defaults capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC 6243: With-defaults Capability for NETCONF, Section 4; and RFC 8526: NETCONF Extensions to Support the Network Management Datastore Architecture, Section 3.1.1.2"; } rpc get-pagable-list { description "Use enhanced filtering features to retrieve data from a specific NMDA datastore. The content returned by get-data must satisfy all filters, i.e., the filter criteria are logically ANDed. Any ancestor nodes (including list keys) of nodes selected by the filters are included in the response. The 'with-origin' parameter is only valid for an operational datastore. If 'with-origin' is used with an invalid datastore, then the server MUST return an element with an value of 'invalid-value'. The 'with-defaults' parameter only applies to the operational datastore if the NETCONF :with-defaults and :with-operational-defaults capabilities are both advertised. If the 'with-defaults' parameter is present in a request for which it is not supported, then the server MUST return an element with an value of 'invalid-value'."; Watsen, et al. Expires May 6, 2021 [Page 8] Internet-Draft NETCONF Pagination Support November 2020 input { leaf datastore { type ds:datastore-ref; mandatory true; description "Datastore from which to retrieve data. If the datastore is not supported by the server, then the server MUST return an element with an value of 'invalid-value'."; } choice filter-spec { description "The content filter specification for this request."; anydata subtree-filter { description "This parameter identifies the portions of the target datastore to retrieve."; reference "RFC 6241: Network Configuration Protocol (NETCONF), Section 6"; } leaf xpath-filter { if-feature "nc:xpath"; type yang:xpath1.0; description "This parameter contains an XPath expression identifying the portions of the target datastore to retrieve. If the expression returns a node-set, all nodes in the node-set are selected by the filter. Otherwise, if the expression does not return a node-set, then the operation fails. The expression is evaluated in the following XPath context: o The set of namespace declarations are those in scope on the 'xpath-filter' leaf element. o The set of variable bindings is empty. o The function library is the core function library, and the XPath functions are defined in Section 10 of RFC 7950. o The context node is the root node of the target datastore."; Watsen, et al. Expires May 6, 2021 [Page 9] Internet-Draft NETCONF Pagination Support November 2020 } } leaf config-filter { type boolean; description "Filter for nodes with the given value for their 'config' property. When this leaf is set to 'true', only 'config true' nodes are selected, and when set to 'false', only 'config false' nodes are selected. If this leaf is not present, no nodes are filtered."; } choice origin-filters { when 'derived-from-or-self(datastore, "ds:operational")'; if-feature "origin"; description "Filters configuration nodes based on the 'origin' annotation. Configuration nodes that do not have an 'origin' annotation are treated as if they have the 'origin' annotation 'or:unknown'. System state nodes are not affected by origin-filters and thus not filtered. Note that system state nodes can be filtered with the 'config-filter' leaf."; leaf-list origin-filter { type or:origin-ref; description "Filter based on the 'origin' annotation. A configuration node matches the filter if its 'origin' annotation is derived from or equal to any of the given filter values."; } leaf-list negated-origin-filter { type or:origin-ref; description "Filter based on the 'origin' annotation. A configuration node matches the filter if its 'origin' annotation is neither derived from nor equal to any of the given filter values."; } } leaf max-depth { type union { type uint16 { range "1..65535"; } type enumeration { enum unbounded { description Watsen, et al. Expires May 6, 2021 [Page 10] Internet-Draft NETCONF Pagination Support November 2020 "All descendant nodes are included."; } } } default "unbounded"; description "For each node selected by the filters, this parameter selects how many conceptual subtree levels should be returned in the reply. If the depth is 1, the reply includes just the selected nodes but no children. If the depth is 'unbounded', all descendant nodes are included."; } leaf with-origin { when 'derived-from-or-self(../datastore, "ds:operational")'; if-feature "origin"; type empty; description "If this parameter is present, the server will return the 'origin' annotation for the nodes that have one."; } uses ncwd:with-defaults-parameters { if-feature "with-defaults"; } leaf list-target { description "Identifies the list object that is being retrieved. This must be a path expression used to represent a list data node or leaf-list data node. "; mandatory true; type string; } leaf count { type union { type uint32; type string { pattern 'unbounded'; } } default "unbounded"; description "The maximum number of list entries to return. The value of the 'count' parameter is either an integer greater than or equal to 1, or the string 'unbounded'. The string 'unbounded' is the default value."; } leaf skip { type union { type uint32; Watsen, et al. Expires May 6, 2021 [Page 11] Internet-Draft NETCONF Pagination Support November 2020 type string { pattern 'none'; } } default "none"; description "The first list item to return. the 'skip' parameter is either an integer greater than or equal to 1, or the string 'unbounded'. The string 'unbounded' is the default value."; } leaf direction { type enumeration { enum forward; enum reverse; } default "forward"; description "Direction relative to the 'sort' order through list or leaf-list. It can be forward direction or reverse direction."; } leaf sort { type union { type string { length "1..max" { description "The name of a descendent node to sort on. For 'Config false' lists and leaf-lists, the node SHOULD have the 'TBD' extension indicating that it has been indexed, enabling efficient sorts."; } } type enumeration { enum default { description "Indicates that the 'default' order is assumed. For 'ordered-by user' lists and leaf-lists, the default order is the user-configured order. For 'ordered-by system' lists and leaf-lists, the default order is specified by the system."; } } } default "default"; description "Indicates how the entries in a list are to be sorted."; } Watsen, et al. Expires May 6, 2021 [Page 12] Internet-Draft NETCONF Pagination Support November 2020 leaf where { type yang:xpath1.0; description "The boolean filter to select data instances to return from the list or leaf-list target. The Xpath expression MAY be constrained either server-wide, by datastore, by 'config' status, or per list or leaf-list. Details regarding how constraints are communicated are TBD. This parameter is optional; no filtering is applied when it is not specified."; } } output { anyxml pageable-list { description "Return the list entries that were requested and matched the filter criteria (if any). An empty data container indicates that the request did not produce any results."; } } } } 4. IANA Considerations 4.1. The "IETF XML" Registry This document registers one URI in the "ns" subregistry of the IETF XML Registry [RFC3688] maintained at . Following the format in [RFC3688], the following registration is requested: URI: urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. 4.2. The "YANG Module Names" Registry This document registers one YANG module in the YANG Module Names registry [RFC6020] maintained at . Following the format defined in [RFC6020], the below registration is requested: Watsen, et al. Expires May 6, 2021 [Page 13] Internet-Draft NETCONF Pagination Support November 2020 name: ietf-restconf-list-pagination namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-list-pagination prefix: rlpg RFC: xxxx 5. Security Considerations 5.1. The "ietf-netconf-list-pagination" YANG Module The YANG module defined in this document extends the base operations for NETCONF [RFC6241] and RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446]. The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF users to a preconfigured subset of all available NETCONF protocol operations and content. The security considerations for the base NETCONF protocol operations (see Section 9 of [RFC6241] apply to the new RPC operations defined in this document. 6. References 6.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, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [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, . Watsen, et al. Expires May 6, 2021 [Page 14] Internet-Draft NETCONF Pagination Support November 2020 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, . [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, . [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, . 6.2. Informative References [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "NETCONF Extensions to Support the Network Management Datastore Architecture", RFC 8526, DOI 10.17487/RFC8526, March 2019, . Watsen, et al. Expires May 6, 2021 [Page 15] Internet-Draft NETCONF Pagination Support November 2020 Appendix A. Open Issues Cursors (i.e.,stable result sets) are related to the topic of dynamic changing lists between two queries. How cursors can be supported using "feature"? Appendix B. Example YANG Module The example YANG module used in this document is supposed to illustrate certain features and not supposed to be complete, valid YANG modules. YANG tree diagram for the "example-module" module: Watsen, et al. Expires May 6, 2021 [Page 16] Internet-Draft NETCONF Pagination Support November 2020 module: example-module +--rw admins | +--rw admin* [name] | +--rw name string | +--rw access? enumeration | +--rw email-address? email-address | +--rw password? ianach:crypt-hash | +--ro status* string | +--rw preference | | +--rw number* uint8 | +--rw skill* [name] | +--rw name string | +--rw rank? uint8 +--rw rulebase | +--rw rule* [name] | +--rw name string | +--rw match? string | +--rw action? enumeration +--rw device-logs | +--ro device-log* [] | +--ro device-id? string | +--ro time-received? yang:timestamp | +--ro time-generated? yang:timestamp | +--ro message? string +--rw audit-logs | +--ro audit-log* [log-creation] | +--ro source-ip? inet:ip-address | +--ro log-creation? yang:timestamp | +--ro request? string | +--ro outcome? boolean +--rw prefixes +--rw prefix-list* [ip-prefix masklength-lower masklength-upper] +--rw ip-prefix inet:ip-prefix +--rw masklength-lower uint8 +--rw masklength-upper uint8 B.1. "example-module" YANG Module module example-module { yang-version 1.1; namespace "http://example.com/ns/example-module"; prefix exm; import iana-crypt-hash { prefix ianach; } import ietf-inet-types { prefix inet; Watsen, et al. Expires May 6, 2021 [Page 17] Internet-Draft NETCONF Pagination Support November 2020 } import ietf-yang-types { prefix yang; } organization "Example, Inc."; contact "support at example.com"; description "Example Data Model Module."; revision 2020-10-06 { description "Initial version."; reference "example.com document 1-4673."; } container admins { description "Admin Group configuration."; list admin { key "name"; description "List of admins for admin group configuration."; ordered-by system; leaf name { type string { length "1 .. max"; } description "The name of the admin."; } leaf access { type enumeration { enum permit { description "Permit access privilege."; } enum deny { description "Deny access privilege."; } enum limited { description "Limited access privilege."; } Watsen, et al. Expires May 6, 2021 [Page 18] Internet-Draft NETCONF Pagination Support November 2020 } default "permit"; description "The Access privilege type for this admin."; } leaf email-address { type inet:email-address; description "Contact email of the admin."; } leaf password { type ianach:crypt-hash; description "The password for this entry."; } leaf-list status { type string; config false; description "The status for this entry."; } container preference { leaf-list number { type uint8; description "Defines the perference numbers for the admin."; } description "Preference parameters."; } list skill { key "name"; description "Represents one 'sill' resource within one 'admin' resource."; leaf name { type string { length "1 .. max"; } description "The name of the skill."; } leaf rank { type uint16; description "The rank identifying the rank on the skill."; } Watsen, et al. Expires May 6, 2021 [Page 19] Internet-Draft NETCONF Pagination Support November 2020 } } } container rulebase { description "Rule base configuration"; list rule { key "name"; description "List of rules for rulebase."; ordered-by user; leaf name { type string { length "1 .. max"; } description "The name of the rule."; } leaf match { type string { length "1 .. max"; } description "The rules in this rulebase determine what fields will be matched upon before any action is taken on them."; } leaf action { type enumeration { enum forwarding { description "Specify forwarding behavior per rule entry."; } enum logging { description "Specify logging behavior per rule entry."; } } default "logging"; description "Defintion of the action for this rule entry."; } } } container device-logs { description "Device log configuration"; list device-log { description Watsen, et al. Expires May 6, 2021 [Page 20] Internet-Draft NETCONF Pagination Support November 2020 "List of device logs."; config false; leaf device-id { type string; description "The device id of the device log."; } leaf time-received { type yang:date-and-time; description "The timestamp value at the time this log was received."; } leaf time-generated { type yang:date-and-time; description "The timestamp value at the time this log was generated."; } leaf message { type string; description "Message given at start of login session."; } } } container audit-logs { description "Audit log configuration"; list audit-log { key "log-creation"; description "List of audit logs."; config false; leaf source-ip { type inet:ip-address; description "The IP address of the targeted object."; } leaf log-creation { type yang:date-and-time; description "The timestamp value at the time this log was created."; } leaf request { type string; description Watsen, et al. Expires May 6, 2021 [Page 21] Internet-Draft NETCONF Pagination Support November 2020 "Request type of audit log."; } leaf outcome { type boolean; default "true"; description "Indicate the audit log is retrieved sucessfully or not."; } } } container prefixes { description "Enclosing container for the list of prefixes in a policy prefix list"; list prefix-list { key "ip-prefix masklength-lower masklength-upper"; description "List of prefixes in the prefix set"; leaf ip-prefix { type inet:ip-prefix; mandatory true; description "The prefix member in CIDR notation -- while the prefix may be either IPv4 or IPv6, most implementations require all members of the prefix set to be the same address family. Mixing address types in the same prefix set is likely to cause an error."; } leaf masklength-lower { type uint8; description "Masklength range lower bound."; } leaf masklength-upper { type uint8 { range "1..128"; } must '../masklength-upper >= ../masklength-lower' { error-message "The upper bound should not be lessthan lower bound."; } description "Masklength range upper bound. The combination of masklength-lower and masklength-upper define a range for the mask length, or single 'exact' length if masklength-lower and masklenght-upper are equal. Example: 10.3.192.0/21 through 10.3.192.0/24 would be Watsen, et al. Expires May 6, 2021 [Page 22] Internet-Draft NETCONF Pagination Support November 2020 expressed as prefix: 10.3.192.0/21, masklength-lower=21, masklength-upper=24 Example: 10.3.192.0/21 (an exact match) would be expressed as prefix: 10.3.192.0/21, masklength-lower=21, masklength-upper=21"; } } } } B.2. Data-Set for example-module Alice permit alice@example.com $0$1543 Available 1 2 Customer Service 99 Problem Solving 90 Bob limited bob@example.com $0$2789 Busy 2 3 Problem Solving 98 Watsen, et al. Expires May 6, 2021 [Page 23] Internet-Draft NETCONF Pagination Support November 2020 Conflict Resolution 93 Joe permit joe@example.com $0$6523 Do Not Disturb 1 4 Management 96 Collaboration 92 Frank deny frank@example.com $0$4030 Offline 5 9 Organization 90 Negotiation 80 Tom permit tom@example.com Watsen, et al. Expires May 6, 2021 [Page 24] Internet-Draft NETCONF Pagination Support November 2020 $0$2376 Do Not Disturb 2 5 Adaptability. 98 Active Listening 85 SvrA-http 92.0.2.0/24 forwarding SvrA-ftp 203.0.113.1/32 forwarding p2p p2p logging any any logging SvrA-tcp 80 forwarding Cloud-IoT-Device-A 2020-07-08T12:38:32Z 2020-07-08T12:37:12Z Watsen, et al. Expires May 6, 2021 [Page 25] Internet-Draft NETCONF Pagination Support November 2020 Upload contains 6 datapoints Cloud-IoT-Device-B 2020-07-08T16:20:54Z 2020-07-08T16:20:14Z Upload successful Cloud-IoT-Device-C 2020-07-08T17:30:34Z 2020-07-08T17:30:12Z Receive a configuration update Cloud-IoT-Device-D 2020-07-08T18:40:13Z 2020-07-08T18:40:00Z Keep-alive ping sent to server Cloud-IoT-Device-E 2020-07-08T19:48:34Z 2020-07-08T19:48:00Z Uploading data to DataPoint 192.168.0.92 2020-11-01T06:47:59Z User-logged-out true 192.168.0.92 2020-11-01T06:49:03Z User-logged-in true 192.168.0.92 2020-11-01T06:51:34Z Patron-card-viewed false 192.168.0.92 Watsen, et al. Expires May 6, 2021 [Page 26] Internet-Draft NETCONF Pagination Support November 2020 2020-11-01T06:53:01Z User-logged-out true 192.168.0.92 2020-11-01T06:56:22Z User-logged-in false 10.0.0.0 8 17 18 2000:1:: 48 48 2000:2:: 48 48 2000:3:: 16 16 :: 0 128 Appendix C. NETCONF YANG Collection Examples The examples within this document use the "example-module" YANG module defined in Appendix A. Watsen, et al. Expires May 6, 2021 [Page 27] Internet-Draft NETCONF Pagination Support November 2020 C.1. "count" Parameter In this example, the client requests the first two "skill" resources for a given admin resource: Request from NETCONF client running admins/admin[name=Bob]/skill 2 Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.2. "skip" Parameter In this example, the client requests the next two skills resource, i.e., two skills resource starting from two. Watsen, et al. Expires May 6, 2021 [Page 28] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 2 Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.3. "direction" Parameter In this example, the client requests the first two "skill" resources in the forward direction for a given admin: Watsen, et al. Expires May 6, 2021 [Page 29] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 forward Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.4. "sort" Parameter In this example, the client requests the first 3 "skill" resources sorted by name for a given admin: Watsen, et al. Expires May 6, 2021 [Page 30] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 name Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.5. Combination of "where" and "count" Parameters In this example, the client requests the first 2 "skill" resources from the selected skill resource list for a given admin: Watsen, et al. Expires May 6, 2021 [Page 31] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 position>=2 and position<=9 Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.6. Combination of "where", "count" and "skip" Parameters In this example, the client requests the first 2 "skill" resources from the selected "skill" resource list for a given admin: Watsen, et al. Expires May 6, 2021 [Page 32] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 2 position>=2 and position<=9 Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... C.7. Combination of "where", "count","skip" and "sort" Parameters In this example, the client requests the first 2 "skill" resources from the selected skill resources list for a given admin: Watsen, et al. Expires May 6, 2021 [Page 33] Internet-Draft NETCONF Pagination Support November 2020 Request from NETCONF client running admins/admin[name=Bob]/skill 2 2 name [position>=2 and position<=9] Response from NETCONF server Problem Solving 98 ... Conflict Resolution 93 ... Acknowledgements This work has benefited from the discussions of restconf resource collection over the years, in particular, [I-D.ietf-netconf-restconf- collection] which provides enhanced filtering features for the retrieval of data nodes with the GET method and [I-D.zheng-netconf- fragmentation] which document large size data handling challenge. The authors would like to thank the following for lively discussions on list: Andy Bierman Martin Bjoerklund Robert Varga Watsen, et al. Expires May 6, 2021 [Page 34] Internet-Draft NETCONF Pagination Support November 2020 Authors' Addresses Kent Watsen Watsen Network EMail: kent+ietf@watsen.net Qin Wu Huawei 101 Software Avenue, Yuhua District Nanjing, Jiangsu 210012 China EMail: bill.wu@huawei.com Olof Hagsand Netgate EMail: olof@hagsand.se Hongwei Li HPE EMail: flycoolman@gmail.com Watsen, et al. Expires May 6, 2021 [Page 35]