NETCONF Working Group K. Watsen
Internet-Draft Watsen Network
Intended status: Standards Track Q. Wu
Expires: May 6, 2021 Huawei
O. Hagsand
H. Li
HPE
November 2, 2020
NETCONF Extensions to Support List Pagination
draft-wwlh-netconf-list-pagination-nc-00
Abstract
In some circumstance, a server may contain many instances of a
particular YANG list or leaf-list. Retrieval of the entire list or
leaf-list at once can be extremely inefficient.
This document defines a YANG data model with "get-pageable-list" RPC
to allow a client to iterate through a large list, in a manner that
is most efficient for the application.
The YANG data model in this document conforms to the Network
Management Datastore Architecture defined in RFC 8342.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 6, 2021.
Watsen, et al. Expires May 6, 2021 [Page 1]
Internet-Draft NETCONF Pagination Support November 2020
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. NETCONF operation . . . . . . . . . . . . . . . . . . . . . . 4
2.1. The <get-list-pagination> operation . . . . . . . . . . . 4
3. YANG Module for List Pagination . . . . . . . . . . . . . . . 6
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
5. Security Considerations . . . . . . . . . . . . . . . . . . . 13
6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 14
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . 14
8.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 16
Appendix B. Example YANG Module . . . . . . . . . . . . . . . . 16
B.1. "example-module" YANG Module . . . . . . . . . . . . . . 17
B.2. Data-Set for example-module . . . . . . . . . . . . . . . 23
Appendix C. NETCONF YANG Collection Examples . . . . . . . . . . 27
C.1. "count" Parameter . . . . . . . . . . . . . . . . . . . . 28
C.2. "skip" Parameter . . . . . . . . . . . . . . . . . . . . 28
C.3. "direction" Parameter . . . . . . . . . . . . . . . . . . 29
C.4. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 30
C.5. Combination of "where" and "count" Parameters . . . . . . 31
C.6. Combination of "where", "count" and "skip" Parameters . . 32
C.7. Combination of "where", "count","skip" and "sort"
Parameters . . . . . . . . . . . . . . . . . . . . . . . 33
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34
Watsen, et al. Expires May 6, 2021 [Page 2]
Internet-Draft NETCONF Pagination Support November 2020
1. Introduction
There is a need for standard mechanisms to control the filtering,
sorting, and retrieval of data from the server. A server may contain
many instances of a particular YANG list. Retrieval of the entire
list or leaf-list at once can be extremely inefficient.
This document defines a YANG module for Pagination mechanisms which
allow a client to iterate through a large list or leaf-list, in a
manner that is most efficient for the application.
While the pagination mechanism is designed for the NETCONF protocol
[RFC6241], the RPC MAY be used by the RESTCONF protocol [RFC8040] if
the RESTCONF server implements the "ietf-yang-list-pagination"
module.
The YANG data model in this document conforms to the Network
Management Datastore Architecture defined in [RFC8342].
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
The following terms are defined in [RFC8342] [RFC7950] and are not
redefined here:
o server
o startup configuration datastore
o candidate configuration datastore
o running configuration datastore
o intended configuration datastore
o operational state datastore
o conventional configuration datastore
o datastore schema
o RPC operation
Watsen, et al. Expires May 6, 2021 [Page 3]
Internet-Draft NETCONF Pagination Support November 2020
The following terms are defined in this document as follows:
2. NETCONF operation
This document define a new operation -- <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.
2.1. The <get-list-pagination> operation
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.
Watsen, et al. Expires May 6, 2021 [Page 4]
Internet-Draft NETCONF Pagination Support November 2020
The "config-filter" parameter can be used to retrieve only "config
true" or "config false" nodes.
The "origin-filter" parameter, which can be present multiple times,
selects nodes equal to or derived from any of the given values. The
"negated-origin-filter", which can be present multiple times, selects
nodes that are not equal to or derived from any of the given values.
The "origin-filter" and "negated-origin-filter" parameters cannot be
used together.
The "max-depth" parameter can be used by the client to limit the
number of subtree levels that are returned in the reply.
The "with-origin" parameter can be used to request the server to
include "origin" metadata annotations in its response, as detailed in
the NMDA. The 'with-origin' parameter is only valid for an
operational datastore. See section 3.1.1.1 of [RFC8526] for the
behavior of the "with-origin" parameter for <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.
Watsen, et al. Expires May 6, 2021 [Page 5]
Internet-Draft NETCONF Pagination Support November 2020
The "sort" parameter is used to indicates how the entries in a list
are to be sorted. By default, the value of the "sort" is default,
i.e., for 'ordered-by user' lists and leaf-lists, the default order
is the user-configured order; for 'ordered-by system' lists and leaf-
lists, the default order is specified by the system.
The "where" parameter is used to specify the boolean filter to select
data instances to return from the list or leaf-list target. The
filter element contains boolean XPATH expression. The filter output
is a set of selected list items. The server determines which node
instances are included (or potentially included) in the filter
output, and which node instances are excluded (pruned) from the
filter output.
The selected list instances are numbered with consecutive integers
from 1 to the number of list instances.
The expected processing order: filter -> sort -> direction -> skip ->
count.
3. YANG Module for List Pagination
The "ietf-netconf-list-pagination" module defines conceptual
definitions within groupings, which are not meant to be implemented
as datastore contents by a server.
<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-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)";
Watsen, et al. Expires May 6, 2021 [Page 6]
Internet-Draft NETCONF Pagination Support November 2020
}
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";
}
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
Watsen, et al. Expires May 6, 2021 [Page 7]
Internet-Draft NETCONF Pagination Support November 2020
"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 {
Watsen, et al. Expires May 6, 2021 [Page 8]
Internet-Draft NETCONF Pagination Support November 2020
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.";
}
}
Watsen, et al. Expires May 6, 2021 [Page 9]
Internet-Draft NETCONF Pagination Support November 2020
leaf config-filter {
type boolean;
description
"Filter for nodes with the given value for their 'config'
property. When this leaf is set to 'true', only 'config
true' nodes are selected, and when set to 'false', only
'config false' nodes are selected. If this leaf is not
present, no nodes are filtered.";
}
choice origin-filters {
when 'derived-from-or-self(datastore, "ds:operational")';
if-feature "origin";
description
"Filters configuration nodes based on the 'origin'
annotation. Configuration nodes that do not have an
'origin' annotation are treated as if they have the
'origin' annotation 'or:unknown'.
System state nodes are not affected by origin-filters and
thus not filtered. Note that system state nodes can be
filtered with the 'config-filter' leaf.";
leaf-list origin-filter {
type or:origin-ref;
description
"Filter based on the 'origin' annotation. A
configuration node matches the filter if its 'origin'
annotation is derived from or equal to any of the given
filter values.";
}
leaf-list negated-origin-filter {
type or:origin-ref;
description
"Filter based on the 'origin' annotation. A
configuration node matches the filter if its 'origin'
annotation is neither derived from nor equal to any of
the given filter values.";
}
}
leaf max-depth {
type union {
type uint16 {
range "1..65535";
}
type enumeration {
enum unbounded {
description
"All descendant nodes are included.";
}
Watsen, et al. Expires May 6, 2021 [Page 10]
Internet-Draft NETCONF Pagination Support November 2020
}
}
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';
Watsen, et al. Expires May 6, 2021 [Page 11]
Internet-Draft NETCONF Pagination Support November 2020
}
}
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;
Watsen, et al. Expires May 6, 2021 [Page 12]
Internet-Draft NETCONF Pagination Support November 2020
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>
4. IANA Considerations
This document registers one URI in the IETF XML Registry [RFC3688].
The following registration has been made:
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]. The following registration has been made:
name: ietf-netconf-list-pagination
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination
prefix: lpg
RFC: xxxx
5. Security Considerations
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].
Watsen, et al. Expires May 6, 2021 [Page 13]
Internet-Draft NETCONF Pagination Support November 2020
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.
6. Contributors
Per Andersson
perander@cisco.com
David Cornejo
dcornejo@gmail.com
7. Acknowledgements
This work has benefited from the discussions of restconf resource
collection over the years, in particular, [I-D.ietf-netconf-restconf-
collection] which provides enhanced filtering features for the
retrieval of data nodes with the GET method and [I-D.zheng-netconf-
fragmentation] which document large size data handling challenge.
The authors would like to thank the following for lively discussions
on list:
Andy Bierman
Martin Bjoerklund
Robert Varga
8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<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>.
[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>.
Watsen, et al. Expires May 6, 2021 [Page 14]
Internet-Draft NETCONF Pagination Support November 2020
[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>.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
<https://www.rfc-editor.org/info/rfc6243>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>.
[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>.
[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>.
[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>.
8.2. Informative References
[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>.
Watsen, et al. Expires May 6, 2021 [Page 15]
Internet-Draft NETCONF Pagination Support November 2020
Appendix A. Open Issues
Cursors (i.e.,stable result sets) are related to the topic of dynamic
changing lists between two queries. How cursors can be supported
using "feature"?
Appendix B. Example YANG Module
The example YANG module used in this document is supposed to
illustrate certain features and not supposed to be complete, valid
YANG modules.
YANG tree diagram for the "example-module" module:
Watsen, et al. Expires May 6, 2021 [Page 16]
Internet-Draft NETCONF Pagination Support November 2020
module: example-module
+--rw admins
| +--rw admin* [name]
| +--rw name string
| +--rw access? enumeration
| +--rw email-address? email-address
| +--rw password? ianach:crypt-hash
| +--ro status* string
| +--rw preference
| | +--rw number* uint8
| +--rw skill* [name]
| +--rw name string
| +--rw rank? uint8
+--rw rulebase
| +--rw rule* [name]
| +--rw name string
| +--rw match? string
| +--rw action? enumeration
+--rw device-logs
| +--ro device-log* []
| +--ro device-id? string
| +--ro time-received? yang:timestamp
| +--ro time-generated? yang:timestamp
| +--ro message? string
+--rw audit-logs
| +--ro audit-log* [log-creation]
| +--ro source-ip? inet:ip-address
| +--ro log-creation? yang:timestamp
| +--ro request? string
| +--ro outcome? boolean
+--rw prefixes
+--rw prefix-list* [ip-prefix masklength-lower masklength-upper]
+--rw ip-prefix inet:ip-prefix
+--rw masklength-lower uint8
+--rw masklength-upper uint8
B.1. "example-module" YANG Module
module example-module {
yang-version 1.1;
namespace "http://example.com/ns/example-module";
prefix exm;
import iana-crypt-hash {
prefix ianach;
}
import ietf-inet-types {
prefix inet;
Watsen, et al. Expires May 6, 2021 [Page 17]
Internet-Draft NETCONF Pagination Support November 2020
}
import ietf-yang-types {
prefix yang;
}
organization
"Example, Inc.";
contact
"support at example.com";
description
"Example Data Model Module.";
revision 2020-10-06 {
description
"Initial version.";
reference
"example.com document 1-4673.";
}
container admins {
description
"Admin Group configuration.";
list admin {
key "name";
description
"List of admins for admin group configuration.";
ordered-by system;
leaf name {
type string {
length "1 .. max";
}
description
"The name of the admin.";
}
leaf access {
type enumeration {
enum permit {
description
"Permit access privilege.";
}
enum deny {
description
"Deny access privilege.";
}
enum limited {
description
"Limited access privilege.";
}
Watsen, et al. Expires May 6, 2021 [Page 18]
Internet-Draft NETCONF Pagination Support November 2020
}
default "permit";
description
"The Access privilege type for this admin.";
}
leaf email-address {
type inet:email-address;
description
"Contact email of the admin.";
}
leaf password {
type ianach:crypt-hash;
description
"The password for this entry.";
}
leaf-list status {
type string;
config false;
description
"The status for this entry.";
}
container preference {
leaf-list number {
type uint8;
description
"Defines the perference numbers for the admin.";
}
description
"Preference parameters.";
}
list skill {
key "name";
description
"Represents one 'sill' resource within one
'admin' resource.";
leaf name {
type string {
length "1 .. max";
}
description
"The name of the skill.";
}
leaf rank {
type uint16;
description
"The rank identifying the rank on
the skill.";
}
Watsen, et al. Expires May 6, 2021 [Page 19]
Internet-Draft NETCONF Pagination Support November 2020
}
}
}
container rulebase {
description
"Rule base configuration";
list rule {
key "name";
description
"List of rules for rulebase.";
ordered-by user;
leaf name {
type string {
length "1 .. max";
}
description
"The name of the rule.";
}
leaf match {
type string {
length "1 .. max";
}
description
"The rules in this rulebase determine what fields will be
matched upon before any action is taken on them.";
}
leaf action {
type enumeration {
enum forwarding {
description
"Specify forwarding behavior per rule entry.";
}
enum logging {
description
"Specify logging behavior per rule entry.";
}
}
default "logging";
description
"Defintion of the action for this rule entry.";
}
}
}
container device-logs {
description
"Device log configuration";
list device-log {
description
Watsen, et al. Expires May 6, 2021 [Page 20]
Internet-Draft NETCONF Pagination Support November 2020
"List of device logs.";
config false;
leaf device-id {
type string;
description
"The device id of the device log.";
}
leaf time-received {
type yang:date-and-time;
description
"The timestamp value at the time this
log was received.";
}
leaf time-generated {
type yang:date-and-time;
description
"The timestamp value at the time this
log was generated.";
}
leaf message {
type string;
description
"Message given at start of login session.";
}
}
}
container audit-logs {
description
"Audit log configuration";
list audit-log {
key "log-creation";
description
"List of audit logs.";
config false;
leaf source-ip {
type inet:ip-address;
description
"The IP address of the targeted object.";
}
leaf log-creation {
type yang:date-and-time;
description
"The timestamp value at the time this
log was created.";
}
leaf request {
type string;
description
Watsen, et al. Expires May 6, 2021 [Page 21]
Internet-Draft NETCONF Pagination Support November 2020
"Request type of audit log.";
}
leaf outcome {
type boolean;
default "true";
description
"Indicate the audit log is retrieved sucessfully or not.";
}
}
}
container prefixes {
description
"Enclosing container for the list of prefixes in a policy
prefix list";
list prefix-list {
key "ip-prefix masklength-lower masklength-upper";
description
"List of prefixes in the prefix set";
leaf ip-prefix {
type inet:ip-prefix;
mandatory true;
description
"The prefix member in CIDR notation -- while the
prefix may be either IPv4 or IPv6, most
implementations require all members of the prefix set
to be the same address family. Mixing address types in
the same prefix set is likely to cause an error.";
}
leaf masklength-lower {
type uint8;
description
"Masklength range lower bound.";
}
leaf masklength-upper {
type uint8 {
range "1..128";
}
must '../masklength-upper >= ../masklength-lower' {
error-message "The upper bound should not be lessthan lower bound.";
}
description
"Masklength range upper bound.
The combination of masklength-lower and masklength-upper
define a range for the mask length, or single 'exact'
length if masklength-lower and masklenght-upper are equal.
Example: 10.3.192.0/21 through 10.3.192.0/24 would be
Watsen, et al. Expires May 6, 2021 [Page 22]
Internet-Draft NETCONF Pagination Support November 2020
expressed as prefix: 10.3.192.0/21,
masklength-lower=21,
masklength-upper=24
Example: 10.3.192.0/21 (an exact match) would be
expressed as prefix: 10.3.192.0/21,
masklength-lower=21,
masklength-upper=21";
}
}
}
}
B.2. Data-Set for example-module
<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>
Watsen, et al. Expires May 6, 2021 [Page 23]
Internet-Draft NETCONF Pagination Support November 2020
</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>
Watsen, et al. Expires May 6, 2021 [Page 24]
Internet-Draft NETCONF Pagination Support November 2020
<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>
Watsen, et al. Expires May 6, 2021 [Page 25]
Internet-Draft NETCONF Pagination Support November 2020
<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>
Watsen, et al. Expires May 6, 2021 [Page 26]
Internet-Draft NETCONF Pagination Support November 2020
<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>
Appendix C. NETCONF YANG Collection Examples
The examples within this document use the "example-module" YANG
module defined in Appendix A.
Watsen, et al. Expires May 6, 2021 [Page 27]
Internet-Draft NETCONF Pagination Support November 2020
C.1. "count" Parameter
In this example, the client requests the first two "skill" resources
for a given admin resource:
Request from NETCONF client
<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>
C.2. "skip" Parameter
In this example, the client requests the next two skills resource,
i.e., two skills resource starting from two.
Watsen, et al. Expires May 6, 2021 [Page 28]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
C.3. "direction" Parameter
In this example, the client requests the first two "skill" resources
in the forward direction for a given admin:
Watsen, et al. Expires May 6, 2021 [Page 29]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
C.4. "sort" Parameter
In this example, the client requests the first 3 "skill" resources
sorted by name for a given admin:
Watsen, et al. Expires May 6, 2021 [Page 30]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
C.5. Combination of "where" and "count" Parameters
In this example, the client requests the first 2 "skill" resources
from the selected skill resource list for a given admin:
Watsen, et al. Expires May 6, 2021 [Page 31]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
C.6. Combination of "where", "count" and "skip" Parameters
In this example, the client requests the first 2 "skill" resources
from the selected "skill" resource list for a given admin:
Watsen, et al. Expires May 6, 2021 [Page 32]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
C.7. Combination of "where", "count","skip" and "sort" Parameters
In this example, the client requests the first 2 "skill" resources
from the selected skill resources list for a given admin:
Watsen, et al. Expires May 6, 2021 [Page 33]
Internet-Draft NETCONF Pagination Support November 2020
Request from NETCONF client
<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>
Authors' Addresses
Kent Watsen
Watsen Network
Email: kent+ietf@watsen.net
Qin Wu
Huawei
101 Software Avenue, Yuhua District
Nanjing, Jiangsu 210012
China
Email: bill.wu@huawei.com
Watsen, et al. Expires May 6, 2021 [Page 34]
Internet-Draft NETCONF Pagination Support November 2020
Olof Hagsand
Email: olof@hagsand.se
Hongwei Li
HPE
Email: flycoolman@gmail.com
Watsen, et al. Expires May 6, 2021 [Page 35]