idnits 2.17.1 draft-ietf-netconf-restconf-client-server-23.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1214 has weird spacing: '...address ine...' -- The document date (18 May 2021) is 1074 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) == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-06 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-21 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-09 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-23 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-22 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-22 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-23 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-14 Summary: 0 errors (**), 0 flaws (~~), 11 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 Networks 4 Intended status: Standards Track 18 May 2021 5 Expires: 19 November 2021 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-23 10 Abstract 12 This document defines two YANG modules, one module to configure a 13 RESTCONF client and the other module to configure a RESTCONF server. 14 Both modules support the TLS transport protocol with both standard 15 RESTCONF and RESTCONF Call Home connections. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains placeholder values that need to be replaced with 20 finalized values at the time of publication. This note summarizes 21 all of the substitutions that are needed. No other RFC Editor 22 instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements (note: not all may 26 be present): 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 32 anchors 34 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 36 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 37 client-server 39 * "EEEE" --> the assigned RFC value for draft-ietf-netconf-ssh- 40 client-server 42 * "FFFF" --> the assigned RFC value for draft-ietf-netconf-tls- 43 client-server 45 * "GGGG" --> the assigned RFC value for draft-ietf-netconf-http- 46 client-server 48 * "HHHH" --> the assigned RFC value for draft-ietf-netconf-netconf- 49 client-server 51 * "IIII" --> the assigned RFC value for this draft 53 Artwork in this document contains placeholder values for the date of 54 publication of this draft. Please apply the following replacement: 56 * "2021-05-18" --> the publication date of this draft 58 The following Appendix section is to be removed prior to publication: 60 * Appendix B. Change Log 62 Status of This Memo 64 This Internet-Draft is submitted in full conformance with the 65 provisions of BCP 78 and BCP 79. 67 Internet-Drafts are working documents of the Internet Engineering 68 Task Force (IETF). Note that other groups may also distribute 69 working documents as Internet-Drafts. The list of current Internet- 70 Drafts is at https://datatracker.ietf.org/drafts/current/. 72 Internet-Drafts are draft documents valid for a maximum of six months 73 and may be updated, replaced, or obsoleted by other documents at any 74 time. It is inappropriate to use Internet-Drafts as reference 75 material or to cite them other than as "work in progress." 77 This Internet-Draft will expire on 19 November 2021. 79 Copyright Notice 81 Copyright (c) 2021 IETF Trust and the persons identified as the 82 document authors. All rights reserved. 84 This document is subject to BCP 78 and the IETF Trust's Legal 85 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 86 license-info) in effect on the date of publication of this document. 87 Please review these documents carefully, as they describe your rights 88 and restrictions with respect to this document. Code Components 89 extracted from this document must include Simplified BSD License text 90 as described in Section 4.e of the Trust Legal Provisions and are 91 provided without warranty as described in the Simplified BSD License. 93 Table of Contents 95 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 96 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 97 1.2. Specification Language . . . . . . . . . . . . . . . . . 6 98 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 6 99 2. The "ietf-restconf-client" Module . . . . . . . . . . . . . . 6 100 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 101 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 11 102 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 14 103 3. The "ietf-restconf-server" Module . . . . . . . . . . . . . . 25 104 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 25 105 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 30 106 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 34 107 4. Security Considerations . . . . . . . . . . . . . . . . . . . 46 108 4.1. The "ietf-restconf-client" YANG Module . . . . . . . . . 46 109 4.2. The "ietf-restconf-server" YANG Module . . . . . . . . . 47 110 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 111 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 47 112 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 48 113 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 114 6.1. Normative References . . . . . . . . . . . . . . . . . . 48 115 6.2. Informative References . . . . . . . . . . . . . . . . . 49 116 Appendix A. Expanded Tree Diagrams . . . . . . . . . . . . . . . 51 117 A.1. Expanded Tree Diagram for 'ietf-restconf-client' . . . . 51 118 A.2. Expanded Tree Diagram for 'ietf-restconf-server' . . . . 51 119 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 51 120 B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 51 121 B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 52 122 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 52 123 B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 52 124 B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 52 125 B.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 52 126 B.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 53 127 B.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 53 128 B.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 53 129 B.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 53 130 B.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 53 131 B.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 54 132 B.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 54 133 B.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 54 134 B.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 55 135 B.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 55 136 B.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 55 137 B.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 55 138 B.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 55 139 B.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 56 140 B.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 56 141 B.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 56 142 B.23. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 56 143 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 56 144 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 56 146 1. Introduction 148 This document defines two YANG [RFC7950] modules, one module to 149 configure a RESTCONF client and the other module to configure a 150 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446] 151 transport protocol with both standard RESTCONF and RESTCONF Call Home 152 connections [RFC8071]. 154 1.1. Relation to other RFCs 156 This document presents one or more YANG modules [RFC7950] that are 157 part of a collection of RFCs that work together to, ultimately, 158 enable the configuration of the clients and servers of both the 159 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 161 The modules have been defined in a modular fashion to enable their 162 use by other efforts, some of which are known to be in progress at 163 the time of this writing, with many more expected to be defined in 164 time. 166 The normative dependency relationship between the various RFCs in the 167 collection is presented in the below diagram. The labels in the 168 diagram represent the primary purpose provided by each RFC. 169 Hyperlinks to each RFC are provided below the diagram. 171 crypto-types 172 ^ ^ 173 / \ 174 / \ 175 truststore keystore 176 ^ ^ ^ ^ 177 | +---------+ | | 178 | | | | 179 | +------------+ | 180 tcp-client-server | / | | 181 ^ ^ ssh-client-server | | 182 | | ^ tls-client-server 183 | | | ^ ^ http-client-server 184 | | | | | ^ 185 | | | +-----+ +---------+ | 186 | | | | | | 187 | +-----------|--------|--------------+ | | 188 | | | | | | 189 +-----------+ | | | | | 190 | | | | | | 191 | | | | | | 192 netconf-client-server restconf-client-server 194 +=======================+===========================================+ 195 |Label in Diagram | Originating RFC | 196 +=======================+===========================================+ 197 |crypto-types | [I-D.ietf-netconf-crypto-types] | 198 +-----------------------+-------------------------------------------+ 199 |truststore | [I-D.ietf-netconf-trust-anchors] | 200 +-----------------------+-------------------------------------------+ 201 |keystore | [I-D.ietf-netconf-keystore] | 202 +-----------------------+-------------------------------------------+ 203 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 204 +-----------------------+-------------------------------------------+ 205 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 206 +-----------------------+-------------------------------------------+ 207 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 208 +-----------------------+-------------------------------------------+ 209 |http-client-server | [I-D.ietf-netconf-http-client-server] | 210 +-----------------------+-------------------------------------------+ 211 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 212 +-----------------------+-------------------------------------------+ 213 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 214 +-----------------------+-------------------------------------------+ 216 Table 1: Label to RFC Mapping 218 1.2. Specification Language 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 222 "OPTIONAL" in this document are to be interpreted as described in BCP 223 14 [RFC2119] [RFC8174] when, and only when, they appear in all 224 capitals, as shown here. 226 1.3. Adherence to the NMDA 228 This document is compliant with the Network Management Datastore 229 Architecture (NMDA) [RFC8342]. For instance, as described in 230 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 231 trust anchors and keys installed during manufacturing are expected to 232 appear in . 234 2. The "ietf-restconf-client" Module 236 The RESTCONF client model presented in this section supports both 237 clients initiating connections to servers, as well as clients 238 listening for connections from servers calling home. 240 YANG feature statements are used to enable implementations to 241 advertise which potentially uncommon parts of the model the RESTCONF 242 client supports. 244 2.1. Data Model Overview 246 This section provides an overview of the "ietf-restconf-client" 247 module in terms of its features and groupings. 249 2.1.1. Features 251 The following diagram lists all the "feature" statements defined in 252 the "ietf-restconf-client" module: 254 Features: 255 +-- https-initiate 256 +-- http-listen 257 +-- https-listen 259 | The diagram above uses syntax that is similar to but not 260 | defined in [RFC8340]. 262 2.1.2. Groupings 264 The "ietf-restconf-client" module defines the following "grouping" 265 statements: 267 * restconf-client-grouping 268 * restconf-client-initiate-stack-grouping 269 * restconf-client-listen-stack-grouping 270 * restconf-client-app-grouping 272 Each of these groupings are presented in the following subsections. 274 2.1.2.1. The "restconf-client-grouping" Grouping 276 The following tree diagram [RFC8340] illustrates the "restconf- 277 client-grouping" grouping: 279 grouping restconf-client-grouping ---> 281 Comments: 283 * This grouping does not define any nodes, but is maintained so that 284 downstream modules can augment nodes into it if needed. 286 * The "restconf-client-grouping" defines, if it can be called that, 287 the configuration for just "RESTCONF" part of a protocol stack. 288 It does not, for instance, define any configuration for the "TCP", 289 "TLS", or "HTTP" protocol layers (for that, see Section 2.1.2.2 290 and Section 2.1.2.3). 292 2.1.2.2. The "restconf-client-initiate-stack-grouping" Grouping 294 The following tree diagram [RFC8340] illustrates the "restconf- 295 client-initiate-stack-grouping" grouping: 297 grouping restconf-client-initiate-stack-grouping 298 +-- (transport) 299 +--:(https) {https-initiate}? 300 +-- https 301 +-- tcp-client-parameters 302 | +---u tcpc:tcp-client-grouping 303 +-- tls-client-parameters 304 | +---u tlsc:tls-client-grouping 305 +-- http-client-parameters 306 | +---u httpc:http-client-grouping 307 +-- restconf-client-parameters 308 +---u rcc:restconf-client-grouping 310 Comments: 312 * The "restconf-client-initiate-stack-grouping" defines the 313 configuration for a full RESTCONF protocol stack, for RESTCONF 314 clients that initiate connections to RESTCONF servers, as opposed 315 to receiving call-home [RFC8071] connections. 317 * The "transport" choice node enables transport options to be 318 configured. This document only defines an "https" option, but 319 other options MAY be augmented in. 321 * For the referenced grouping statement(s): 323 - The "tcp-client-grouping" grouping is discussed in 324 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 325 - The "tls-client-grouping" grouping is discussed in 326 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 327 - The "http-client-grouping" grouping is discussed in 328 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 329 - The "restconf-client-grouping" grouping is discussed in 330 Section 2.1.2.1 in this document. 332 2.1.2.3. The "restconf-client-listen-stack-grouping" Grouping 334 The following tree diagram [RFC8340] illustrates the "restconf- 335 client-listen-stack-grouping" grouping: 337 grouping restconf-client-listen-stack-grouping 338 +-- (transport) 339 +--:(http) {http-listen}? 340 | +-- http 341 | +-- tcp-server-parameters 342 | | +---u tcps:tcp-server-grouping 343 | +-- http-client-parameters 344 | | +---u httpc:http-client-grouping 345 | +-- restconf-client-parameters 346 | +---u rcc:restconf-client-grouping 347 +--:(https) {https-listen}? 348 +-- https 349 +-- tcp-server-parameters 350 | +---u tcps:tcp-server-grouping 351 +-- tls-client-parameters 352 | +---u tlsc:tls-client-grouping 353 +-- http-client-parameters 354 | +---u httpc:http-client-grouping 355 +-- restconf-client-parameters 356 +---u rcc:restconf-client-grouping 358 Comments: 360 * The "restconf-client-listen-stack-grouping" defines the 361 configuration for a full RESTCONF protocol stack, for RESTCONF 362 clients that receive call-home [RFC8071] connections from RESTCONF 363 servers. 365 * The "transport" choice node enables both the HTTP and HTTPS 366 transports to be configured, with each option enabled by a 367 "feature" statement. Note that RESTCONF requires HTTPS, the HTTP 368 option is provided to support cases where a TLS-terminator is 369 deployed in front of the RESTCONF-client. 371 * For the referenced grouping statement(s): 373 - The "tcp-server-grouping" grouping is discussed in 374 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 375 - The "tls-client-grouping" grouping is discussed in 376 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 377 - The "http-client-grouping" grouping is discussed in 378 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 379 - The "restconf-client-grouping" grouping is discussed in 380 Section 2.1.2.1 in this document. 382 2.1.2.4. The "restconf-client-app-grouping" Grouping 384 The following tree diagram [RFC8340] illustrates the "restconf- 385 client-app-grouping" grouping: 387 grouping restconf-client-app-grouping 388 +-- initiate! {https-initiate}? 389 | +-- restconf-server* [name] 390 | +-- name? string 391 | +-- endpoints 392 | | +-- endpoint* [name] 393 | | +-- name? string 394 | | +---u restconf-client-initiate-stack-grouping 395 | +-- connection-type 396 | | +-- (connection-type) 397 | | +--:(persistent-connection) 398 | | | +-- persistent! 399 | | +--:(periodic-connection) 400 | | +-- periodic! 401 | | +-- period? uint16 402 | | +-- anchor-time? yang:date-and-time 403 | | +-- idle-timeout? uint16 404 | +-- reconnect-strategy 405 | +-- start-with? enumeration 406 | +-- max-attempts? uint8 407 +-- listen! {http-listen or https-listen}? 408 +-- idle-timeout? uint16 409 +-- endpoint* [name] 410 +-- name? string 411 +---u restconf-client-listen-stack-grouping 413 Comments: 415 * The "restconf-client-app-grouping" defines the configuration for a 416 RESTCONF client that supports both initiating connections to 417 RESTCONF servers as well as receiving call-home connections from 418 RESTCONF servers. 420 * Both the "initiate" and "listen" subtrees must be enabled by 421 "feature" statements. 423 * For the referenced grouping statement(s): 425 - The "restconf-client-initiate-stack-grouping" grouping is 426 discussed in Section 2.1.2.2 in this document. 427 - The "restconf-client-listen-stack-grouping" grouping is 428 discussed in Section 2.1.2.3 in this document. 430 2.1.3. Protocol-accessible Nodes 432 The following tree diagram [RFC8340] lists all the protocol- 433 accessible nodes defined in the "ietf-restconf-client" module: 435 module: ietf-restconf-client 436 +--rw restconf-client 437 +---u restconf-client-app-grouping 439 Comments: 441 * Protocol-accessible nodes are those nodes that are accessible when 442 the module is "implemented", as described in Section 5.6.5 of 443 [RFC7950]. 445 * For the "ietf-restconf-client" module, the protocol-accessible 446 nodes are an instance of the "restconf-client-app-grouping" 447 discussed in Section 2.1.2.4 grouping. 449 * The reason for why "restconf-client-app-grouping" exists separate 450 from the protocol-accessible nodes definition is so as to enable 451 instances of restconf-client-app-grouping to be instantiated in 452 other locations, as may be needed or desired by some modules. 454 2.2. Example Usage 456 The following example illustrates configuring a RESTCONF client to 457 initiate connections, as well as to listen for call-home connections. 459 This example is consistent with the examples presented in Section 2.2 460 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 461 [I-D.ietf-netconf-keystore]. 463 =============== NOTE: '\' line wrapping per RFC 8792 ================ 465 469 470 471 472 corp-fw1 473 474 475 corp-fw1.example.com 476 477 478 corp-fw1.example.com 479 480 15 481 3 482 30 484 485 486 487 488 489 490 rsa-asymmetric-key 492 ex-rsa-cert 493 494 495 496 497 498 trusted-server-ca-certs 500 501 502 trusted-server-ee-certs 504 505 506 507 508 30 509 3 510 511 512 513 514 515 516 bob 517 secret 518 519 520 521 522 523 524 corp-fw2.example.com 525 526 527 corp-fw2.example.com 528 529 15 530 3 531 30 533 534 535 536 537 538 539 rsa-asymmetric-key 541 ex-rsa-cert 542 543 544 545 546 547 trusted-server-ca-certs 549 550 551 trusted-server-ee-certs 553 554 555 556 557 30 558 3 559 560 561 562 563 564 565 bob 566 secret 567 568 569 570 571 572 573 574 575 576 577 579 580 581 582 Intranet-facing listener 583 584 585 11.22.33.44 586 587 588 589 590 591 rsa-asymmetric-key 592 ex-rsa-cert 593 594 595 596 597 598 trusted-server-ca-certs 600 601 602 trusted-server-ee-certs 604 605 606 607 608 609 610 611 612 613 bob 614 secret 615 616 617 618 619 620 621 623 2.3. YANG Module 625 This YANG module has normative references to [RFC6991], [RFC8040], 626 and [RFC8071], [I-D.ietf-netconf-tcp-client-server], 627 [I-D.ietf-netconf-tls-client-server], and 628 [I-D.ietf-netconf-http-client-server]. 630 file "ietf-restconf-client@2021-05-18.yang" 632 module ietf-restconf-client { 633 yang-version 1.1; 634 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 635 prefix rcc; 637 import ietf-yang-types { 638 prefix yang; 639 reference 640 "RFC 6991: Common YANG Data Types"; 641 } 643 import ietf-tcp-client { 644 prefix tcpc; 645 reference 646 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 647 } 649 import ietf-tcp-server { 650 prefix tcps; 651 reference 652 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 653 } 655 import ietf-tls-client { 656 prefix tlsc; 657 reference 658 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 659 } 661 import ietf-http-client { 662 prefix httpc; 663 reference 664 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 665 } 667 organization 668 "IETF NETCONF (Network Configuration) Working Group"; 670 contact 671 "WG Web: 672 WG List: 673 Author: Kent Watsen 674 Author: Gary Wu "; 676 description 677 "This module contains a collection of YANG definitions 678 for configuring RESTCONF clients. 680 Copyright (c) 2021 IETF Trust and the persons identified 681 as authors of the code. All rights reserved. 683 Redistribution and use in source and binary forms, with 684 or without modification, is permitted pursuant to, and 685 subject to the license terms contained in, the Simplified 686 BSD License set forth in Section 4.c of the IETF Trust's 687 Legal Provisions Relating to IETF Documents 688 (https://trustee.ietf.org/license-info). 690 This version of this YANG module is part of RFC IIII 691 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 692 itself for full legal notices. 694 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 695 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 696 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 697 are to be interpreted as described in BCP 14 (RFC 2119) 698 (RFC 8174) when, and only when, they appear in all 699 capitals, as shown here."; 701 revision 2021-05-18 { 702 description 703 "Initial version"; 704 reference 705 "RFC IIII: RESTCONF Client and Server Models"; 706 } 708 // Features 710 feature https-initiate { 711 description 712 "The 'https-initiate' feature indicates that the RESTCONF 713 client supports initiating HTTPS connections to RESTCONF 714 servers. This feature exists as HTTPS might not be a 715 mandatory to implement transport in the future."; 716 reference 717 "RFC 8040: RESTCONF Protocol"; 718 } 720 feature http-listen { 721 description 722 "The 'https-listen' feature indicates that the RESTCONF client 723 supports opening a port to listen for incoming RESTCONF 724 server call-home connections. This feature exists as not 725 all RESTCONF clients may support RESTCONF call home."; 727 reference 728 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 729 } 731 feature https-listen { 732 description 733 "The 'https-listen' feature indicates that the RESTCONF client 734 supports opening a port to listen for incoming RESTCONF 735 server call-home connections. This feature exists as not 736 all RESTCONF clients may support RESTCONF call home."; 737 reference 738 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 739 } 741 // Groupings 743 grouping restconf-client-grouping { 744 description 745 "A reusable grouping for configuring a RESTCONF client 746 without any consideration for how underlying transport 747 sessions are established. 749 This grouping currently doesn't define any nodes."; 750 } 752 grouping restconf-client-initiate-stack-grouping { 753 description 754 "A reusable grouping for configuring a RESTCONF client 755 'initiate' protocol stack for a single connection."; 757 choice transport { 758 mandatory true; 759 description 760 "Selects between available transports. This is a 761 'choice' statement so as to support additional 762 transport options to be augmented in."; 763 case https { 764 if-feature "https-initiate"; 765 container https { 766 must 'tls-client-parameters/client-identity 767 or http-client-parameters/client-identity'; 768 description 769 "Specifies HTTPS-specific transport 770 configuration."; 771 container tcp-client-parameters { 772 description 773 "A wrapper around the TCP client parameters 774 to avoid name collisions."; 776 uses tcpc:tcp-client-grouping { 777 refine "remote-port" { 778 default "443"; 779 description 780 "The RESTCONF client will attempt to 781 connect to the IANA-assigned well-known 782 port value for 'https' (443) if no value 783 is specified."; 784 } 785 } 786 } 787 container tls-client-parameters { 788 description 789 "A wrapper around the TLS client parameters 790 to avoid name collisions."; 791 uses tlsc:tls-client-grouping; 792 } 793 container http-client-parameters { 794 description 795 "A wrapper around the HTTP client parameters 796 to avoid name collisions."; 797 uses httpc:http-client-grouping; 798 } 799 container restconf-client-parameters { 800 description 801 "A wrapper around the HTTP client parameters 802 to avoid name collisions."; 803 uses rcc:restconf-client-grouping; 804 } 805 } 806 } 807 } 808 } // restconf-client-initiate-stack-grouping 810 grouping restconf-client-listen-stack-grouping { 811 description 812 "A reusable grouping for configuring a RESTCONF client 813 'listen' protocol stack for a single connection. The 814 'listen' stack supports call home connections, as 815 described in RFC 8071"; 816 reference 817 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 818 choice transport { 819 mandatory true; 820 description 821 "Selects between available transports. This is a 822 'choice' statement so as to support additional 823 transport options to be augmented in."; 825 case http { 826 if-feature "http-listen"; 827 container http { 828 description 829 "HTTP-specific listening configuration for inbound 830 connections. 832 This transport option is made available to support 833 deployments where the TLS connections are terminated 834 by another system (e.g., a load balanacer) fronting 835 the client."; 836 container tcp-server-parameters { 837 description 838 "A wrapper around the TCP client parameters 839 to avoid name collisions."; 840 uses tcps:tcp-server-grouping { 841 refine "local-port" { 842 default "4336"; 843 description 844 "The RESTCONF client will listen on the IANA- 845 assigned well-known port for 'restconf-ch-tls' 846 (4336) if no value is specified."; 847 } 848 } 849 } 850 container http-client-parameters { 851 description 852 "A wrapper around the HTTP client parameters 853 to avoid name collisions."; 854 uses httpc:http-client-grouping; 855 } 856 container restconf-client-parameters { 857 description 858 "A wrapper around the RESTCONF client parameters 859 to avoid name collisions."; 860 uses rcc:restconf-client-grouping; 861 } 862 } 863 } 864 case https { 865 if-feature "https-listen"; 866 container https { 867 must 'tls-client-parameters/client-identity 868 or http-client-parameters/client-identity'; 869 description 870 "HTTPS-specific listening configuration for inbound 871 connections."; 872 container tcp-server-parameters { 873 description 874 "A wrapper around the TCP client parameters 875 to avoid name collisions."; 876 uses tcps:tcp-server-grouping { 877 refine "local-port" { 878 default "4336"; 879 description 880 "The RESTCONF client will listen on the IANA- 881 assigned well-known port for 'restconf-ch-tls' 882 (4336) if no value is specified."; 883 } 884 } 885 } 886 container tls-client-parameters { 887 description 888 "A wrapper around the TLS client parameters 889 to avoid name collisions."; 890 uses tlsc:tls-client-grouping; 891 } 892 container http-client-parameters { 893 description 894 "A wrapper around the HTTP client parameters 895 to avoid name collisions."; 896 uses httpc:http-client-grouping; 897 } 898 container restconf-client-parameters { 899 description 900 "A wrapper around the RESTCONF client parameters 901 to avoid name collisions."; 902 uses rcc:restconf-client-grouping; 903 } 904 } 905 } 906 } 907 } // restconf-client-listen-stack-grouping 909 grouping restconf-client-app-grouping { 910 description 911 "A reusable grouping for configuring a RESTCONF client 912 application that supports both 'initiate' and 'listen' 913 protocol stacks for a multiplicity of connections."; 914 container initiate { 915 if-feature "https-initiate"; 916 presence 917 "Indicates that client-initiated connections have been 918 configured. This statement is present so the mandatory 919 descendant nodes do not imply that this node must be 920 configured."; 922 description 923 "Configures client initiating underlying TCP connections."; 924 list restconf-server { 925 key "name"; 926 min-elements 1; 927 description 928 "List of RESTCONF servers the RESTCONF client is to 929 maintain simultaneous connections with."; 930 leaf name { 931 type string; 932 description 933 "An arbitrary name for the RESTCONF server."; 934 } 935 container endpoints { 936 description 937 "Container for the list of endpoints."; 938 list endpoint { 939 key "name"; 940 min-elements 1; 941 ordered-by user; 942 description 943 "A non-empty user-ordered list of endpoints for this 944 RESTCONF client to try to connect to in sequence. 945 Defining more than one enables high-availability."; 946 leaf name { 947 type string; 948 description 949 "An arbitrary name for this endpoint."; 950 } 951 uses restconf-client-initiate-stack-grouping; 952 } 953 } 954 container connection-type { 955 description 956 "Indicates the RESTCONF client's preference for how 957 the RESTCONF connection is maintained."; 958 choice connection-type { 959 mandatory true; 960 description 961 "Selects between available connection types."; 962 case persistent-connection { 963 container persistent { 964 presence 965 "Indicates that a persistent connection is to be 966 maintained."; 967 description 968 "Maintain a persistent connection to the 969 RESTCONF server. If the connection goes down, 970 immediately start trying to reconnect to the 971 RESTCONF server, using the reconnection strategy. 973 This connection type minimizes any RESTCONF server 974 to RESTCONF client data-transfer delay, albeit 975 at the expense of holding resources longer."; 976 } 977 } 978 case periodic-connection { 979 container periodic { 980 presence 981 "Indicates that a periodic connection is to be 982 maintained."; 983 description 984 "Periodically connect to the RESTCONF server. 986 This connection type increases resource 987 utilization, albeit with increased delay 988 in RESTCONF server to RESTCONF client 989 interactions. 991 The RESTCONF client SHOULD gracefully close 992 the underlying TLS connection upon completing 993 planned activities. 995 In the case that the previous connection is 996 still active, establishing a new connection 997 is NOT RECOMMENDED."; 998 leaf period { 999 type uint16; 1000 units "minutes"; 1001 default "60"; 1002 description 1003 "Duration of time between periodic 1004 connections."; 1005 } 1006 leaf anchor-time { 1007 type yang:date-and-time { 1008 // constrained to minute-level granularity 1009 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1010 + '(Z|[\+\-]\d{2}:\d{2})'; 1011 } 1012 description 1013 "Designates a timestamp before or after which 1014 a series of periodic connections are 1015 determined. The periodic connections occur 1016 at a whole multiple interval from the anchor 1017 time. For example, for an anchor time is 15 1018 minutes past midnight and a period interval 1019 of 24 hours, then a periodic connection will 1020 occur 15 minutes past midnight everyday."; 1021 } 1022 leaf idle-timeout { 1023 type uint16; 1024 units "seconds"; 1025 default "120"; // two minutes 1026 description 1027 "Specifies the maximum number of seconds 1028 that the underlying TCP session may remain 1029 idle. A TCP session will be dropped if it 1030 is idle for an interval longer than this 1031 number of seconds If set to zero, then the 1032 RESTCONF client will never drop a session 1033 because it is idle."; 1034 } 1035 } 1036 } // periodic-connection 1037 } // connection-type 1038 } // connection-type 1039 container reconnect-strategy { 1040 description 1041 "The reconnection strategy directs how a RESTCONF 1042 client reconnects to a RESTCONF server, after 1043 discovering its connection to the server has 1044 dropped, even if due to a reboot. The RESTCONF 1045 client starts with the specified endpoint and 1046 tries to connect to it max-attempts times before 1047 trying the next endpoint in the list (round 1048 robin)."; 1049 leaf start-with { 1050 type enumeration { 1051 enum first-listed { 1052 description 1053 "Indicates that reconnections should start 1054 with the first endpoint listed."; 1055 } 1056 enum last-connected { 1057 description 1058 "Indicates that reconnections should start 1059 with the endpoint last connected to. If 1060 no previous connection has ever been 1061 established, then the first endpoint 1062 configured is used. RESTCONF clients 1063 SHOULD be able to remember the last 1064 endpoint connected to across reboots."; 1065 } 1066 enum random-selection { 1067 description 1068 "Indicates that reconnections should start with 1069 a random endpoint."; 1070 } 1071 } 1072 default "first-listed"; 1073 description 1074 "Specifies which of the RESTCONF server's 1075 endpoints the RESTCONF client should start 1076 with when trying to connect to the RESTCONF 1077 server."; 1078 } 1079 leaf max-attempts { 1080 type uint8 { 1081 range "1..max"; 1082 } 1083 default "3"; 1084 description 1085 "Specifies the number times the RESTCONF client 1086 tries to connect to a specific endpoint before 1087 moving on to the next endpoint in the list 1088 (round robin)."; 1089 } 1090 } 1091 } 1092 } // initiate 1093 container listen { 1094 if-feature "http-listen or https-listen"; 1095 presence 1096 "Indicates that client-listening ports have been configured. 1097 This statement is present so the mandatory descendant nodes 1098 do not imply that this node must be configured."; 1099 description 1100 "Configures the client to accept call-home TCP connections."; 1101 leaf idle-timeout { 1102 type uint16; 1103 units "seconds"; 1104 default "3600"; // one hour 1105 description 1106 "Specifies the maximum number of seconds that an 1107 underlying TCP session may remain idle. A TCP session 1108 will be dropped if it is idle for an interval longer 1109 then this number of seconds. If set to zero, then 1110 the server will never drop a session because it is 1111 idle. Sessions that have a notification subscription 1112 active are never dropped."; 1113 } 1114 list endpoint { 1115 key "name"; 1116 min-elements 1; 1117 description 1118 "List of endpoints to listen for RESTCONF connections."; 1119 leaf name { 1120 type string; 1121 description 1122 "An arbitrary name for the RESTCONF listen endpoint."; 1123 } 1124 uses restconf-client-listen-stack-grouping; 1125 } 1126 } 1127 } // restconf-client-app-grouping 1129 // Protocol accessible node for servers that implement this module. 1130 container restconf-client { 1131 uses restconf-client-app-grouping; 1132 description 1133 "Top-level container for RESTCONF client configuration."; 1134 } 1135 } 1137 1139 3. The "ietf-restconf-server" Module 1141 The RESTCONF server model presented in this section supports both 1142 listening for connections as well as initiating call-home 1143 connections. 1145 YANG feature statements are used to enable implementations to 1146 advertise which potentially uncommon parts of the model the RESTCONF 1147 server supports. 1149 3.1. Data Model Overview 1151 This section provides an overview of the "ietf-restconf-server" 1152 module in terms of its features and groupings. 1154 3.1.1. Features 1156 The following diagram lists all the "feature" statements defined in 1157 the "ietf-restconf-server" module: 1159 Features: 1160 +-- http-listen 1161 +-- https-listen 1162 +-- https-call-home 1164 | The diagram above uses syntax that is similar to but not 1165 | defined in [RFC8340]. 1167 3.1.2. Groupings 1169 The "ietf-restconf-server" module defines the following "grouping" 1170 statements: 1172 * restconf-server-grouping 1173 * restconf-server-listen-stack-grouping 1174 * restconf-server-callhome-stack-grouping 1175 * restconf-server-app-grouping 1177 Each of these groupings are presented in the following subsections. 1179 3.1.2.1. The "restconf-server-grouping" Grouping 1181 The following tree diagram [RFC8340] illustrates the "restconf- 1182 server-grouping" grouping: 1184 grouping restconf-server-grouping 1185 +-- client-identity-mappings 1186 +---u x509c2n:cert-to-name 1188 Comments: 1190 * The "restconf-server-grouping" defines the configuration for just 1191 "RESTCONF" part of a protocol stack. It does not, for instance, 1192 define any configuration for the "TCP", "TLS", or "HTTP" protocol 1193 layers (for that, see Section 3.1.2.2 and Section 3.1.2.3). 1195 * The "client-identity-mappings" node, which must be enabled by 1196 "feature" statements, defines a mapping from certificate fields to 1197 RESTCONF user names. 1199 * For the referenced grouping statement(s): 1201 - The "cert-to-name" grouping is discussed in Section 4.1 of 1202 [RFC7407]. 1204 3.1.2.2. The "restconf-server-listen-stack-grouping" Grouping 1206 The following tree diagram [RFC8340] illustrates the "restconf- 1207 server-listen-stack-grouping" grouping: 1209 grouping restconf-server-listen-stack-grouping 1210 +-- (transport) 1211 +--:(http) {http-listen}? 1212 | +-- http 1213 | +-- external-endpoint! 1214 | | +-- address inet:ip-address 1215 | | +-- port? inet:port-number 1216 | +-- tcp-server-parameters 1217 | | +---u tcps:tcp-server-grouping 1218 | +-- http-server-parameters 1219 | | +---u https:http-server-grouping 1220 | +-- restconf-server-parameters 1221 | +---u rcs:restconf-server-grouping 1222 +--:(https) {https-listen}? 1223 +-- https 1224 +-- tcp-server-parameters 1225 | +---u tcps:tcp-server-grouping 1226 +-- tls-server-parameters 1227 | +---u tlss:tls-server-grouping 1228 +-- http-server-parameters 1229 | +---u https:http-server-grouping 1230 +-- restconf-server-parameters 1231 +---u rcs:restconf-server-grouping 1233 Comments: 1235 * The "restconf-server-listen-stack-grouping" defines the 1236 configuration for a full RESTCONF protocol stack for RESTCONF 1237 servers that listen for standard connections from RESTCONF 1238 clients, as opposed to initiating call-home [RFC8071] connections. 1240 * The "transport" choice node enables both the HTTP and HTTPS 1241 transports to be configured, with each option enabled by a 1242 "feature" statement. The HTTP option is provided to support cases 1243 where a TLS-terminator is deployed in front of the RESTCONF- 1244 server. 1246 * For the referenced grouping statement(s): 1248 - The "tcp-server-grouping" grouping is discussed in 1249 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1250 - The "tls-server-grouping" grouping is discussed in 1251 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1253 - The "http-server-grouping" grouping is discussed in 1254 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1255 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1256 of this document. 1258 3.1.2.3. The "restconf-server-callhome-stack-grouping" Grouping 1260 The following tree diagram [RFC8340] illustrates the "restconf- 1261 server-callhome-stack-grouping" grouping: 1263 grouping restconf-server-callhome-stack-grouping 1264 +-- (transport) 1265 +--:(https) {https-listen}? 1266 +-- https 1267 +-- tcp-client-parameters 1268 | +---u tcpc:tcp-client-grouping 1269 +-- tls-server-parameters 1270 | +---u tlss:tls-server-grouping 1271 +-- http-server-parameters 1272 | +---u https:http-server-grouping 1273 +-- restconf-server-parameters 1274 +---u rcs:restconf-server-grouping 1276 Comments: 1278 * The "restconf-server-callhome-stack-grouping" defines the 1279 configuration for a full RESTCONF protocol stack, for RESTCONF 1280 servers that initiate call-home [RFC8071] connections to RESTCONF 1281 clients. 1283 * The "transport" choice node enables transport options to be 1284 configured. This document only defines an "https" option, but 1285 other options MAY be augmented in. 1287 * For the referenced grouping statement(s): 1289 - The "tcp-client-grouping" grouping is discussed in 1290 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1291 - The "tls-server-grouping" grouping is discussed in 1292 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1293 - The "http-server-grouping" grouping is discussed in 1294 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1295 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1296 of this document. 1298 3.1.2.4. The "restconf-server-app-grouping" Grouping 1300 The following tree diagram [RFC8340] illustrates the "restconf- 1301 server-app-grouping" grouping: 1303 grouping restconf-server-app-grouping 1304 +-- listen! {http-listen or https-listen}? 1305 | +-- endpoint* [name] 1306 | +-- name? string 1307 | +---u restconf-server-listen-stack-grouping 1308 +-- call-home! {https-call-home}? 1309 +-- restconf-client* [name] 1310 +-- name? string 1311 +-- endpoints 1312 | +-- endpoint* [name] 1313 | +-- name? string 1314 | +---u restconf-server-callhome-stack-grouping 1315 +-- connection-type 1316 | +-- (connection-type) 1317 | +--:(persistent-connection) 1318 | | +-- persistent! 1319 | +--:(periodic-connection) 1320 | +-- periodic! 1321 | +-- period? uint16 1322 | +-- anchor-time? yang:date-and-time 1323 | +-- idle-timeout? uint16 1324 +-- reconnect-strategy 1325 +-- start-with? enumeration 1326 +-- max-attempts? uint8 1328 Comments: 1330 * The "restconf-server-app-grouping" defines the configuration for a 1331 RESTCONF server that supports both listening for connections from 1332 RESTCONF clients as well as initiating call-home connections to 1333 RESTCONF clients. 1335 * Both the "listen" and "call-home" subtrees must be enabled by 1336 "feature" statements. 1338 * For the referenced grouping statement(s): 1340 - The "restconf-server-listen-stack-grouping" grouping is 1341 discussed in Section 3.1.2.2 in this document. 1342 - The "restconf-server-callhome-stack-grouping" grouping is 1343 discussed in Section 3.1.2.3 in this document. 1345 3.1.3. Protocol-accessible Nodes 1347 The following tree diagram [RFC8340] lists all the protocol- 1348 accessible nodes defined in the "ietf-restconf-server" module: 1350 module: ietf-restconf-server 1351 +--rw restconf-server 1352 +---u restconf-server-app-grouping 1354 Comments: 1356 * Protocol-accessible nodes are those nodes that are accessible when 1357 the module is "implemented", as described in Section 5.6.5 of 1358 [RFC7950]. 1360 * For the "ietf-restconf-server" module, the protocol-accessible 1361 nodes are an instance of the "restconf-server-app-grouping" 1362 discussed in Section 3.1.2.4 grouping. 1364 * The reason for why "restconf-server-app-grouping" exists separate 1365 from the protocol-accessible nodes definition is so as to enable 1366 instances of restconf-server-app-grouping to be instantiated in 1367 other locations, as may be needed or desired by some modules. 1369 3.2. Example Usage 1371 The following example illustrates configuring a RESTCONF server to 1372 listen for RESTCONF client connections, as well as configuring call- 1373 home to one RESTCONF client. 1375 This example is consistent with the examples presented in Section 2.2 1376 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 1377 [I-D.ietf-netconf-keystore]. 1379 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1381 1386 1387 1388 1389 restconf/https 1390 1391 1392 11.22.33.44 1394 1395 1396 1397 1398 1399 rsa-asymmetric-key 1400 ex-rsa-cert 1401 1402 1403 1404 1405 1406 trusted-client-ca-certs 1408 1409 1410 trusted-client-ee-certs 1412 1413 1414 1415 1416 1417 1418 1419 foo.example.com 1420 1421 1422 1423 1424 1 1425 11:0A:05:11:00 1426 x509c2n:specified 1427 scooby-doo 1428 1429 1430 2 1431 x509c2n:san-any 1432 1433 1434 1435 1436 1437 1439 1440 1441 1442 config-manager 1443 1444 1445 east-data-center 1446 1447 1448 east.example.com 1449 1450 15 1451 3 1452 30 1453 1454 1455 1456 1457 1458 1459 rsa-asymmetric-key 1461 ex-rsa-cert 1462 1463 1464 1465 1466 1467 trusted-client-ca-certs 1469 1470 1471 trusted-client-ee-certs 1473 1474 1475 1476 1477 30 1478 3 1479 1480 1481 1482 1483 foo.example.com 1484 1485 1486 1487 1488 1 1489 11:0A:05:11:00 1490 x509c2n:specified 1491 scooby-doo 1492 1493 1494 2 1495 x509c2n:san-any 1496 1497 1498 1499 1500 1501 1502 west-data-center 1503 1504 1505 west.example.com 1506 1507 15 1508 3 1509 30 1510 1511 1512 1513 1514 1515 1516 rsa-asymmetric-key 1518 ex-rsa-cert 1519 1520 1521 1522 1523 1524 trusted-client-ca-certs 1526 1527 1528 trusted-client-ee-certs 1530 1531 1532 1533 1534 30 1535 3 1536 1537 1539 1540 1541 foo.example.com 1542 1543 1544 1545 1546 1 1547 11:0A:05:11:00 1548 x509c2n:specified 1549 scooby-doo 1550 1551 1552 2 1553 x509c2n:san-any 1554 1555 1556 1557 1558 1559 1560 1561 1562 300 1563 60 1564 1565 1566 1567 last-connected 1568 3 1569 1570 1571 1572 1574 3.3. YANG Module 1576 This YANG module has normative references to [RFC6991], [RFC7407], 1577 [RFC8040], [RFC8071], [I-D.ietf-netconf-tcp-client-server], 1578 [I-D.ietf-netconf-tls-client-server], and 1579 [I-D.ietf-netconf-http-client-server]. 1581 file "ietf-restconf-server@2021-05-18.yang" 1582 module ietf-restconf-server { 1583 yang-version 1.1; 1584 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1585 prefix rcs; 1587 import ietf-yang-types { 1588 prefix yang; 1589 reference 1590 "RFC 6991: Common YANG Data Types"; 1591 } 1593 import ietf-inet-types { 1594 prefix inet; 1595 reference 1596 "RFC 6991: Common YANG Data Types"; 1597 } 1599 import ietf-x509-cert-to-name { 1600 prefix x509c2n; 1601 reference 1602 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1603 } 1605 import ietf-tcp-client { 1606 prefix tcpc; 1607 reference 1608 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1609 } 1611 import ietf-tcp-server { 1612 prefix tcps; 1613 reference 1614 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1615 } 1617 import ietf-tls-server { 1618 prefix tlss; 1619 reference 1620 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1621 } 1623 import ietf-http-server { 1624 prefix https; 1625 reference 1626 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 1627 } 1629 organization 1630 "IETF NETCONF (Network Configuration) Working Group"; 1632 contact 1633 "WG Web: 1634 WG List: 1635 Author: Kent Watsen 1636 Author: Gary Wu 1637 Author: Juergen Schoenwaelder 1638 "; 1640 description 1641 "This module contains a collection of YANG definitions 1642 for configuring RESTCONF servers. 1644 Copyright (c) 2021 IETF Trust and the persons identified 1645 as authors of the code. All rights reserved. 1647 Redistribution and use in source and binary forms, with 1648 or without modification, is permitted pursuant to, and 1649 subject to the license terms contained in, the Simplified 1650 BSD License set forth in Section 4.c of the IETF Trust's 1651 Legal Provisions Relating to IETF Documents 1652 (https://trustee.ietf.org/license-info). 1654 This version of this YANG module is part of RFC IIII 1655 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 1656 itself for full legal notices. 1658 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1659 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1660 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1661 are to be interpreted as described in BCP 14 (RFC 2119) 1662 (RFC 8174) when, and only when, they appear in all 1663 capitals, as shown here."; 1665 revision 2021-05-18 { 1666 description 1667 "Initial version"; 1668 reference 1669 "RFC IIII: RESTCONF Client and Server Models"; 1670 } 1672 // Features 1674 feature http-listen { 1675 description 1676 "The 'http-listen' feature indicates that the RESTCONF server 1677 supports opening a port to listen for incoming RESTCONF over 1678 TPC client connections, whereby the TLS connections are 1679 terminated by an external system."; 1680 reference 1681 "RFC 8040: RESTCONF Protocol"; 1682 } 1684 feature https-listen { 1685 description 1686 "The 'https-listen' feature indicates that the RESTCONF server 1687 supports opening a port to listen for incoming RESTCONF over 1688 TLS client connections, whereby the TLS connections are 1689 terminated by the server itself."; 1690 reference 1691 "RFC 8040: RESTCONF Protocol"; 1692 } 1694 feature https-call-home { 1695 description 1696 "The 'https-call-home' feature indicates that the RESTCONF 1697 server supports initiating connections to RESTCONF clients."; 1698 reference 1699 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1700 } 1702 // Groupings 1704 grouping restconf-server-grouping { 1705 description 1706 "A reusable grouping for configuring a RESTCONF server 1707 without any consideration for how underlying transport 1708 sessions are established. 1710 Note that this grouping uses a fairly typical descendant 1711 node name such that a stack of 'uses' statements will 1712 have name conflicts. It is intended that the consuming 1713 data model will resolve the issue by wrapping the 'uses' 1714 statement in a container called, e.g., 1715 'restconf-server-parameters'. This model purposely does 1716 not do this itself so as to provide maximum flexibility 1717 to consuming models."; 1719 container client-identity-mappings { 1720 description 1721 "Specifies mappings through which RESTCONF client X.509 1722 certificates are used to determine a RESTCONF username. 1723 If no matching and valid cert-to-name list entry can be 1724 found, then the RESTCONF server MUST close the connection, 1725 and MUST NOT accept RESTCONF messages over it."; 1727 reference 1728 "RFC 7407: A YANG Data Model for SNMP Configuration."; 1729 uses x509c2n:cert-to-name { 1730 refine "cert-to-name/fingerprint" { 1731 mandatory false; 1732 description 1733 "A 'fingerprint' value does not need to be specified 1734 when the 'cert-to-name' mapping is independent of 1735 fingerprint matching. A 'cert-to-name' having no 1736 fingerprint value will match any client certificate 1737 and therefore should only be present at the end of 1738 the user-ordered 'cert-to-name' list."; 1739 } 1740 } 1741 } 1742 } 1744 grouping restconf-server-listen-stack-grouping { 1745 description 1746 "A reusable grouping for configuring a RESTCONF server 1747 'listen' protocol stack for a single connection."; 1748 choice transport { 1749 mandatory true; 1750 description 1751 "Selects between available transports. This is a 1752 'choice' statement so as to support additional 1753 transport options to be augmented in."; 1754 case http { 1755 if-feature "http-listen"; 1756 container http { 1757 description 1758 "Configures RESTCONF server stack assuming that 1759 TLS-termination is handled externally."; 1760 container external-endpoint { 1761 presence 1762 "Identifies that an external endpoint has been 1763 configured. This statement is present so the 1764 mandatory descendant nodes do not imply that 1765 this node must be configured."; 1766 description 1767 "Identifies contact information for the external 1768 system that terminates connections before passing 1769 them thru to this server (e.g., a network address 1770 translator or a load balancer). These values have 1771 no effect on the local operation of this server, 1772 but may be used by the application when needing to 1773 inform other systems how to contact this server."; 1774 leaf address { 1775 type inet:ip-address; 1776 mandatory true; 1777 description 1778 "The IP address or hostname of the external system 1779 that terminates incoming RESTCONF client 1780 connections before forwarding them to this 1781 server."; 1782 } 1783 leaf port { 1784 type inet:port-number; 1785 default "443"; 1786 description 1787 "The port number that the external system listens 1788 on for incoming RESTCONF client connections that 1789 are forwarded to this server. The default HTTPS 1790 port (443) is used, as expected for a RESTCONF 1791 connection."; 1792 } 1793 } 1794 container tcp-server-parameters { 1795 description 1796 "A wrapper around the TCP server parameters 1797 to avoid name collisions."; 1798 uses tcps:tcp-server-grouping { 1799 refine "local-port" { 1800 default "80"; 1801 description 1802 "The RESTCONF server will listen on the IANA- 1803 assigned well-known port value for 'http' 1804 (80) if no value is specified."; 1805 } 1806 } 1807 } 1808 container http-server-parameters { 1809 description 1810 "A wrapper around the HTTP server parameters 1811 to avoid name collisions."; 1812 uses https:http-server-grouping; 1813 } 1814 container restconf-server-parameters { 1815 description 1816 "A wrapper around the RESTCONF server parameters 1817 to avoid name collisions."; 1818 uses rcs:restconf-server-grouping; 1819 } 1820 } 1821 } 1822 case https { 1823 if-feature "https-listen"; 1824 container https { 1825 description 1826 "Configures RESTCONF server stack assuming that 1827 TLS-termination is handled internally."; 1828 container tcp-server-parameters { 1829 description 1830 "A wrapper around the TCP server parameters 1831 to avoid name collisions."; 1832 uses tcps:tcp-server-grouping { 1833 refine "local-port" { 1834 default "443"; 1835 description 1836 "The RESTCONF server will listen on the IANA- 1837 assigned well-known port value for 'https' 1838 (443) if no value is specified."; 1839 } 1840 } 1841 } 1842 container tls-server-parameters { 1843 description 1844 "A wrapper around the TLS server parameters 1845 to avoid name collisions."; 1846 uses tlss:tls-server-grouping; 1847 } 1848 container http-server-parameters { 1849 description 1850 "A wrapper around the HTTP server parameters 1851 to avoid name collisions."; 1852 uses https:http-server-grouping; 1853 } 1854 container restconf-server-parameters { 1855 description 1856 "A wrapper around the RESTCONF server parameters 1857 to avoid name collisions."; 1858 uses rcs:restconf-server-grouping; 1859 } 1860 } 1861 } 1862 } 1863 } 1865 grouping restconf-server-callhome-stack-grouping { 1866 description 1867 "A reusable grouping for configuring a RESTCONF server 1868 'call-home' protocol stack, for a single connection."; 1869 choice transport { 1870 mandatory true; 1871 description 1872 "Selects between available transports. This is a 1873 'choice' statement so as to support additional 1874 transport options to be augmented in."; 1875 case https { 1876 if-feature "https-listen"; 1877 container https { 1878 description 1879 "Configures RESTCONF server stack assuming that 1880 TLS-termination is handled internally."; 1881 container tcp-client-parameters { 1882 description 1883 "A wrapper around the TCP client parameters 1884 to avoid name collisions."; 1885 uses tcpc:tcp-client-grouping { 1886 refine "remote-port" { 1887 default "4336"; 1888 description 1889 "The RESTCONF server will attempt to 1890 connect to the IANA-assigned well-known 1891 port for 'restconf-ch-tls' (4336) if no 1892 value is specified."; 1893 } 1894 } 1895 } 1896 container tls-server-parameters { 1897 description 1898 "A wrapper around the TLS server parameters 1899 to avoid name collisions."; 1900 uses tlss:tls-server-grouping; 1901 } 1902 container http-server-parameters { 1903 description 1904 "A wrapper around the HTTP server parameters 1905 to avoid name collisions."; 1906 uses https:http-server-grouping; 1907 } 1908 container restconf-server-parameters { 1909 description 1910 "A wrapper around the RESTCONF server parameters 1911 to avoid name collisions."; 1912 uses rcs:restconf-server-grouping; 1913 } 1914 } 1915 } 1916 } 1917 } 1918 grouping restconf-server-app-grouping { 1919 description 1920 "A reusable grouping for configuring a RESTCONF server 1921 application that supports both 'listen' and 'call-home' 1922 protocol stacks for a multiplicity of connections."; 1923 container listen { 1924 if-feature "http-listen or https-listen"; 1925 presence 1926 "Identifies that the server has been configured to 1927 listen for incoming client connections. This statement 1928 is present so the mandatory descendant nodes do not 1929 imply that this node must be configured."; 1930 description 1931 "Configures the RESTCONF server to listen for RESTCONF 1932 client connections."; 1933 list endpoint { 1934 key "name"; 1935 min-elements 1; 1936 description 1937 "List of endpoints to listen for RESTCONF connections."; 1938 leaf name { 1939 type string; 1940 description 1941 "An arbitrary name for the RESTCONF listen endpoint."; 1942 } 1943 uses restconf-server-listen-stack-grouping; 1944 } 1945 } 1946 container call-home { 1947 if-feature "https-call-home"; 1948 presence 1949 "Identifies that the server has been configured to initiate 1950 call home connections. This statement is present so the 1951 mandatory descendant nodes do not imply that this node 1952 must be configured."; 1953 description 1954 "Configures the RESTCONF server to initiate the underlying 1955 transport connection to RESTCONF clients."; 1956 list restconf-client { 1957 key "name"; 1958 min-elements 1; 1959 description 1960 "List of RESTCONF clients the RESTCONF server is to 1961 maintain simultaneous call-home connections with."; 1962 leaf name { 1963 type string; 1964 description 1965 "An arbitrary name for the remote RESTCONF client."; 1967 } 1968 container endpoints { 1969 description 1970 "Container for the list of endpoints."; 1971 list endpoint { 1972 key "name"; 1973 min-elements 1; 1974 ordered-by user; 1975 description 1976 "User-ordered list of endpoints for this RESTCONF 1977 client. Defining more than one enables high- 1978 availability."; 1979 leaf name { 1980 type string; 1981 description 1982 "An arbitrary name for this endpoint."; 1983 } 1984 uses restconf-server-callhome-stack-grouping; 1985 } 1986 } 1987 container connection-type { 1988 description 1989 "Indicates the RESTCONF server's preference for how the 1990 RESTCONF connection is maintained."; 1991 choice connection-type { 1992 mandatory true; 1993 description 1994 "Selects between available connection types."; 1995 case persistent-connection { 1996 container persistent { 1997 presence 1998 "Indicates that a persistent connection is to be 1999 maintained."; 2000 description 2001 "Maintain a persistent connection to the RESTCONF 2002 client. If the connection goes down, immediately 2003 start trying to reconnect to the RESTCONF server, 2004 using the reconnection strategy. 2006 This connection type minimizes any RESTCONF 2007 client to RESTCONF server data-transfer delay, 2008 albeit at the expense of holding resources 2009 longer."; 2010 } 2011 } 2012 case periodic-connection { 2013 container periodic { 2014 presence 2015 "Indicates that a periodic connection is to be 2016 maintained."; 2017 description 2018 "Periodically connect to the RESTCONF client. 2020 This connection type increases resource 2021 utilization, albeit with increased delay in 2022 RESTCONF client to RESTCONF client interactions. 2024 The RESTCONF client SHOULD gracefully close 2025 the underlying TLS connection upon completing 2026 planned activities. If the underlying TLS 2027 connection is not closed gracefully, the 2028 RESTCONF server MUST immediately attempt 2029 to reestablish the connection. 2031 In the case that the previous connection is 2032 still active (i.e., the RESTCONF client has not 2033 closed it yet), establishing a new connection 2034 is NOT RECOMMENDED."; 2036 leaf period { 2037 type uint16; 2038 units "minutes"; 2039 default "60"; 2040 description 2041 "Duration of time between periodic connections."; 2042 } 2043 leaf anchor-time { 2044 type yang:date-and-time { 2045 // constrained to minute-level granularity 2046 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2047 + '(Z|[\+\-]\d{2}:\d{2})'; 2048 } 2049 description 2050 "Designates a timestamp before or after which a 2051 series of periodic connections are determined. 2052 The periodic connections occur at a whole 2053 multiple interval from the anchor time. For 2054 example, for an anchor time is 15 minutes past 2055 midnight and a period interval of 24 hours, then 2056 a periodic connection will occur 15 minutes past 2057 midnight everyday."; 2058 } 2059 leaf idle-timeout { 2060 type uint16; 2061 units "seconds"; 2062 default "120"; // two minutes 2063 description 2064 "Specifies the maximum number of seconds that 2065 the underlying TCP session may remain idle. 2066 A TCP session will be dropped if it is idle 2067 for an interval longer than this number of 2068 seconds. If set to zero, then the server 2069 will never drop a session because it is idle."; 2070 } 2071 } 2072 } 2073 } 2074 } 2075 container reconnect-strategy { 2076 description 2077 "The reconnection strategy directs how a RESTCONF server 2078 reconnects to a RESTCONF client after discovering its 2079 connection to the client has dropped, even if due to a 2080 reboot. The RESTCONF server starts with the specified 2081 endpoint and tries to connect to it max-attempts times 2082 before trying the next endpoint in the list (round 2083 robin)."; 2084 leaf start-with { 2085 type enumeration { 2086 enum first-listed { 2087 description 2088 "Indicates that reconnections should start with 2089 the first endpoint listed."; 2090 } 2091 enum last-connected { 2092 description 2093 "Indicates that reconnections should start with 2094 the endpoint last connected to. If no previous 2095 connection has ever been established, then the 2096 first endpoint configured is used. RESTCONF 2097 servers SHOULD be able to remember the last 2098 endpoint connected to across reboots."; 2099 } 2100 enum random-selection { 2101 description 2102 "Indicates that reconnections should start with 2103 a random endpoint."; 2104 } 2105 } 2106 default "first-listed"; 2107 description 2108 "Specifies which of the RESTCONF client's endpoints 2109 the RESTCONF server should start with when trying 2110 to connect to the RESTCONF client."; 2112 } 2113 leaf max-attempts { 2114 type uint8 { 2115 range "1..max"; 2116 } 2117 default "3"; 2118 description 2119 "Specifies the number times the RESTCONF server tries 2120 to connect to a specific endpoint before moving on to 2121 the next endpoint in the list (round robin)."; 2122 } 2123 } 2124 } // restconf-client 2125 } // call-home 2126 } // restconf-server-app-grouping 2128 // Protocol accessible node for servers that implement this module. 2129 container restconf-server { 2130 uses restconf-server-app-grouping; 2131 description 2132 "Top-level container for RESTCONF server configuration."; 2133 } 2134 } 2136 2138 4. Security Considerations 2140 4.1. The "ietf-restconf-client" YANG Module 2142 The "ietf-restconf-client" YANG module defines data nodes that are 2143 designed to be accessed via YANG based management protocols, such as 2144 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2145 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2146 with mutual authentication. 2148 The NETCONF access control model (NACM) [RFC8341] provides the means 2149 to restrict access for particular users to a pre-configured subset of 2150 all available protocol operations and content. 2152 None of the readable data nodes in this YANG module are considered 2153 sensitive or vulnerable in network environments. The NACM "default- 2154 deny-all" extension has not been set for any data nodes defined in 2155 this module. 2157 None of the writable data nodes in this YANG module are considered 2158 sensitive or vulnerable in network environments. The NACM "default- 2159 deny-write" extension has not been set for any data nodes defined in 2160 this module. 2162 This module does not define any RPCs, actions, or notifications, and 2163 thus the security consideration for such is not provided here. 2165 Please be aware that this module uses groupings defined in other RFCs 2166 that define data nodes that do set the NACM "default-deny-all" and 2167 "default-deny-write" extensions. 2169 4.2. The "ietf-restconf-server" YANG Module 2171 The "ietf-restconf-server" YANG module defines data nodes that are 2172 designed to be accessed via YANG based management protocols, such as 2173 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2174 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2175 with mutual authentication. 2177 The NETCONF access control model (NACM) [RFC8341] provides the means 2178 to restrict access for particular users to a pre-configured subset of 2179 all available protocol operations and content. 2181 None of the readable data nodes in this YANG module are considered 2182 sensitive or vulnerable in network environments. The NACM "default- 2183 deny-all" extension has not been set for any data nodes defined in 2184 this module. 2186 None of the writable data nodes in this YANG module are considered 2187 sensitive or vulnerable in network environments. The NACM "default- 2188 deny-write" extension has not been set for any data nodes defined in 2189 this module. 2191 This module does not define any RPCs, actions, or notifications, and 2192 thus the security consideration for such is not provided here. 2194 Please be aware that this module uses groupings defined in other RFCs 2195 that define data nodes that do set the NACM "default-deny-all" and 2196 "default-deny-write" extensions. 2198 5. IANA Considerations 2200 5.1. The "IETF XML" Registry 2202 This document registers two URIs in the "ns" subregistry of the IETF 2203 XML Registry [RFC3688]. Following the format in [RFC3688], the 2204 following registrations are requested: 2206 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2207 Registrant Contact: The IESG 2208 XML: N/A, the requested URI is an XML namespace. 2210 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2211 Registrant Contact: The IESG 2212 XML: N/A, the requested URI is an XML namespace. 2214 5.2. The "YANG Module Names" Registry 2216 This document registers two YANG modules in the YANG Module Names 2217 registry [RFC6020]. Following the format in [RFC6020], the following 2218 registrations are requested: 2220 name: ietf-restconf-client 2221 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2222 prefix: ncc 2223 reference: RFC IIII 2225 name: ietf-restconf-server 2226 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2227 prefix: ncs 2228 reference: RFC IIII 2230 6. References 2232 6.1. Normative References 2234 [I-D.ietf-netconf-http-client-server] 2235 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2236 Servers", Work in Progress, Internet-Draft, draft-ietf- 2237 netconf-http-client-server-06, 10 February 2021, 2238 . 2241 [I-D.ietf-netconf-keystore] 2242 Watsen, K., "A YANG Data Model for a Keystore", Work in 2243 Progress, Internet-Draft, draft-ietf-netconf-keystore-21, 2244 10 February 2021, . 2247 [I-D.ietf-netconf-tcp-client-server] 2248 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2249 and TCP Servers", Work in Progress, Internet-Draft, draft- 2250 ietf-netconf-tcp-client-server-09, 10 February 2021, 2251 . 2254 [I-D.ietf-netconf-tls-client-server] 2255 Watsen, K., "YANG Groupings for TLS Clients and TLS 2256 Servers", Work in Progress, Internet-Draft, draft-ietf- 2257 netconf-tls-client-server-23, 10 February 2021, 2258 . 2261 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2262 Requirement Levels", BCP 14, RFC 2119, 2263 DOI 10.17487/RFC2119, March 1997, 2264 . 2266 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2267 the Network Configuration Protocol (NETCONF)", RFC 6020, 2268 DOI 10.17487/RFC6020, October 2010, 2269 . 2271 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2272 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2273 . 2275 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2276 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2277 December 2014, . 2279 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2280 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2281 . 2283 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2284 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2285 . 2287 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2288 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2289 . 2291 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2292 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2293 May 2017, . 2295 6.2. Informative References 2297 [I-D.ietf-netconf-crypto-types] 2298 Watsen, K., "YANG Data Types and Groupings for 2299 Cryptography", Work in Progress, Internet-Draft, draft- 2300 ietf-netconf-crypto-types-19, 10 February 2021, 2301 . 2304 [I-D.ietf-netconf-netconf-client-server] 2305 Watsen, K., "NETCONF Client and Server Models", Work in 2306 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2307 client-server-22, 10 February 2021, 2308 . 2311 [I-D.ietf-netconf-restconf-client-server] 2312 Watsen, K., "RESTCONF Client and Server Models", Work in 2313 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2314 client-server-22, 10 February 2021, 2315 . 2318 [I-D.ietf-netconf-ssh-client-server] 2319 Watsen, K., "YANG Groupings for SSH Clients and SSH 2320 Servers", Work in Progress, Internet-Draft, draft-ietf- 2321 netconf-ssh-client-server-23, 10 February 2021, 2322 . 2325 [I-D.ietf-netconf-trust-anchors] 2326 Watsen, K., "A YANG Data Model for a Truststore", Work in 2327 Progress, Internet-Draft, draft-ietf-netconf-trust- 2328 anchors-14, 10 February 2021, 2329 . 2332 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2333 DOI 10.17487/RFC3688, January 2004, 2334 . 2336 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2337 and A. Bierman, Ed., "Network Configuration Protocol 2338 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2339 . 2341 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2342 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2343 . 2345 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2346 Access Control Model", STD 91, RFC 8341, 2347 DOI 10.17487/RFC8341, March 2018, 2348 . 2350 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2351 and R. Wilton, "Network Management Datastore Architecture 2352 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2353 . 2355 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2356 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2357 . 2359 Appendix A. Expanded Tree Diagrams 2361 A.1. Expanded Tree Diagram for 'ietf-restconf-client' 2363 The following tree diagram [RFC8340] provides an overview of the data 2364 model for the "ietf-restconf-client" module. 2366 This tree diagram shows all the nodes defined in this module, 2367 including those defined by "grouping" statements used by this module. 2369 Please see Section 2.1 for a tree diagram that illustrates what the 2370 module looks like without all the "grouping" statements expanded. 2372 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-client-tree.txt) 2374 A.2. Expanded Tree Diagram for 'ietf-restconf-server' 2376 The following tree diagram [RFC8340] provides an overview of the data 2377 model for the "ietf-restconf-server" module. 2379 This tree diagram shows all the nodes defined in this module, 2380 including those defined by "grouping" statements used by this module. 2382 Please see Section 3.1 for a tree diagram that illustrates what the 2383 module looks like without all the "grouping" statements expanded. 2385 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-server-tree.txt) 2387 Appendix B. Change Log 2389 This section is to be removed before publishing as an RFC. 2391 B.1. 00 to 01 2392 * Renamed "keychain" to "keystore". 2394 B.2. 01 to 02 2396 * Filled in previously missing 'ietf-restconf-client' module. 2398 * Updated the ietf-restconf-server module to accommodate new 2399 grouping 'ietf-tls-server-grouping'. 2401 B.3. 02 to 03 2403 * Refined use of tls-client-grouping to add a must statement 2404 indicating that the TLS client must specify a client-certificate. 2406 * Changed restconf-client??? to be a grouping (not a container). 2408 B.4. 03 to 04 2410 * Added RFC 8174 to Requirements Language Section. 2412 * Replaced refine statement in ietf-restconf-client to add a 2413 mandatory true. 2415 * Added refine statement in ietf-restconf-server to add a must 2416 statement. 2418 * Now there are containers and groupings, for both the client and 2419 server models. 2421 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2423 * Updated examples to inline key and certificates (no longer a 2424 leafref to keystore) 2426 B.5. 04 to 05 2428 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2430 * Updated examples to inline key and certificates (no longer a 2431 leafref to keystore) 2433 B.6. 05 to 06 2435 * Fixed change log missing section issue. 2437 * Updated examples to match latest updates to the crypto-types, 2438 trust-anchors, and keystore drafts. 2440 * Reduced line length of the YANG modules to fit within 69 columns. 2442 B.7. 06 to 07 2444 * removed "idle-timeout" from "persistent" connection config. 2446 * Added "random-selection" for reconnection-strategy's "starts-with" 2447 enum. 2449 * Replaced "connection-type" choice default (persistent) with 2450 "mandatory true". 2452 * Reduced the periodic-connection's "idle-timeout" from 5 to 2 2453 minutes. 2455 * Replaced reconnect-timeout with period/anchor-time combo. 2457 B.8. 07 to 08 2459 * Modified examples to be compatible with new crypto-types algs 2461 B.9. 08 to 09 2463 * Corrected use of "mandatory true" for "address" leafs. 2465 * Updated examples to reflect update to groupings defined in the 2466 keystore draft. 2468 * Updated to use groupings defined in new TCP and HTTP drafts. 2470 * Updated copyright date, boilerplate template, affiliation, and 2471 folding algorithm. 2473 B.10. 09 to 10 2475 * Reformatted YANG modules. 2477 B.11. 10 to 11 2479 * Adjusted for the top-level "demux container" added to groupings 2480 imported from other modules. 2482 * Added "must" expressions to ensure that keepalives are not 2483 configured for "periodic" connections. 2485 * Updated the boilerplate text in module-level "description" 2486 statement to match copyeditor convention. 2488 * Moved "expanded" tree diagrams to the Appendix. 2490 B.12. 11 to 12 2492 * Removed the 'must' statement limiting keepalives in periodic 2493 connections. 2495 * Updated models and examples to reflect removal of the "demux" 2496 containers in the imported models. 2498 * Updated the "periodic-connnection" description statements to 2499 better describe behavior when connections are not closed 2500 gracefully. 2502 * Updated text to better reference where certain examples come from 2503 (e.g., which Section in which draft). 2505 * In the server model, commented out the "must 'pinned-ca-certs or 2506 pinned-client-certs'" statement to reflect change made in the TLS 2507 draft whereby the trust anchors MAY be defined externally. 2509 * Replaced the 'listen', 'initiate', and 'call-home' features with 2510 boolean expressions. 2512 B.13. 12 to 13 2514 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2515 anchors/truststore/g + s/pinned.//) 2517 * In ietf-restconf-server, Added 'http-listen' (not https-listen) 2518 choice, to support case when server is behind a TLS-terminator. 2520 * Refactored server module to be more like other 'server' models. 2521 If folks like it, will also apply to the client model, as well as 2522 to both the netconf client/server models. Now the 'restconf- 2523 server-grouping' is just the RC-specific bits (i.e., the "demux" 2524 container minus the container), 'restconf-server- 2525 [listen|callhome]-stack-grouping' is the protocol stack for a 2526 single connection, and 'restconf-server-app-grouping' is 2527 effectively what was before (both listen+callhome for many 2528 inbound/outbound endpoints). 2530 B.14. 13 to 14 2532 * Updated examples to reflect ietf-crypto-types change (e.g., 2533 identities --> enumerations) 2535 * Adjusting from change in TLS client model (removing the top-level 2536 'certificate' container). 2538 * Added "external-endpoint" to the "http-listen" choice in ietf- 2539 restconf-server. 2541 B.15. 14 to 15 2543 * Added missing "or https-listen" clause in a "must" expression. 2545 * Refactored the client module similar to how the server module was 2546 refactored in -13. Now the 'restconf-client-grouping' is just the 2547 RC-specific bits, the 'restconf-client-[initiate|listen]-stack- 2548 grouping' is the protocol stack for a single connection, and 2549 'restconf-client-app-grouping' is effectively what was before 2550 (both listen+callhome for many inbound/outbound endpoints). 2552 B.16. 15 to 16 2554 * Added refinement to make "cert-to-name/fingerprint" be mandatory 2555 false. 2557 * Commented out refinement to "tls-server-grouping/client- 2558 authentication" until a better "must" expression is defined. 2560 * Updated restconf-client example to reflect that http-client- 2561 grouping no longer has a "protocol-version" leaf. 2563 B.17. 16 to 17 2565 * Updated examples to include the "*-key-format" nodes. 2567 * Updated examples to remove the "required" nodes. 2569 B.18. 17 to 18 2571 * Updated examples to reflect new "bag" addition to truststore. 2573 B.19. 18 to 19 2575 * Updated examples to remove the 'algorithm' nodes. 2577 * Updated examples to reflect the new TLS keepalives structure. 2579 * Removed the 'protocol-versions' node from the restconf-server 2580 examples. 2582 * Added a "Note to Reviewers" note to first page. 2584 B.20. 19 to 20 2586 * Moved and changed "must" statement so that either TLS *or* HTTP 2587 auth must be configured. 2589 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2590 diagrams]. 2592 * Updated the Security Considerations section. 2594 B.21. 20 to 21 2596 * Cleaned up titles in the IANA Consideratons section 2598 * Fixed issues found by the SecDir review of the "keystore" draft. 2600 B.22. 21 to 22 2602 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 2604 B.23. 22 to 23 2606 * Further clarified why some 'presence' statements are present. 2608 * Addressed nits found in YANG Doctor reviews. 2610 * Aligned modules with `pyang -f` formatting. 2612 Acknowledgements 2614 The authors would like to thank for following for lively discussions 2615 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2616 Bierman, Balazs Kovacs, Benoit Claise, Bert Wijnen David Lamparter, 2617 Juergen Schoenwaelder, Ladislav Lhotka, Martin Bjoerklund, Mehmet 2618 Ersue, Phil Shafer, Radek Krejci, Ramkumar Dhanapal, Sean Turner, and 2619 Tom Petch. 2621 Author's Address 2623 Kent Watsen 2624 Watsen Networks 2626 Email: kent+ietf@watsen.net