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