idnits 2.17.1 draft-wwlh-netconf-list-pagination-nc-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 17 instances of too long lines in the document, the longest one being 16 characters in excess of 72. == There are 4 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 171 has weird spacing: '...-target str...' == Line 738 has weird spacing: '...rw name str...' == Line 760 has weird spacing: '...h-lower uin...' == Line 761 has weird spacing: '...h-upper uin...' == Line 1131 has weird spacing: '...ulebase xmlns...' == (3 more instances...) -- The document date (November 2, 2020) is 1270 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Network 4 Intended status: Standards Track Q. Wu 5 Expires: May 6, 2021 Huawei 6 O. Hagsand 7 Netgate 8 H. Li 9 HPE 10 November 2, 2020 12 NETCONF Extensions to Support List Pagination 13 draft-wwlh-netconf-list-pagination-nc-01 15 Abstract 17 In some circumstance, a server may contain many instances of a 18 particular YANG list or leaf-list. Retrieval of the entire list or 19 leaf-list at once can be extremely inefficient. 21 This document defines a YANG data model with "get-pageable-list" RPC 22 to allow a client to iterate through a large list, in a manner that 23 is most efficient for the application. 25 The YANG data model in this document conforms to the Network 26 Management Datastore Architecture defined in RFC 8342. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 6, 2021. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. NETCONF operation . . . . . . . . . . . . . . . . . . . . . . 4 65 2.1. The operation . . . . . . . . . . . 4 66 3. YANG Module for List Pagination . . . . . . . . . . . . . . . 6 67 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 68 4.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 13 69 4.2. The "YANG Module Names" Registry . . . . . . . . . . . . 13 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 71 5.1. The "ietf-netconf-list-pagination" YANG Module . . . . . 14 72 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 73 6.1. Normative References . . . . . . . . . . . . . . . . . . 14 74 6.2. Informative References . . . . . . . . . . . . . . . . . 15 75 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 16 76 Appendix B. Example YANG Module . . . . . . . . . . . . . . . . 16 77 B.1. "example-module" YANG Module . . . . . . . . . . . . . . 17 78 B.2. Data-Set for example-module . . . . . . . . . . . . . . . 23 79 Appendix C. NETCONF YANG Collection Examples . . . . . . . . . . 27 80 C.1. "count" Parameter . . . . . . . . . . . . . . . . . . . . 28 81 C.2. "skip" Parameter . . . . . . . . . . . . . . . . . . . . 28 82 C.3. "direction" Parameter . . . . . . . . . . . . . . . . . . 29 83 C.4. "sort" Parameter . . . . . . . . . . . . . . . . . . . . 30 84 C.5. Combination of "where" and "count" Parameters . . . . . . 31 85 C.6. Combination of "where", "count" and "skip" Parameters . . 32 86 C.7. Combination of "where", "count","skip" and "sort" 87 Parameters . . . . . . . . . . . . . . . . . . . . . . . 33 88 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 91 1. Introduction 93 There is a need for standard mechanisms to control the filtering, 94 sorting, and retrieval of data from the server. A server may contain 95 many instances of a particular YANG list. Retrieval of the entire 96 list or leaf-list at once can be extremely inefficient. 98 This document defines a YANG module for Pagination mechanisms which 99 allow a client to iterate through a large list or leaf-list, in a 100 manner that is most efficient for the application. 102 While the pagination mechanism defined in this document is designed 103 for the NETCONF protocol [RFC6241], the RPC MAY be used by the 104 RESTCONF protocol [RFC8040] if the RESTCONF server implements the 105 "ietf-yang-list-pagination" module. 107 The YANG data model in this document conforms to the Network 108 Management Datastore Architecture defined in [RFC8342] 110 1.1. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 The following terms are defined in [RFC8342] [RFC7950] and are not 119 redefined here: 121 o server 123 o startup configuration datastore 125 o candidate configuration datastore 127 o running configuration datastore 129 o intended configuration datastore 131 o operational state datastore 133 o conventional configuration datastore 135 o datastore schema 137 o RPC operation 138 The following terms are defined in this document as follows: 140 2. NETCONF operation 142 This document define a new operation -- to 143 support YANG based pagination. This operation is similar to the 144 [RFC8526] in that it takes an input parameter to indicate 145 the datastore that is the source of the data to be retrieved. 147 2.1. The operation 149 The operation uses enhanced filtering features to 150 retrieve data from a specific NMDA datastore. This operation is 151 similar to operation defined in [RFC8526] and have the 152 flexibility to select the different source datastore. 154 +---x get-pageable-list 155 +---w input 156 | +---w datastore? string 157 | +---w (filter-spec)? 158 | | +--:(subtree-filter) 159 | | | +---w subtree-filter? 160 | | +--:(xpath-filter) 161 | | +---w xpath-filter? yang:xpath1.0 {nc:xpath}? 162 | +---w config-filter? boolean 163 | +---w (origin-filters)? {origin}? 164 | | +--:(origin-filter) 165 | | | +---w origin-filter* or:origin-ref 166 | | +--:(negated-origin-filter) 167 | | +---w negated-origin-filter* or:origin-ref 168 | +---w max-depth? union 169 | +---w with-origin? empty {origin}? 170 | +---w with-defaults? with-defaults-mode 171 | +---w list-target string 172 | +---w count? union 173 | +---w skip? union 174 | +---w direction? enumeration 175 | +---w sort? string 176 | +---w where? string 177 +--ro output 178 +--ro collection? 180 The "datastore" parameter indicates the datastore that is the source 181 of the data to be retrieved. This is a "datastore" identity. 183 The operation accepts a content filter parameter, 184 similar to the "filter" parameter of , but uses explicit 185 nodes for list filtering or leaf-list filtering. 187 The "config-filter" parameter can be used to retrieve only "config 188 true" or "config false" nodes. 190 The "origin-filter" parameter, which can be present multiple times, 191 selects nodes equal to or derived from any of the given values. The 192 "negated-origin-filter", which can be present multiple times, selects 193 nodes that are not equal to or derived from any of the given values. 194 The "origin-filter" and "negated-origin-filter" parameters cannot be 195 used together. 197 The "max-depth" parameter can be used by the client to limit the 198 number of subtree levels that are returned in the reply. 200 The "with-origin" parameter can be used to request the server to 201 include "origin" metadata annotations in its response, as detailed in 202 the NMDA. The 'with-origin' parameter is only valid for an 203 operational datastore. See section 3.1.1.1 of [RFC8526] for the 204 behavior of the "with-origin" parameter for . 206 The "with-default"parameter can be used to control whether default 207 data is returned by the server. The 'with-default' parameter is only 208 valid for an operational datastore. See section 3.1.1.2 of [RFC8526] 209 for the behavior of the "with-defaults" parameter for . 211 The "list-target" parameter is used to specify that YANG list that 212 will be retrieved. This must be a path expression used to represent 213 a list data node. 215 The "count" parameter can be used to specify the maximum number of 216 list entries to return. The value of the "count" parameter is either 217 an integer greater than or equal to 1, or the string "unbounded". 218 The string "unbounded" is the default value. 220 The "skip" parameter can be used to specify the first list item to 221 return in response to NETCONF/Request requests on instances of a 222 particular YANG list. YANG list instances are numbered with 223 consecutive integers from 1 to the number of YANG list instances. 225 The value of the "skip" parameter is an integer greater than or equal 226 to 1. The default value is 1. 228 If the "where" parameter is specified, the "skip" parameter MUST 229 start with a set of selected list resources picked by using "where" 230 parameter and specify the first list item resource to return. 232 The "direction" parameter can be used to specify the direction 233 relative to the 'sort' order through list or leaf-list. 235 The "sort" parameter is used to indicates how the entries in a list 236 are to be sorted. By default, the value of the "sort" is default, 237 i.e., for 'ordered-by user' lists and leaf-lists, the default order 238 is the user-configured order; for 'ordered-by system' lists and leaf- 239 lists, the default order is specified by the system. 241 The "where" parameter is used to specify the boolean filter to select 242 data instances to return from the list or leaf-list target. The 243 filter element contains boolean XPATH expression. The filter output 244 is a set of selected list items. The server determines which node 245 instances are included (or potentially included) in the filter 246 output, and which node instances are excluded (pruned) from the 247 filter output. 249 The selected list instances are numbered with consecutive integers 250 from 1 to the number of list instances. 252 The expected processing order: filter -> sort -> direction -> skip -> 253 count. 255 3. YANG Module for List Pagination 257 The "ietf-netconf-list-pagination" module defines conceptual 258 definitions within groupings, which are not meant to be implemented 259 as datastore contents by a server. 261 This module has normative references to [RFC6241], [RFC6243], 262 [RFC6991], and [RFC8342]. 264 file "ietf-netconf-list-pagination@2020-10-30.yang" 265 module ietf-netconf-list-pagination { 266 yang-version 1.1; 267 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination"; 268 prefix ycoll; 270 import ietf-netconf { 271 prefix nc; 272 reference 273 "RFC 6241: Network Configuration Protocol (NETCONF)"; 274 } 275 import ietf-netconf-with-defaults { 276 prefix ncwd; 277 reference 278 "RFC 6243: With-defaults Capability for NETCONF"; 279 } 280 import ietf-yang-types { 281 prefix yang; 282 reference 283 "RFC 6991: Common YANG Data Types"; 284 } 285 import ietf-datastores { 286 prefix ds; 287 reference 288 "RFC 8342: Network Management Datastore Architecture 289 (NMDA)"; 290 } 291 import ietf-origin { 292 prefix or; 293 reference 294 "RFC 8342: Network Management Datastore Architecture 295 (NMDA)"; 296 } 298 organization 299 "IETF NETCONF (Network Configuration) Working Group"; 300 contact 301 "WG Web: 302 WG List: 304 Editor: 306 Editor: 308 Editor: "; 309 description 310 "This module define a new operation -- 311 to support YANG based pagination. 313 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 314 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 315 'MAY', and 'OPTIONAL' in this document are to be interpreted as 316 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 317 they appear in all capitals, as shown here. 319 Copyright (c) 2019 IETF Trust and the persons identified as 320 authors of the code. All rights reserved. 322 Redistribution and use in source and binary forms, with or 323 without modification, is permitted pursuant to, and subject to 324 the license terms contained in, the Simplified BSD License set 325 forth in Section 4.c of the IETF Trust's Legal Provisions 326 Relating to IETF Documents 327 (https://trustee.ietf.org/license-info). 329 This version of this YANG module is part of RFC 8526; see 330 the RFC itself for full legal notices."; 332 revision 2020-10-30 { 333 description 334 "Initial revision."; 335 reference 336 "RFC XXXX: YANG Based Pagination."; 337 } 339 feature origin { 340 description 341 "Indicates that the server supports the 'origin' annotation."; 342 reference 343 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 344 } 346 feature with-defaults { 347 description 348 "NETCONF :with-defaults capability. If the server advertises 349 the :with-defaults capability for a session, then this 350 feature must also be enabled for that session. Otherwise, 351 this feature must not be enabled."; 352 reference 353 "RFC 6243: With-defaults Capability for NETCONF, Section 4; and 354 RFC 8526: NETCONF Extensions to Support the Network Management 355 Datastore Architecture, Section 3.1.1.2"; 356 } 358 rpc get-pagable-list { 359 description 360 "Use enhanced filtering features to retrieve data from a 361 specific NMDA datastore. The content returned by get-data 362 must satisfy all filters, i.e., the filter criteria are 363 logically ANDed. 365 Any ancestor nodes (including list keys) of nodes selected by 366 the filters are included in the response. 368 The 'with-origin' parameter is only valid for an operational 369 datastore. If 'with-origin' is used with an invalid 370 datastore, then the server MUST return an element 371 with an value of 'invalid-value'. 373 The 'with-defaults' parameter only applies to the operational 374 datastore if the NETCONF :with-defaults and 375 :with-operational-defaults capabilities are both advertised. 376 If the 'with-defaults' parameter is present in a request for 377 which it is not supported, then the server MUST return an 378 element with an value of 379 'invalid-value'."; 381 input { 382 leaf datastore { 383 type ds:datastore-ref; 384 mandatory true; 385 description 386 "Datastore from which to retrieve data. 388 If the datastore is not supported by the server, then 389 the server MUST return an element with an 390 value of 'invalid-value'."; 391 } 392 choice filter-spec { 393 description 394 "The content filter specification for this request."; 395 anydata subtree-filter { 396 description 397 "This parameter identifies the portions of the 398 target datastore to retrieve."; 399 reference 400 "RFC 6241: Network Configuration Protocol (NETCONF), 401 Section 6"; 402 } 403 leaf xpath-filter { 404 if-feature "nc:xpath"; 405 type yang:xpath1.0; 406 description 407 "This parameter contains an XPath expression identifying 408 the portions of the target datastore to retrieve. 410 If the expression returns a node-set, all nodes in the 411 node-set are selected by the filter. Otherwise, if the 412 expression does not return a node-set, then the 413 operation fails. 415 The expression is evaluated in the following XPath 416 context: 418 o The set of namespace declarations are those in 419 scope on the 'xpath-filter' leaf element. 421 o The set of variable bindings is empty. 423 o The function library is the core function library, 424 and the XPath functions are defined in Section 10 425 of RFC 7950. 427 o The context node is the root node of the target 428 datastore."; 430 } 431 } 432 leaf config-filter { 433 type boolean; 434 description 435 "Filter for nodes with the given value for their 'config' 436 property. When this leaf is set to 'true', only 'config 437 true' nodes are selected, and when set to 'false', only 438 'config false' nodes are selected. If this leaf is not 439 present, no nodes are filtered."; 440 } 441 choice origin-filters { 442 when 'derived-from-or-self(datastore, "ds:operational")'; 443 if-feature "origin"; 444 description 445 "Filters configuration nodes based on the 'origin' 446 annotation. Configuration nodes that do not have an 447 'origin' annotation are treated as if they have the 448 'origin' annotation 'or:unknown'. 450 System state nodes are not affected by origin-filters and 451 thus not filtered. Note that system state nodes can be 452 filtered with the 'config-filter' leaf."; 453 leaf-list origin-filter { 454 type or:origin-ref; 455 description 456 "Filter based on the 'origin' annotation. A 457 configuration node matches the filter if its 'origin' 458 annotation is derived from or equal to any of the given 459 filter values."; 460 } 461 leaf-list negated-origin-filter { 462 type or:origin-ref; 463 description 464 "Filter based on the 'origin' annotation. A 465 configuration node matches the filter if its 'origin' 466 annotation is neither derived from nor equal to any of 467 the given filter values."; 468 } 469 } 470 leaf max-depth { 471 type union { 472 type uint16 { 473 range "1..65535"; 474 } 475 type enumeration { 476 enum unbounded { 477 description 478 "All descendant nodes are included."; 479 } 480 } 481 } 482 default "unbounded"; 483 description 484 "For each node selected by the filters, this parameter 485 selects how many conceptual subtree levels should be 486 returned in the reply. If the depth is 1, the reply 487 includes just the selected nodes but no children. If the 488 depth is 'unbounded', all descendant nodes are included."; 489 } 490 leaf with-origin { 491 when 'derived-from-or-self(../datastore, "ds:operational")'; 492 if-feature "origin"; 493 type empty; 494 description 495 "If this parameter is present, the server will return 496 the 'origin' annotation for the nodes that have one."; 497 } 498 uses ncwd:with-defaults-parameters { 499 if-feature "with-defaults"; 500 } 501 leaf list-target { 502 description 503 "Identifies the list object that is being retrieved. 504 This must be a path expression used to represent 505 a list data node or leaf-list data node. "; 506 mandatory true; 507 type string; 508 } 509 leaf count { 510 type union { 511 type uint32; 512 type string { 513 pattern 'unbounded'; 514 } 515 } 516 default "unbounded"; 517 description 518 "The maximum number of list entries to return. The 519 value of the 'count' parameter is either an integer 520 greater than or equal to 1, or the string 'unbounded'. 521 The string 'unbounded' is the default value."; 522 } 523 leaf skip { 524 type union { 525 type uint32; 526 type string { 527 pattern 'none'; 528 } 529 } 530 default "none"; 531 description 532 "The first list item to return. 533 the 'skip' parameter is either an integer greater than 534 or equal to 1, or the string 'unbounded'. The string 535 'unbounded' is the default value."; 536 } 537 leaf direction { 538 type enumeration { 539 enum forward; 540 enum reverse; 541 } 542 default "forward"; 543 description 544 "Direction relative to the 'sort' order through list 545 or leaf-list. It can be forward direction or reverse 546 direction."; 547 } 548 leaf sort { 549 type union { 550 type string { 551 length "1..max" { 552 description 553 "The name of a descendent node to sort on. For 554 'Config false' lists and leaf-lists, the node SHOULD 555 have the 'TBD' extension indicating that it has been 556 indexed, enabling efficient sorts."; 557 } 558 } 559 type enumeration { 560 enum default { 561 description 562 "Indicates that the 'default' order is assumed. For 563 'ordered-by user' lists and leaf-lists, the default order 564 is the user-configured order. For 'ordered-by system' 565 lists and leaf-lists, the default order is specified by the 566 system."; 567 } 568 } 569 } 570 default "default"; 571 description 572 "Indicates how the entries in a list are to be sorted."; 573 } 574 leaf where { 575 type yang:xpath1.0; 576 description 577 "The boolean filter to select data instances to return from 578 the list or leaf-list target. The Xpath expression MAY be 579 constrained either server-wide, by datastore, by 'config' 580 status, or per list or leaf-list. Details regarding how 581 constraints are communicated are TBD. This parameter 582 is optional; no filtering is applied when it is not 583 specified."; 584 } 585 } 586 output { 587 anyxml pageable-list { 588 description 589 "Return the list entries that were requested and matched 590 the filter criteria (if any). An empty data container 591 indicates that the request did not produce any results."; 592 } 593 } 594 } 595 } 596 598 4. IANA Considerations 600 4.1. The "IETF XML" Registry 602 This document registers one URI in the "ns" subregistry of the IETF 603 XML Registry [RFC3688] maintained at 604 . Following the format in [RFC3688], the following 606 registration is requested: 608 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-list-pagination 609 Registrant Contact: The IESG. 610 XML: N/A, the requested URI is an XML namespace. 612 4.2. The "YANG Module Names" Registry 614 This document registers one YANG module in the YANG Module Names 615 registry [RFC6020] maintained at . Following the format defined 617 in [RFC6020], the below registration is requested: 619 name: ietf-restconf-list-pagination 620 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-list-pagination 621 prefix: rlpg 622 RFC: xxxx 624 5. Security Considerations 626 5.1. The "ietf-netconf-list-pagination" YANG Module 628 The YANG module defined in this document extends the base operations 629 for NETCONF [RFC6241] and RESTCONF [RFC8040]. The lowest NETCONF 630 layer is the secure transport layer, and the mandatory-to-implement 631 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 632 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 633 transport is TLS [RFC8446]. 635 The Network Configuration Access Control Model (NACM) [RFC8341] 636 provides the means to restrict access for particular NETCONF users to 637 a preconfigured subset of all available NETCONF protocol operations 638 and content. 640 The security considerations for the base NETCONF protocol operations 641 (see Section 9 of [RFC6241] apply to the new 642 RPC operations defined in this document. 644 6. References 646 6.1. Normative References 648 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 649 Requirement Levels", BCP 14, RFC 2119, 650 DOI 10.17487/RFC2119, March 1997, 651 . 653 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 654 DOI 10.17487/RFC3688, January 2004, 655 . 657 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 658 the Network Configuration Protocol (NETCONF)", RFC 6020, 659 DOI 10.17487/RFC6020, October 2010, 660 . 662 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 663 and A. Bierman, Ed., "Network Configuration Protocol 664 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 665 . 667 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 668 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 669 . 671 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 672 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 673 . 675 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 676 RFC 6991, DOI 10.17487/RFC6991, July 2013, 677 . 679 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 680 RFC 7950, DOI 10.17487/RFC7950, August 2016, 681 . 683 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 684 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 685 May 2017, . 687 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 688 Access Control Model", STD 91, RFC 8341, 689 DOI 10.17487/RFC8341, March 2018, 690 . 692 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 693 and R. Wilton, "Network Management Datastore Architecture 694 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 695 . 697 6.2. Informative References 699 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 700 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 701 . 703 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 704 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 705 . 707 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 708 and R. Wilton, "NETCONF Extensions to Support the Network 709 Management Datastore Architecture", RFC 8526, 710 DOI 10.17487/RFC8526, March 2019, 711 . 713 Appendix A. Open Issues 715 Cursors (i.e.,stable result sets) are related to the topic of dynamic 716 changing lists between two queries. How cursors can be supported 717 using "feature"? 719 Appendix B. Example YANG Module 721 The example YANG module used in this document is supposed to 722 illustrate certain features and not supposed to be complete, valid 723 YANG modules. 725 YANG tree diagram for the "example-module" module: 727 module: example-module 728 +--rw admins 729 | +--rw admin* [name] 730 | +--rw name string 731 | +--rw access? enumeration 732 | +--rw email-address? email-address 733 | +--rw password? ianach:crypt-hash 734 | +--ro status* string 735 | +--rw preference 736 | | +--rw number* uint8 737 | +--rw skill* [name] 738 | +--rw name string 739 | +--rw rank? uint8 740 +--rw rulebase 741 | +--rw rule* [name] 742 | +--rw name string 743 | +--rw match? string 744 | +--rw action? enumeration 745 +--rw device-logs 746 | +--ro device-log* [] 747 | +--ro device-id? string 748 | +--ro time-received? yang:timestamp 749 | +--ro time-generated? yang:timestamp 750 | +--ro message? string 751 +--rw audit-logs 752 | +--ro audit-log* [log-creation] 753 | +--ro source-ip? inet:ip-address 754 | +--ro log-creation? yang:timestamp 755 | +--ro request? string 756 | +--ro outcome? boolean 757 +--rw prefixes 758 +--rw prefix-list* [ip-prefix masklength-lower masklength-upper] 759 +--rw ip-prefix inet:ip-prefix 760 +--rw masklength-lower uint8 761 +--rw masklength-upper uint8 763 B.1. "example-module" YANG Module 765 module example-module { 766 yang-version 1.1; 767 namespace "http://example.com/ns/example-module"; 768 prefix exm; 770 import iana-crypt-hash { 771 prefix ianach; 772 } 773 import ietf-inet-types { 774 prefix inet; 776 } 777 import ietf-yang-types { 778 prefix yang; 779 } 781 organization 782 "Example, Inc."; 783 contact 784 "support at example.com"; 785 description 786 "Example Data Model Module."; 788 revision 2020-10-06 { 789 description 790 "Initial version."; 791 reference 792 "example.com document 1-4673."; 793 } 795 container admins { 796 description 797 "Admin Group configuration."; 798 list admin { 799 key "name"; 800 description 801 "List of admins for admin group configuration."; 802 ordered-by system; 803 leaf name { 804 type string { 805 length "1 .. max"; 806 } 807 description 808 "The name of the admin."; 809 } 810 leaf access { 811 type enumeration { 812 enum permit { 813 description 814 "Permit access privilege."; 815 } 816 enum deny { 817 description 818 "Deny access privilege."; 819 } 820 enum limited { 821 description 822 "Limited access privilege."; 823 } 825 } 826 default "permit"; 827 description 828 "The Access privilege type for this admin."; 829 } 830 leaf email-address { 831 type inet:email-address; 832 description 833 "Contact email of the admin."; 834 } 835 leaf password { 836 type ianach:crypt-hash; 837 description 838 "The password for this entry."; 839 } 840 leaf-list status { 841 type string; 842 config false; 843 description 844 "The status for this entry."; 845 } 846 container preference { 847 leaf-list number { 848 type uint8; 849 description 850 "Defines the perference numbers for the admin."; 851 } 852 description 853 "Preference parameters."; 854 } 855 list skill { 856 key "name"; 857 description 858 "Represents one 'sill' resource within one 859 'admin' resource."; 860 leaf name { 861 type string { 862 length "1 .. max"; 863 } 864 description 865 "The name of the skill."; 866 } 867 leaf rank { 868 type uint16; 869 description 870 "The rank identifying the rank on 871 the skill."; 872 } 874 } 875 } 876 } 877 container rulebase { 878 description 879 "Rule base configuration"; 880 list rule { 881 key "name"; 882 description 883 "List of rules for rulebase."; 884 ordered-by user; 885 leaf name { 886 type string { 887 length "1 .. max"; 888 } 889 description 890 "The name of the rule."; 891 } 892 leaf match { 893 type string { 894 length "1 .. max"; 895 } 896 description 897 "The rules in this rulebase determine what fields will be 898 matched upon before any action is taken on them."; 899 } 900 leaf action { 901 type enumeration { 902 enum forwarding { 903 description 904 "Specify forwarding behavior per rule entry."; 905 } 906 enum logging { 907 description 908 "Specify logging behavior per rule entry."; 909 } 910 } 911 default "logging"; 912 description 913 "Defintion of the action for this rule entry."; 914 } 915 } 916 } 917 container device-logs { 918 description 919 "Device log configuration"; 920 list device-log { 921 description 922 "List of device logs."; 923 config false; 924 leaf device-id { 925 type string; 926 description 927 "The device id of the device log."; 928 } 929 leaf time-received { 930 type yang:date-and-time; 931 description 932 "The timestamp value at the time this 933 log was received."; 934 } 935 leaf time-generated { 936 type yang:date-and-time; 937 description 938 "The timestamp value at the time this 939 log was generated."; 940 } 941 leaf message { 942 type string; 943 description 944 "Message given at start of login session."; 945 } 946 } 947 } 948 container audit-logs { 949 description 950 "Audit log configuration"; 951 list audit-log { 952 key "log-creation"; 953 description 954 "List of audit logs."; 955 config false; 956 leaf source-ip { 957 type inet:ip-address; 958 description 959 "The IP address of the targeted object."; 960 } 961 leaf log-creation { 962 type yang:date-and-time; 963 description 964 "The timestamp value at the time this 965 log was created."; 966 } 967 leaf request { 968 type string; 969 description 970 "Request type of audit log."; 971 } 972 leaf outcome { 973 type boolean; 974 default "true"; 975 description 976 "Indicate the audit log is retrieved sucessfully or not."; 977 } 978 } 979 } 980 container prefixes { 981 description 982 "Enclosing container for the list of prefixes in a policy 983 prefix list"; 984 list prefix-list { 985 key "ip-prefix masklength-lower masklength-upper"; 986 description 987 "List of prefixes in the prefix set"; 988 leaf ip-prefix { 989 type inet:ip-prefix; 990 mandatory true; 991 description 992 "The prefix member in CIDR notation -- while the 993 prefix may be either IPv4 or IPv6, most 994 implementations require all members of the prefix set 995 to be the same address family. Mixing address types in 996 the same prefix set is likely to cause an error."; 997 } 998 leaf masklength-lower { 999 type uint8; 1000 description 1001 "Masklength range lower bound."; 1002 } 1003 leaf masklength-upper { 1004 type uint8 { 1005 range "1..128"; 1006 } 1007 must '../masklength-upper >= ../masklength-lower' { 1008 error-message "The upper bound should not be lessthan lower bound."; 1009 } 1010 description 1011 "Masklength range upper bound. 1013 The combination of masklength-lower and masklength-upper 1014 define a range for the mask length, or single 'exact' 1015 length if masklength-lower and masklenght-upper are equal. 1017 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 1018 expressed as prefix: 10.3.192.0/21, 1019 masklength-lower=21, 1020 masklength-upper=24 1022 Example: 10.3.192.0/21 (an exact match) would be 1023 expressed as prefix: 10.3.192.0/21, 1024 masklength-lower=21, 1025 masklength-upper=21"; 1026 } 1027 } 1028 } 1029 } 1031 B.2. Data-Set for example-module 1033 1034 1035 Alice 1036 permit 1037 alice@example.com 1038 $0$1543 1039 Available 1040 1041 1 1042 2 1043 1044 1045 Customer Service 1046 99 1047 1048 1049 Problem Solving 1050 90 1051 1052 1053 1054 Bob 1055 limited 1056 bob@example.com 1057 $0$2789 1058 Busy 1059 1060 2 1061 3 1062 1063 1064 Problem Solving 1065 98 1067 1068 1069 Conflict Resolution 1070 93 1071 1072 1073 1074 Joe 1075 permit 1076 joe@example.com 1077 $0$6523 1078 Do Not Disturb 1079 1080 1 1081 4 1082 1083 1084 Management 1085 96 1086 1087 1088 Collaboration 1089 92 1090 1091 1092 1093 Frank 1094 deny 1095 frank@example.com 1096 $0$4030 1097 Offline 1098 1099 5 1100 9 1101 1102 1103 Organization 1104 90 1105 1106 1107 Negotiation 1108 80 1109 1110 1111 1112 Tom 1113 permit 1114 tom@example.com 1115 $0$2376 1116 Do Not Disturb 1117 1118 2 1119 5 1120 1121 1122 Adaptability. 1123 98 1124 1125 1126 Active Listening 1127 85 1128 1129 1130 1131 1132 1133 SvrA-http 1134 92.0.2.0/24 1135 forwarding 1136 1137 1138 SvrA-ftp 1139 203.0.113.1/32 1140 forwarding 1141 1142 1143 p2p 1144 p2p 1145 logging 1146 1147 1148 any 1149 any 1150 logging 1151 1152 1153 SvrA-tcp 1154 80 1155 forwarding 1156 1157 1158 1159 1160 Cloud-IoT-Device-A 1161 2020-07-08T12:38:32Z 1162 2020-07-08T12:37:12Z 1163 Upload contains 6 datapoints 1164 1165 1166 Cloud-IoT-Device-B 1167 2020-07-08T16:20:54Z 1168 2020-07-08T16:20:14Z 1169 Upload successful 1170 1171 1172 Cloud-IoT-Device-C 1173 2020-07-08T17:30:34Z 1174 2020-07-08T17:30:12Z 1175 Receive a configuration update 1176 1177 1178 Cloud-IoT-Device-D 1179 2020-07-08T18:40:13Z 1180 2020-07-08T18:40:00Z 1181 Keep-alive ping sent to server 1182 1183 1184 Cloud-IoT-Device-E 1185 2020-07-08T19:48:34Z 1186 2020-07-08T19:48:00Z 1187 Uploading data to DataPoint 1188 1189 1190 1191 1192 192.168.0.92 1193 2020-11-01T06:47:59Z 1194 User-logged-out 1195 true 1196 1197 1198 192.168.0.92 1199 2020-11-01T06:49:03Z 1200 User-logged-in 1201 true 1202 1203 1204 192.168.0.92 1205 2020-11-01T06:51:34Z 1206 Patron-card-viewed 1207 false 1208 1209 1210 192.168.0.92 1211 2020-11-01T06:53:01Z 1212 User-logged-out 1213 true 1214 1215 1216 192.168.0.92 1217 2020-11-01T06:56:22Z 1218 User-logged-in 1219 false 1220 1221 1222 1223 1224 10.0.0.0 8 1225 17 1226 18 1227 1228 1229 2000:1:: 1230 48 1231 48 1232 1233 1234 2000:2:: 1235 48 1236 48 1237 1238 1239 2000:3:: 1240 16 1241 16 1242 1243 1244 :: 1245 0 1246 128 1247 1248 1250 Appendix C. NETCONF YANG Collection Examples 1252 The examples within this document use the "example-module" YANG 1253 module defined in Appendix A. 1255 C.1. "count" Parameter 1257 In this example, the client requests the first two "skill" resources 1258 for a given admin resource: 1260 Request from NETCONF client 1261 1263 1265 running 1266 admins/admin[name=Bob]/skill 1267 2 1268 1269 1271 Response from NETCONF server 1272 1274 1275 1276 Problem Solving 1277 98 1278 ... 1279 1280 1281 Conflict Resolution 1282 93 1283 ... 1284 1285 1286 1288 C.2. "skip" Parameter 1290 In this example, the client requests the next two skills resource, 1291 i.e., two skills resource starting from two. 1293 Request from NETCONF client 1294 1296 1298 running 1299 admins/admin[name=Bob]/skill 1300 2 1301 2 1302 1303 1305 Response from NETCONF server 1306 1308 1309 1310 Problem Solving 1311 98 1312 ... 1313 1314 1315 Conflict Resolution 1316 93 1317 ... 1318 1319 1320 1322 C.3. "direction" Parameter 1324 In this example, the client requests the first two "skill" resources 1325 in the forward direction for a given admin: 1327 Request from NETCONF client 1328 1330 1332 running 1333 admins/admin[name=Bob]/skill 1334 2 1335 forward 1336 1337 1339 Response from NETCONF server 1340 1342 1343 1344 Problem Solving 1345 98 1346 ... 1347 1348 1349 Conflict Resolution 1350 93 1351 ... 1352 1353 1354 1356 C.4. "sort" Parameter 1358 In this example, the client requests the first 3 "skill" resources 1359 sorted by name for a given admin: 1361 Request from NETCONF client 1362 1364 1366 running 1367 admins/admin[name=Bob]/skill 1368 2 1369 name 1370 1371 1373 Response from NETCONF server 1374 1376 1377 1378 Problem Solving 1379 98 1380 ... 1381 1382 1383 Conflict Resolution 1384 93 1385 ... 1386 1387 1388 1390 C.5. Combination of "where" and "count" Parameters 1392 In this example, the client requests the first 2 "skill" resources 1393 from the selected skill resource list for a given admin: 1395 Request from NETCONF client 1396 1398 1400 running 1401 admins/admin[name=Bob]/skill 1402 2 1403 position>=2 and position<=9 1404 1405 1407 Response from NETCONF server 1408 1410 1411 1412 Problem Solving 1413 98 1414 ... 1415 1416 1417 Conflict Resolution 1418 93 1419 ... 1420 1421 1422 1424 C.6. Combination of "where", "count" and "skip" Parameters 1426 In this example, the client requests the first 2 "skill" resources 1427 from the selected "skill" resource list for a given admin: 1429 Request from NETCONF client 1430 1432 1434 running 1435 admins/admin[name=Bob]/skill 1436 2 1437 2 1438 position>=2 and position<=9 1439 1440 1442 Response from NETCONF server 1443 1445 1446 1447 Problem Solving 1448 98 1449 ... 1450 1451 1452 Conflict Resolution 1453 93 1454 ... 1455 1456 1457 1459 C.7. Combination of "where", "count","skip" and "sort" Parameters 1461 In this example, the client requests the first 2 "skill" resources 1462 from the selected skill resources list for a given admin: 1464 Request from NETCONF client 1465 1467 1469 running 1470 admins/admin[name=Bob]/skill 1471 2 1472 2 1473 name 1474 [position>=2 and position<=9] 1475 1476 1478 Response from NETCONF server 1479 1481 1482 1483 Problem Solving 1484 98 1485 ... 1486 1487 1488 Conflict Resolution 1489 93 1490 ... 1491 1492 1493 1495 Acknowledgements 1497 This work has benefited from the discussions of restconf resource 1498 collection over the years, in particular, [I-D.ietf-netconf-restconf- 1499 collection] which provides enhanced filtering features for the 1500 retrieval of data nodes with the GET method and [I-D.zheng-netconf- 1501 fragmentation] which document large size data handling challenge. 1502 The authors would like to thank the following for lively discussions 1503 on list: 1505 Andy Bierman 1506 Martin Bjoerklund 1507 Robert Varga 1509 Authors' Addresses 1511 Kent Watsen 1512 Watsen Network 1514 EMail: kent+ietf@watsen.net 1516 Qin Wu 1517 Huawei 1518 101 Software Avenue, Yuhua District 1519 Nanjing, Jiangsu 210012 1520 China 1522 EMail: bill.wu@huawei.com 1524 Olof Hagsand 1525 Netgate 1527 EMail: olof@hagsand.se 1529 Hongwei Li 1530 HPE 1532 EMail: flycoolman@gmail.com