| Internet-Draft | NETCONF Pagination Support | November 2020 |
| Watsen, et al. | Expires 6 May 2021 | [Page] |
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.¶
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 6 May 2021.¶
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.¶
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]¶
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:¶
The 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> [RFC8526] 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 [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? <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 [RFC8526] 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 [RFC8526] 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 [RFC6241], [RFC6243], [RFC6991], and [RFC8342].¶
<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 [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-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 [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-restconf-list-pagination namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-list-pagination prefix: rlpg RFC: xxxx¶
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 <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 uint8¶
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;
}
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¶