]> Cisco Systems

perander@cisco.com

Watsen Networks

kent+ietf@watsen.net

Huawei Technologies

bill.wu@huawei.com

SUNET

olof@hagsand.se

Hewlett Packard Enterprise

flycoolman@gmail.com

OPS Area NETCONF Working Group List pagination for YANG-driven protocols are defined in . Operational data can have very large data sets. These data sets can furthermore have big churn, a lot of additions or deletions to the data set. In order to support a stable pagination of such data sets, snapshots can be used. This document defines snapshot support for pagination of "config false" nodes of type "list" and "leaf-list". The snapshot support for individual nodes is signaled via the "ietf-system-capabilities" module.

Introduction The following open questions have been identified for list-pagination with snapshots. The requirements that are necessory to resolve for a complete solution:

• What should be in the snapshot? The discussions have touched on include entire list content, take a snapshot of list keys etc.
• How should a client return to a taken snapshot? I.e. one RESTCONF request starts paginating and allocates a snapshot, how does the client return to that snapshot for the next page? The snapshot would need some id and a method to fetch it later. For instance a new query parameter to identify a snapshot, and a snapshot metadata id?
• What is the lifecycle of a snapshot for pagination?
• Should the client be able to signal that the snapshot should be deallocated?
• Should it the snapshot have some timeout after which it is deallocated?
• What happens when a server can't take a snapshot due to resource constraints?
• Should snapshots be implicitly deallocated when the pagination reaches the last page?
• Security considerations for protecting against DoS when a lot of (possibly huge) snapshots can be taken.

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 when, and only when, they appear in all capitals, as shown here. The following terms are defined in and are not redefined here: client, data model, data tree, feature, extension, module, leaf, leaf-list, and server.

Conventions Various examples in this document use "BASE64VALUE=" as a placeholder value for binary data that has been base64 encoded (per ). This placeholder value is used because real base64 encoded structures are often many lines long and hence distracting to the example being presented.

Adherence to the NMDA This document is compliant with the Network Management Datastore Architecture (NMDA) . The "ietf-list-pagination-snapshot" module only defines a YANG identity, grouping, and augments a couple leafs into a "config false" node defined by the "ietf-system-capabilities" module.

Solution Overview The solution presented in this document extends the pagination functionality in . The snapshot functionality defined by the document conforms to "config false" "list" and "leaf-list" nodes. The "snapshot" query parameter (see ) enables clients to ask create a snapshot. The support for snapshots is signaled via (see ).

The "snapshot" Query Parameter

Description

The "snapshot" query parameter indicates that the client requests the server to take a snapshot of a "config false" target before starting the pagination.

Default Value

If this query parameter is unspecified, it defaults to false.

Allowed Values

The allowed values are true or false. If snapshots are not supported the "snapshot-not-supported" SHOULD be produced in the error-app-tag in the error output.

Conformance

The "snapshot" query parameter MAY be supported for "config false" lists and leaf-lists.

NETCONF For the NETCONF protocol, the "snapshot" query parameter is added to the protocol by augmenting "lpgsnap:snapshot-param-grouping" to the get, get-config, and get-data RPCs.

RESTCONF The RESTCONF protocol specific functionality and conformance is defined in this section. If the target node does not support snapshots, then a "501 Not Implemented" status-line MUST be returned with the error-type value "application" and error-tag value "invalid-value", and SHOULD also include the "snapshot-not-supported" identity as error-app-tag value. The "snapshot" query parameter is allowed for GET and HEAD methods on "list" and "leaf-list" data resources. A "400 Bad Request" status-line MUST be returned if used with any other method or resource type. The error-tag value "operation-not-supprted" is used in this case.

Snapshot support A server MAY support snapshots when paginating a "config false" list or leaf-list. In order to enable servers to identify which nodes may be used to take snapshots when paginating the "ietf-list-pagination-snapshot" module (see ) augments an empty leaf node called "snapshot" into the "per-node-capabilities" node defined in the "ietf-system-capabilities" module (see ). Note that it is possible for a client to request the server to take a snapshot when paginating with the "snapshot" query parameter (see .

The "ietf-list-pagination-snapshot" Module The "ietf-list-pagination-snapshot" module is used by servers to indicate that they support pagination on YANG "list" and "leaf-list" nodes, and to provide an ability to indicate which "config false" list and/or "leaf-list" nodes are constrained and, if so, which nodes may be used in "where" and "sort-by" expressions.

Data Model Overview The following tree diagram illustrates the "ietf-list-pagination-snapshot" module: Comments: As shown, this module augments an optional leaf into the "per-node-capabilities" list node of the "ietf-system-capabilities" module.

YANG Module This YANG module has normative references to and . <CODE BEGINS> file "ietf-list-pagination-snapshot@2024-03-01.yang" "; description "This module is used by servers to indicate they support snapshot pagination on 'config false' nodes of type 'list' and 'leaf-list'. It also defines a grouping for the snapshot parameter. Copyright (c) 2024 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 Revised 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 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself for full legal notices. 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."; revision 2024-03-01 { description "Initial revision."; reference "RFC XXXX: List Pagination Snapshots for YANG-driven Protocols"; } // Identities identity snapshot-not-supported { base lpg:list-pagination-error; description "Snapshot is not supported for the target. Either it is not a 'config false' list or leaf-list, or it is disabled."; } // Groupings grouping snapshot-param-grouping { description "This grouping may be used by protocol-specific YANG modules to define a protocol-specific query parameter."; leaf snapshot { type boolean; description "The 'snapshot' parameter indicates that the client requests the server to take a snapshot of the 'config false' list or leaf-list target before paginating."; } } // Protocol-accessible nodes augment "/nc:get/nc:input" { description "Allow the 'get' operation to use the 'snapshot' query parameter for YANG list or leaf-list that is to be retrieved."; uses snapshot-param-grouping; } augment "/nc:get-config/nc:input" { description "Allow the 'get-config' operation to use the 'snapshot' query parameter for YANG list or leaf-list that is to be retrieved."; uses snapshot-param-grouping; } augment "/ncds:get-data/ncds:input" { description "Allow the 'get-data' operation to use the 'snapshot' query parameter for YANG list or leaf-list that is to be retrieved."; uses snapshot-param-grouping; } augment "/sysc:system-capabilities/sysc:datastore-capabilities" + "/sysc:per-node-capabilities" { // Ensure the following node is only used for the // datastore. when "/sysc:system-capabilities/sysc:datastore-capabilities" + "/sysc:datastore = 'ds:operational'"; description "Defines some leafs that MAY be used by the server to describe constraints imposed of the 'where' filters and 'sort-by' parameters used in list pagination queries."; leaf snapshot { type empty; description "Indicates that snapshots are supported for the targeted 'config false' list or leaf-list node."; } } } ]]> <CODE ENDS>

IANA Considerations

The "IETF XML" Registry This document registers one URI in the "ns" subregistry of the IETF XML Registry maintained at . Following the format in , the following registration is requested:

The "YANG Module Names" Registry This document registers one YANG module in the YANG Module Names registry maintained at . Following the format defined in , the below registration is requested:

The "RESTCONF Capability URNs" Registry This document registers one capability in the RESTCONF Capability URNs maintained at . Following the instructions defined in , the below registrations are requested: All the registrations are to use this document (RFC XXXX) for the "Reference" value.

Security Considerations

Regarding the "ietf-list-pagination-snapshot" YANG Module The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF or RESTCONF . The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) . The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS . The Network Configuration Access Control Model (NACM) provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. All protocol-accessible data nodes in the extension to "ietf-system-capabilities" module are read-only and cannot be modified. Access control may be configured to avoid exposing any read-only data that is defined by the augmenting module documentation as being security sensitive. The security considerations for the base NETCONF protocol operations (see Section 9 of and Section 6 of ) apply to the extension made to operations <get>, <get-config>, and <get-data> defined in this document.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas. This document describes the structure, content, construction, and semantics of language tags for use in cases where it is desirable to indicate the language used in an information object. It also describes how to register values for use in language tags and the creation of user-defined extensions for private interchange. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK] This document describes a method for invoking and running the Network Configuration Protocol (NETCONF) within a Secure Shell (SSH) session as an SSH subsystem. This document obsoletes RFC 4742. [STANDARDS-TRACK] YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). This document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF). RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) or the RESTCONF protocol requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF or RESTCONF protocol access for particular users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. This document defines such an access control model. This document obsoletes RFC 6536. This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. This document extends the Network Configuration Protocol (NETCONF) defined in RFC 6241 in order to support the Network Management Datastore Architecture (NMDA) defined in RFC 8342. This document updates RFCs 6241 and 7950. The update to RFC 6241 adds new and operations and augments existing,, and operations. The update to RFC 7950 requires the usage of the YANG library (described in RFC 8525) by NETCONF servers implementing the NMDA. This document defines two YANG modules, "ietf-system-capabilities" and "ietf-notification-capabilities". The module "ietf-system-capabilities" provides a placeholder structure that can be used to discover YANG-related system capabilities for servers. The module can be used to report capability information from the server at runtime or at implementation time by making use of the YANG instance data file format. The module "ietf-notification-capabilities" augments "ietf-system-capabilities" to specify capabilities related to "Subscription to YANG Notifications for Datastore Updates" (RFC 8641). Informative References YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK] This document provides a list of terms used in the IETF when discussing internationalization. The purpose is to help frame discussions of internationalization in the various areas of the IETF and to help introduce the main concepts to IETF participants. This memo documents an Internet Best Current Practice. This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language. Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. This document describes a YANG library that provides information about the YANG modules, datastores, and datastore schemas used by a network management server. Simple caching mechanisms are provided to allow clients to minimize retrieval of this information. This version of the YANG library supports the Network Management Datastore Architecture (NMDA) by listing all datastores supported by a network management server and the schema that is used by each of these datastores.

Vector Tests This normative appendix section illustrates every notable edge condition conceived during this document's production. Test inputs and outputs are provided in a manner that is both generic and concise. Management protocol specific documents need only reproduce as many of these tests as necessary to convey pecularities presented by the protocol. Implementations are RECOMMENDED to implement the tests presented in this document, in addition to any tests that may be presented in protocol specific documents. The vector tests assume the "example-social" YANG module and example data set defined .

Example Data Set The examples assume the server's operational state as follows. The following data enables snapshot support for the audit-log list node. ds:operational /es:audit-logs/es:audit-log ]]>

Example Queries The following sections present example queries for the the snapshot query parameter. All the vector tests are presented in a protocol-independent manner. JSON is used only for its conciseness.

The "snapshot" Parameter The "snapshot" parameter may be used on "config false" target nodes. REQUEST RESPONSE

Acknowledgements The authors would like to thank the following for lively discussions on list (ordered by first name): Andy Bierman, Tom Petch, and Quifang Ma.