List Pagination Snapshots for YANG-driven Protocols
draft-awwhl-netconf-list-pagination-snapshot-00
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Authors | Per Andersson , Kent Watsen , Qin Wu , Olof Hagsand , Hongwei Li | ||
| Last updated | 2024-03-01 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Yang Validation | 0 errors, 1 warnings | ||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-awwhl-netconf-list-pagination-snapshot-00
NETCONF Working Group P. Andersson
Internet-Draft Cisco Systems
Intended status: Standards Track K. Watsen
Expires: 2 September 2024 Watsen Networks
Q. Wu
Huawei Technologies
O. Hagsand
SUNET
H. Li
Hewlett Packard Enterprise
1 March 2024
List Pagination Snapshots for YANG-driven Protocols
draft-awwhl-netconf-list-pagination-snapshot-00
Abstract
List pagination for YANG-driven protocols are defined in
[I-D.ietf-netconf-list-pagination]. 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.
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 2 September 2024.
Andersson, et al. Expires 2 September 2024 [Page 1]
Internet-Draft List Pagination Snapshots March 2024
Copyright Notice
Copyright (c) 2024 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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Conventions . . . . . . . . . . . . . . . . . . . . . . . 4
1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 4
2. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4
4. Snapshot support . . . . . . . . . . . . . . . . . . . . . . 5
5. The "ietf-list-pagination-snapshot" Module . . . . . . . . . 5
5.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6
5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 10
6.2. The "YANG Module Names" Registry . . . . . . . . . . . . 10
6.3. The "RESTCONF Capability URNs" Registry . . . . . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . . 10
7.1. Regarding the "ietf-list-pagination-snapshot" YANG
Module . . . . . . . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Vector Tests . . . . . . . . . . . . . . . . . . . . 14
A.1. Example Data Set . . . . . . . . . . . . . . . . . . . . 14
A.2. Example Queries . . . . . . . . . . . . . . . . . . . . . 14
A.2.1. The "snapshot" Parameter . . . . . . . . . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction
The following open questions have been identified for list-pagination
with snapshots.
Andersson, et al. Expires 2 September 2024 [Page 2]
Internet-Draft List Pagination Snapshots March 2024
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.
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 [RFC7950] and are not redefined
here: client, data model, data tree, feature, extension, module,
leaf, leaf-list, and server.
Andersson, et al. Expires 2 September 2024 [Page 3]
Internet-Draft List Pagination Snapshots March 2024
1.2. Conventions
Various examples in this document use "BASE64VALUE=" as a placeholder
value for binary data that has been base64 encoded (per Section 9.8
of [RFC7950]). This placeholder value is used because real base64
encoded structures are often many lines long and hence distracting to
the example being presented.
1.3. Adherence to the NMDA
This document is compliant with the Network Management Datastore
Architecture (NMDA) [RFC8342]. 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.
2. Solution Overview
The solution presented in this document extends the pagination
functionality in [I-D.ietf-netconf-list-pagination]. The snapshot
functionality defined by the document conforms to "config false"
"list" and "leaf-list" nodes.
The "snapshot" query parameter (see Section 3) enables clients to ask
create a snapshot. The support for snapshots is signaled via
[RFC9196] (see Section 4).
3. 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.
Andersson, et al. Expires 2 September 2024 [Page 4]
Internet-Draft List Pagination Snapshots March 2024
3.1. 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.
3.2. 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.
+----------+---------+--------------------------------------------+
| Name | Methods | Description |
+----------+---------+--------------------------------------------+
| snapshot | GET, | Indicates that the server should take a |
| | HEAD | snapshot before paginating the result set. |
+----------+---------+--------------------------------------------+
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.
4. 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 Section 5) augments an empty leaf node called
"snapshot" into the "per-node-capabilities" node defined in the
"ietf-system-capabilities" module (see [RFC9196]).
Note that it is possible for a client to request the server to take a
snapshot when paginating with the "snapshot" query parameter (see
Section 3.
5. 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.
Andersson, et al. Expires 2 September 2024 [Page 5]
Internet-Draft List Pagination Snapshots March 2024
5.1. Data Model Overview
The following tree diagram [RFC8340] illustrates the "ietf-list-
pagination-snapshot" module:
module: ietf-list-pagination-snapshot
augment /nc:get/nc:input:
+---w snapshot? boolean
augment /nc:get-config/nc:input:
+---w snapshot? boolean
augment /ncds:get-data/ncds:input:
+---w snapshot? boolean
augment /sysc:system-capabilities/sysc:datastore-capabilities
/sysc:per-node-capabilities:
+--ro snapshot? empty
Comments:
As shown, this module augments an optional leaf into the "per-node-
capabilities" list node of the "ietf-system-capabilities" module.
5.2. YANG Module
This YANG module has normative references to [RFC7952] and [RFC9196].
<CODE BEGINS> file "ietf-list-pagination-snapshot@2024-03-01.yang"
module ietf-list-pagination-snapshot {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-list-pagination-snapshot";
prefix lpgsnap;
import ietf-datastores {
prefix ds;
reference
"RFC 8342: Network Management Datastore Architecture (NMDA)";
}
import ietf-netconf {
prefix nc;
reference
"RFC 6241: Network Configuration Protocol (NETCONF)";
}
import ietf-netconf-nmda {
prefix ncds;
Andersson, et al. Expires 2 September 2024 [Page 6]
Internet-Draft List Pagination Snapshots March 2024
reference
"RFC 8526: NETCONF Extensions to Support the
Network Management Datastore Architecture";
}
import ietf-system-capabilities {
prefix sysc;
reference
"RFC 9691: YANG Modules Describing Capabilities for Systems and
Datastore Update Notifications";
}
import ietf-list-pagination {
prefix lpg;
reference
"draft-ietf-list-pagination: List Pagination for YANG-driven
Protocols";
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: https://datatracker.ietf.org/wg/netconf
WG List: NETCONF WG list <mailto:netconf@ietf.org>";
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',
Andersson, et al. Expires 2 September 2024 [Page 7]
Internet-Draft List Pagination Snapshots March 2024
'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;
}
Andersson, et al. Expires 2 September 2024 [Page 8]
Internet-Draft List Pagination Snapshots March 2024
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
// <operational> 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>
6. IANA Considerations
Andersson, et al. Expires 2 September 2024 [Page 9]
Internet-Draft List Pagination Snapshots March 2024
6.1. The "IETF XML" Registry
This document registers one URI in the "ns" subregistry of the IETF
XML Registry [RFC3688] maintained at
https://www.iana.org/assignments/xml-registry/xml-registry.xhtml#ns.
Following the format in [RFC3688], the following registration is
requested:
URI: urn:ietf:params:xml:ns:yang:ietf-list-pagination-snapshot
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
6.2. The "YANG Module Names" Registry
This document registers one YANG module in the YANG Module Names
registry [RFC6020] maintained at https://www.iana.org/assignments/
yang-parameters/yang-parameters.xhtml. Following the format defined
in [RFC6020], the below registration is requested:
name: ietf-list-pagination-snapshot
namespace: urn:ietf:params:xml:ns:yang:ietf-list-pagination-snapshot
prefix: lpg
RFC: XXXX
6.3. The "RESTCONF Capability URNs" Registry
This document registers one capability in the RESTCONF Capability
URNs [RFC8040] maintained at https://www.iana.org/assignments/
restconf-capability-urns/restconf-capability-urns.xhtml. Following
the instructions defined in Section 11.4 of [RFC8040], the below
registrations are requested:
All the registrations are to use this document (RFC XXXX) for the
"Reference" value.
Index Capability Identifier
---------------------------------------------------------------------
:snapshot urn:ietf:params:restconf:capability:snapshot:1.0
7. Security Considerations
Andersson, et al. Expires 2 September 2024 [Page 10]
Internet-Draft List Pagination Snapshots March 2024
7.1. 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 [RFC6241] or 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 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 [RFC6241] and Section 6 of [RFC8526]) apply to the
extension made to operations <get>, <get-config>, and <get-data>
defined in this document.
8. References
8.1. Normative References
[I-D.ietf-netconf-list-pagination]
Watsen, K., Wu, Q., Andersson, P., Hagsand, O., and H. Li,
"List Pagination for YANG-driven Protocols", Work in
Progress, Internet-Draft, draft-ietf-netconf-list-
pagination-03, 1 March 2024,
<https://datatracker.ietf.org/api/v1/doc/document/draft-
ietf-netconf-list-pagination/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
Andersson, et al. Expires 2 September 2024 [Page 11]
Internet-Draft List Pagination Snapshots March 2024
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[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,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
<https://www.rfc-editor.org/info/rfc7952>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[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,
<https://www.rfc-editor.org/info/rfc8526>.
[RFC9196] Lengyel, B., Clemm, A., and B. Claise, "YANG Modules
Describing Capabilities for Systems and Datastore Update
Notifications", RFC 9196, DOI 10.17487/RFC9196, February
2022, <https://www.rfc-editor.org/info/rfc9196>.
Andersson, et al. Expires 2 September 2024 [Page 12]
Internet-Draft List Pagination Snapshots March 2024
8.2. Informative References
[I-D.ietf-netconf-list-pagination-nc]
Watsen, K., Wu, Q., Hagsand, O., Li, H., and P. Andersson,
"NETCONF Extensions to Support List Pagination", Work in
Progress, Internet-Draft, draft-ietf-netconf-list-
pagination-nc-02, 22 October 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-netconf-
list-pagination-nc-02>.
[I-D.ietf-netconf-list-pagination-rc]
Watsen, K., Wu, Q., Hagsand, O., Li, H., and P. Andersson,
"RESTCONF Extensions to Support List Pagination", Work in
Progress, Internet-Draft, draft-ietf-netconf-list-
pagination-rc-02, 22 October 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-netconf-
list-pagination-rc-02>.
[I-D.ietf-netconf-restconf-collection]
Bierman, A., Björklund, M., and K. Watsen, "RESTCONF
Collection Resource", Work in Progress, Internet-Draft,
draft-ietf-netconf-restconf-collection-00, 30 January
2015, <https://datatracker.ietf.org/doc/html/draft-ietf-
netconf-restconf-collection-00>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
Internationalization in the IETF", BCP 166, RFC 6365,
DOI 10.17487/RFC6365, September 2011,
<https://www.rfc-editor.org/info/rfc6365>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[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,
<https://www.rfc-editor.org/info/rfc8342>.
[RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", RFC 8525,
DOI 10.17487/RFC8525, March 2019,
<https://www.rfc-editor.org/info/rfc8525>.
Andersson, et al. Expires 2 September 2024 [Page 13]
Internet-Draft List Pagination Snapshots March 2024
Appendix A. 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 [I-D.ietf-netconf-list-pagination].
A.1. 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.
<system-capabilities
xmlns="urn:ietf:params:xml:ns:yang:ietf-system-capabilities"
xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores"
xmlns:es="https://example.com/ns/example-social"
xmlns:lpg="urn:ietf:params:xml:ns:yang:ietf-list-pagination">
<datastore-capabilities>
<datastore>ds:operational</datastore>
<per-node-capabilities>
<node-selector>/es:audit-logs/es:audit-log</node-selector>
<lpgsnap:snapshot/>
</per-node-capabilities>
</datastore-capabilities>
</system-capabilities>
A.2. 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.
Andersson, et al. Expires 2 September 2024 [Page 14]
Internet-Draft List Pagination Snapshots March 2024
A.2.1. The "snapshot" Parameter
The "snapshot" parameter may be used on "config false" target nodes.
| If this parameter is omitted, the default value is false.
REQUEST
Target: /example-social:audit-logs/audit-log
Pagination Parameters:
Where: -
Sort-by: -
Direction: -
Offset: -
Limit: -
Snapshot: true
RESPONSE
Andersson, et al. Expires 2 September 2024 [Page 15]
Internet-Draft List Pagination Snapshots March 2024
{
"example-social:audit-log": [
{
"member-id": "alice",
...
},
{
"member-id": "bob",
...
},
{
"member-id": "eric",
...
},
{
"member-id": "alice",
...
},
{
"member-id": "bob",
...
},
{
"member-id": "alice",
...
},
{
"member-id": "bob",
...
}
]
}
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.
Authors' Addresses
Per Andersson
Cisco Systems
Email: perander@cisco.com
Kent Watsen
Watsen Networks
Andersson, et al. Expires 2 September 2024 [Page 16]
Internet-Draft List Pagination Snapshots March 2024
Email: kent+ietf@watsen.net
Qin Wu
Huawei Technologies
Email: bill.wu@huawei.com
Olof Hagsand
SUNET
Email: olof@hagsand.se
Hongwei Li
Hewlett Packard Enterprise
Email: flycoolman@gmail.com
Andersson, et al. Expires 2 September 2024 [Page 17]