NETCONF Extensions to Support
List PaginationWatsen Networkkent+ietf@watsen.netHuawei101 Software Avenue, Yuhua DistrictNanjingJiangsu210012Chinabill.wu@huawei.comNetgateolof@hagsand.seHPEflycoolman@gmail.com
OPS Area
NETCONF Working GroupIn 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.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 , the RPC MAY be
used by the RESTCONF protocol 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 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:serverstartup configuration datastorecandidate configuration datastorerunning configuration datastoreintended configuration datastoreoperational state datastoreconventional configuration datastoredatastore schemaRPC operationThe following terms are defined in this document as follows:This document define a new operation -- <get-list-pagination>
to support YANG based pagination. This operation is similar to the
<get-data> in that it takes an input parameter to
indicate the datastore that is the source of the data to be
retrieved.The <get-pageable-list> operation uses enhanced filtering
features to retrieve data from a specific NMDA datastore. This
operation is similar to <get-data> operation defined in
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? <anydata>
| | +--:(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? <anyxml>The "datastore" parameter indicates the datastore that is the
source of the data to be retrieved. This is a "datastore"
identity.The <get-pageable-list> operation accepts a content filter
parameter, similar to the "filter" parameter of <get-config>,
but uses explicit nodes for list filtering or leaf-list filtering.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 for the behavior of the
"with-origin" parameter for <operational>.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
for the behavior of the "with-defaults" parameter for
<operational>.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.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.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 ,
, , and .<CODE BEGINS> 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
"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: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Editor:
Editor:
Editor: ";
description
"This module define a new operation -- <get-collection>
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.";
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 <rpc-error> element
with an <error-tag> 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
<rpc-error> element with an <error-tag> value of
'invalid-value'.";
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 <rpc-error> element with an
<error-tag> 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
<get-data> 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.";
}
}
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
"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;
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.";
}
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.";
}
}
}
}
<CODE ENDS>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: 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.This document registers one YANG module in the YANG Module
Names registry maintained at
.
Following the format defined in , the below
registration is requested: name: ietf-restconf-list-pagination
namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-list-pagination
prefix: rlpg
RFC: xxxxThe YANG module defined in this document extends the base operations
for NETCONF and 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 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 apply to the new
<get-list-pagination> RPC operations defined in this document.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"?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: 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 uint8module 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;
}
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.";
}
}
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.";
}
}
}
}
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
"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
"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
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";
}
}
}
} <admins xmlns="http://example.com/ns/example-module">
<admin>
<name>Alice</name>
<access>permit</access>
<email-address>alice@example.com</email-address>
<password>$0$1543</password>
<status>Available</status>
<preference>
<number>1</number>
<number>2</number>
</preference>
<skill>
<name>Customer Service</name>
<rank>99</rank>
</skill>
<skill>
<name>Problem Solving</name>
<rank>90</rank>
</skill>
</admin>
<admin>
<name>Bob</name>
<access>limited</access>
<email-address>bob@example.com</email-address>
<password>$0$2789</password>
<status>Busy</status>
<preference>
<number>2</number>
<number>3</number>
</preference>
<skill>
<name>Problem Solving</name>
<rank>98</rank>
</skill>
<skill>
<name>Conflict Resolution</name>
<rank>93</rank>
</skill>
</admin>
<admin>
<name>Joe</name>
<access>permit</access>
<email-address>joe@example.com</email-address>
<password>$0$6523</password>
<status>Do Not Disturb</status>
<preference>
<number>1</number>
<number>4</number>
</preference>
<skill>
<name>Management</name>
<rank>96</rank>
</skill>
<skill>
<name>Collaboration</name>
<rank>92</rank>
</skill>
</admin>
<admin>
<name>Frank</name>
<access>deny</access>
<email-address>frank@example.com</email-address>
<password>$0$4030</password>
<status>Offline</status>
<preference>
<number>5</number>
<number>9</number>
</preference>
<skill>
<name>Organization</name>
<rank>90</rank>
</skill>
<skill>
<name>Negotiation</name>
<rank>80</rank>
</skill>
</admin>
<admin>
<name>Tom</name>
<access>permit</access>
<email-address>tom@example.com</email-address>
<password>$0$2376</password>
<status>Do Not Disturb</status>
<preference>
<number>2</number>
<number>5</number>
</preference>
<skill>
<name>Adaptability.</name>
<rank>98</rank>
</skill>
<skill>
<name>Active Listening</name>
<rank>85</rank>
</skill>
</admin>
</admins>
<rulebase xmlns="http://example.com/ns/example-module">
<rule>
<name>SvrA-http</name>
<match>92.0.2.0/24</match>
<action>forwarding</action>
</rule>
<rule>
<name>SvrA-ftp</name>
<match>203.0.113.1/32</match>
<action>forwarding</action>
</rule>
<rule>
<name>p2p</name>
<match>p2p</match>
<action>logging</action>
</rule>
<rule>
<name>any</name>
<match>any</match>
<action>logging</action>
</rule>
<rule>
<name>SvrA-tcp</name>
<match>80</match>
<action>forwarding</action>
</rule>
</rulebase>
<device-logs xmlns="http://example.com/ns/example-module">
<device-log>
<device-id>Cloud-IoT-Device-A</device-id>
<time-received>2020-07-08T12:38:32Z</time-received>
<time-generated>2020-07-08T12:37:12Z</time-generated>
<message>Upload contains 6 datapoints</message>
</device-log>
<device-log>
<device-id>Cloud-IoT-Device-B</device-id>
<time-received>2020-07-08T16:20:54Z</time-received>
<time-generated>2020-07-08T16:20:14Z</time-generated>
<message>Upload successful</message>
</device-log>
<device-log>
<device-id>Cloud-IoT-Device-C</device-id>
<time-received>2020-07-08T17:30:34Z</time-received>
<time-generated>2020-07-08T17:30:12Z</time-generated>
<message>Receive a configuration update</message>
</device-log>
<device-log>
<device-id>Cloud-IoT-Device-D</device-id>
<time-received>2020-07-08T18:40:13Z</time-received>
<time-generated>2020-07-08T18:40:00Z</time-generated>
<message>Keep-alive ping sent to server</message>
</device-log>
<device-log>
<device-id>Cloud-IoT-Device-E</device-id>
<time-received>2020-07-08T19:48:34Z</time-received>
<time-generated>2020-07-08T19:48:00Z</time-generated>
<message>Uploading data to DataPoint</message>
</device-log>
</device-logs>
<audit-logs xmlns="http://example.com/ns/example-module">
<audit-log>
<source-ip>192.168.0.92</source-ip>
<log-creation>2020-11-01T06:47:59Z</log-creation>
<request>User-logged-out</request>
<outcome>true</outcome>
</audit-log>
<audit-log>
<source-ip>192.168.0.92</source-ip>
<log-creation>2020-11-01T06:49:03Z</log-creation>
<request>User-logged-in</request>
<outcome>true</outcome>
</audit-log>
<audit-log>
<source-ip>192.168.0.92</source-ip>
<log-creation>2020-11-01T06:51:34Z</log-creation>
<request>Patron-card-viewed</request>
<outcome>false</outcome>
</audit-log>
<audit-log>
<source-ip>192.168.0.92</source-ip>
<log-creation>2020-11-01T06:53:01Z</log-creation>
<request>User-logged-out</request>
<outcome>true</outcome>
</audit-log>
<audit-log>
<source-ip>192.168.0.92</source-ip>
<log-creation>2020-11-01T06:56:22Z</log-creation>
<request>User-logged-in</request>
<outcome>false</outcome>
</audit-log>
</audit-logs>
<prefixes xmlns="http://example.com/ns/example-module">
<prefix-list>
<ip-prefix>10.0.0.0 8</ip-prefix>
<masklength-lower>17</masklength-lower>
<masklength-upper>18</masklength-upper>
</prefix-list>
<prefix-list>
<ip-prefix>2000:1::</ip-prefix>
<masklength-lower>48</masklength-lower>
<masklength-upper>48</masklength-upper>
</prefix-list>
<prefix-list>
<ip-prefix>2000:2::</ip-prefix>
<masklength-lower>48</masklength-lower>
<masklength-upper>48</masklength-upper>
</prefix-list>
<prefix-list>
<ip-prefix>2000:3::</ip-prefix>
<masklength-lower>16</masklength-lower>
<masklength-upper>16</masklength-upper>
</prefix-list>
<prefix-list>
<ip-prefix>::</ip-prefix>
<masklength-lower>0</masklength-lower>
<masklength-upper>128</masklength-upper>
</prefix-list>
</prefixes> The examples within this document use the "example-module" YANG
module defined in Appendix A.In this example, the client requests the first two "skill"
resources for a given admin resource:Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target>admins/admin[name=Bob]/skill</list-target>
<count>2</count>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the next two skills resource,
i.e., two skills resource starting from two. Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target>admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<skip>2</skip>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the first two "skill"
resources in the forward direction for a given admin:Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target>admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<direction>forward</direction>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the first 3 "skill" resources
sorted by name for a given admin: Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target>admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<sort>name</sort>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the first 2 "skill" resources
from the selected skill resource list for a given admin: Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target>admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<where>position>=2 and position<=9</where>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the first 2 "skill" resources
from the selected "skill" resource list for a given admin: Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target> admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<skip>2</skip>
<where>position>=2 and position<=9</where>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>In this example, the client requests the first 2 "skill" resources
from the selected skill resources list for a given admin: Request from NETCONF client
<netconf:rpc netconf:message-id="101"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-pageable-list
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<datastore>running</datastore>
<list-target> admins/admin[name=Bob]/skill </list-target>
<count>2</count>
<skip>2</skip>
<sort>name</sort>
<where>[position>=2 and position<=9]</where>
</get-pageable-list>
</netconf:rpc>
Response from NETCONF server
<netconf:rpc-reply netconf:message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<pageable-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination">
<skill xmlns="http://example.com/ns/example-module">
<name>Problem Solving</name>
<rank>98</rank>
...
</skill>
<skill xmlns="http://example.com/ns/example-module">
<name>Conflict Resolution</name>
<rank>93</rank>
...
</skill>
</pageable-list>
</netconf:rpc-reply>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 Björklund
Robert Varga