idnits 2.17.1 draft-ietf-netconf-restconf-client-server-25.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 1215 has weird spacing: '...address ine...' -- The document date (7 March 2022) is 778 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-08 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-23 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-11 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-26 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-24 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-24 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-26 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-16 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 7 March 2022 5 Expires: 8 September 2022 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-25 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-client- 37 server 39 * EEEE --> the assigned RFC value for draft-ietf-netconf-ssh-client- 40 server 42 * FFFF --> the assigned RFC value for draft-ietf-netconf-tls-client- 43 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 * 2022-03-07 --> the publication date of this draft 58 The following Appendix section is to be removed prior to publication: 60 * Appendix A. 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 8 September 2022. 79 Copyright Notice 81 Copyright (c) 2022 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 Revised BSD License text as 90 described in Section 4.e of the Trust Legal Provisions and are 91 provided without warranty as described in the Revised 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 1.4. Conventions . . . . . . . . . . . . . . . . . . . . . . . 6 100 2. The "ietf-restconf-client" Module . . . . . . . . . . . . . . 6 101 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 102 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 11 103 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 15 104 3. The "ietf-restconf-server" Module . . . . . . . . . . . . . . 25 105 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 25 106 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 30 107 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 34 108 4. Security Considerations . . . . . . . . . . . . . . . . . . . 46 109 4.1. The "ietf-restconf-client" YANG Module . . . . . . . . . 46 110 4.2. The "ietf-restconf-server" YANG Module . . . . . . . . . 47 111 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 112 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 47 113 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 48 114 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 115 6.1. Normative References . . . . . . . . . . . . . . . . . . 48 116 6.2. Informative References . . . . . . . . . . . . . . . . . 49 117 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 51 118 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 51 119 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 51 120 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 51 121 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 51 122 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 52 123 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 52 124 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 52 125 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 52 126 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 52 127 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 53 128 A.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 53 129 A.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 53 130 A.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 53 131 A.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 54 132 A.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 54 133 A.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 54 134 A.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 54 135 A.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 55 136 A.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 55 137 A.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 55 138 A.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 55 139 A.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 55 140 A.23. 22 to 23 . . . . . . . . . . . . . . . . . . . . . . . . 55 141 A.24. 23 to 24 . . . . . . . . . . . . . . . . . . . . . . . . 55 142 A.25. 24 to 25 . . . . . . . . . . . . . . . . . . . . . . . . 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 1.4. Conventions 236 Various examples used in this document use a placeholder value for 237 binary data that has been base64 encoded (e.g., "BASE64VALUE="). 238 This placeholder value is used as real base64 encoded structures are 239 often many lines long and hence distracting to the example being 240 presented. 242 2. The "ietf-restconf-client" Module 244 The RESTCONF client model presented in this section supports both 245 clients initiating connections to servers, as well as clients 246 listening for connections from servers calling home. 248 YANG feature statements are used to enable implementations to 249 advertise which potentially uncommon parts of the model the RESTCONF 250 client supports. 252 2.1. Data Model Overview 254 This section provides an overview of the "ietf-restconf-client" 255 module in terms of its features and groupings. 257 2.1.1. Features 259 The following diagram lists all the "feature" statements defined in 260 the "ietf-restconf-client" module: 262 Features: 263 +-- https-initiate 264 +-- http-listen 265 +-- https-listen 266 | The diagram above uses syntax that is similar to but not 267 | defined in [RFC8340]. 269 2.1.2. Groupings 271 The "ietf-restconf-client" module defines the following "grouping" 272 statements: 274 * restconf-client-grouping 275 * restconf-client-initiate-stack-grouping 276 * restconf-client-listen-stack-grouping 277 * restconf-client-app-grouping 279 Each of these groupings are presented in the following subsections. 281 2.1.2.1. The "restconf-client-grouping" Grouping 283 The following tree diagram [RFC8340] illustrates the "restconf- 284 client-grouping" grouping: 286 grouping restconf-client-grouping ---> 288 Comments: 290 * This grouping does not define any nodes, but is maintained so that 291 downstream modules can augment nodes into it if needed. 293 * The "restconf-client-grouping" defines, if it can be called that, 294 the configuration for just "RESTCONF" part of a protocol stack. 295 It does not, for instance, define any configuration for the "TCP", 296 "TLS", or "HTTP" protocol layers (for that, see Section 2.1.2.2 297 and Section 2.1.2.3). 299 2.1.2.2. The "restconf-client-initiate-stack-grouping" Grouping 301 The following tree diagram [RFC8340] illustrates the "restconf- 302 client-initiate-stack-grouping" grouping: 304 grouping restconf-client-initiate-stack-grouping 305 +-- (transport) 306 +--:(https) {https-initiate}? 307 +-- https 308 +-- tcp-client-parameters 309 | +---u tcpc:tcp-client-grouping 310 +-- tls-client-parameters 311 | +---u tlsc:tls-client-grouping 312 +-- http-client-parameters 313 | +---u httpc:http-client-grouping 314 +-- restconf-client-parameters 315 +---u rcc:restconf-client-grouping 317 Comments: 319 * The "restconf-client-initiate-stack-grouping" defines the 320 configuration for a full RESTCONF protocol stack, for RESTCONF 321 clients that initiate connections to RESTCONF servers, as opposed 322 to receiving call-home [RFC8071] connections. 324 * The "transport" choice node enables transport options to be 325 configured. This document only defines an "https" option, but 326 other options MAY be augmented in. 328 * For the referenced grouping statement(s): 330 - The "tcp-client-grouping" grouping is discussed in 331 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 332 - The "tls-client-grouping" grouping is discussed in 333 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 334 - The "http-client-grouping" grouping is discussed in 335 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 336 - The "restconf-client-grouping" grouping is discussed in 337 Section 2.1.2.1 in this document. 339 2.1.2.3. The "restconf-client-listen-stack-grouping" Grouping 341 The following tree diagram [RFC8340] illustrates the "restconf- 342 client-listen-stack-grouping" grouping: 344 grouping restconf-client-listen-stack-grouping 345 +-- (transport) 346 +--:(http) {http-listen}? 347 | +-- http 348 | +-- tcp-server-parameters 349 | | +---u tcps:tcp-server-grouping 350 | +-- http-client-parameters 351 | | +---u httpc:http-client-grouping 352 | +-- restconf-client-parameters 353 | +---u rcc:restconf-client-grouping 354 +--:(https) {https-listen}? 355 +-- https 356 +-- tcp-server-parameters 357 | +---u tcps:tcp-server-grouping 358 +-- tls-client-parameters 359 | +---u tlsc:tls-client-grouping 360 +-- http-client-parameters 361 | +---u httpc:http-client-grouping 362 +-- restconf-client-parameters 363 +---u rcc:restconf-client-grouping 365 Comments: 367 * The "restconf-client-listen-stack-grouping" defines the 368 configuration for a full RESTCONF protocol stack, for RESTCONF 369 clients that receive call-home [RFC8071] connections from RESTCONF 370 servers. 372 * The "transport" choice node enables both the HTTP and HTTPS 373 transports to be configured, with each option enabled by a 374 "feature" statement. Note that RESTCONF requires HTTPS, the HTTP 375 option is provided to support cases where a TLS-terminator is 376 deployed in front of the RESTCONF-client. 378 * For the referenced grouping statement(s): 380 - The "tcp-server-grouping" grouping is discussed in 381 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 382 - The "tls-client-grouping" grouping is discussed in 383 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 384 - The "http-client-grouping" grouping is discussed in 385 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 386 - The "restconf-client-grouping" grouping is discussed in 387 Section 2.1.2.1 in this document. 389 2.1.2.4. The "restconf-client-app-grouping" Grouping 391 The following tree diagram [RFC8340] illustrates the "restconf- 392 client-app-grouping" grouping: 394 grouping restconf-client-app-grouping 395 +-- initiate! {https-initiate}? 396 | +-- restconf-server* [name] 397 | +-- name? string 398 | +-- endpoints 399 | | +-- endpoint* [name] 400 | | +-- name? string 401 | | +---u restconf-client-initiate-stack-grouping 402 | +-- connection-type 403 | | +-- (connection-type) 404 | | +--:(persistent-connection) 405 | | | +-- persistent! 406 | | +--:(periodic-connection) 407 | | +-- periodic! 408 | | +-- period? uint16 409 | | +-- anchor-time? yang:date-and-time 410 | | +-- idle-timeout? uint16 411 | +-- reconnect-strategy 412 | +-- start-with? enumeration 413 | +-- max-attempts? uint8 414 +-- listen! {http-listen or https-listen}? 415 +-- idle-timeout? uint16 416 +-- endpoint* [name] 417 +-- name? string 418 +---u restconf-client-listen-stack-grouping 420 Comments: 422 * The "restconf-client-app-grouping" defines the configuration for a 423 RESTCONF client that supports both initiating connections to 424 RESTCONF servers as well as receiving call-home connections from 425 RESTCONF servers. 427 * Both the "initiate" and "listen" subtrees must be enabled by 428 "feature" statements. 430 * For the referenced grouping statement(s): 432 - The "restconf-client-initiate-stack-grouping" grouping is 433 discussed in Section 2.1.2.2 in this document. 434 - The "restconf-client-listen-stack-grouping" grouping is 435 discussed in Section 2.1.2.3 in this document. 437 2.1.3. Protocol-accessible Nodes 439 The following tree diagram [RFC8340] lists all the protocol- 440 accessible nodes defined in the "ietf-restconf-client" module: 442 module: ietf-restconf-client 443 +--rw restconf-client 444 +---u restconf-client-app-grouping 446 Comments: 448 * Protocol-accessible nodes are those nodes that are accessible when 449 the module is "implemented", as described in Section 5.6.5 of 450 [RFC7950]. 452 * For the "ietf-restconf-client" module, the protocol-accessible 453 nodes are an instance of the "restconf-client-app-grouping" 454 discussed in Section 2.1.2.4 grouping. 456 * The reason for why "restconf-client-app-grouping" exists separate 457 from the protocol-accessible nodes definition is so as to enable 458 instances of restconf-client-app-grouping to be instantiated in 459 other locations, as may be needed or desired by some modules. 461 2.2. Example Usage 463 The following example illustrates configuring a RESTCONF client to 464 initiate connections, as well as to listen for call-home connections. 466 This example is consistent with the examples presented in Section 2.2 467 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 468 [I-D.ietf-netconf-keystore]. 470 =============== NOTE: '\' line wrapping per RFC 8792 ================ 472 475 476 477 478 corp-fw1 479 480 481 corp-fw1.example.com 482 483 484 corp-fw1.example.com 485 486 15 487 3 488 30 489 490 491 492 493 494 495 rsa-asymmetric-key 497 ex-rsa-cert 498 499 500 501 502 503 trusted-server-ca-certs 505 506 507 trusted-server-ee-certs 509 510 511 512 513 30 514 3 515 516 517 518 519 520 521 bob 522 secret 523 524 525 526 527 528 529 corp-fw2.example.com 530 531 532 corp-fw2.example.com 533 534 15 535 3 536 30 537 538 539 540 541 542 543 rsa-asymmetric-key 545 ex-rsa-cert 546 547 548 549 550 551 trusted-server-ca-certs 553 554 555 trusted-server-ee-certs 557 558 559 560 561 30 562 3 563 564 565 566 567 568 569 bob 570 secret 571 572 573 574 575 576 577 578 579 580 582 584 585 586 587 Intranet-facing listener 588 589 590 11.22.33.44 591 592 593 594 595 596 rsa-asymmetric-key 597 ex-rsa-cert 598 599 600 601 602 603 trusted-server-ca-certs 605 606 607 trusted-server-ee-certs 609 610 611 612 613 614 615 616 617 618 bob 619 secret 620 621 622 623 624 625 626 628 2.3. YANG Module 630 This YANG module has normative references to [RFC6991], [RFC8040], 631 and [RFC8071], [I-D.ietf-netconf-tcp-client-server], 632 [I-D.ietf-netconf-tls-client-server], and 633 [I-D.ietf-netconf-http-client-server]. 635 file "ietf-restconf-client@2022-03-07.yang" 637 module ietf-restconf-client { 638 yang-version 1.1; 639 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 640 prefix rcc; 642 import ietf-yang-types { 643 prefix yang; 644 reference 645 "RFC 6991: Common YANG Data Types"; 646 } 648 import ietf-tcp-client { 649 prefix tcpc; 650 reference 651 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 652 } 654 import ietf-tcp-server { 655 prefix tcps; 656 reference 657 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 658 } 660 import ietf-tls-client { 661 prefix tlsc; 662 reference 663 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 664 } 666 import ietf-http-client { 667 prefix httpc; 668 reference 669 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 670 } 672 organization 673 "IETF NETCONF (Network Configuration) Working Group"; 675 contact 676 "WG Web: https://datatracker.ietf.org/wg/netconf 677 WG List: NETCONF WG list 678 Author: Kent Watsen 679 Author: Gary Wu "; 681 description 682 "This module contains a collection of YANG definitions 683 for configuring RESTCONF clients. 685 Copyright (c) 2021 IETF Trust and the persons identified 686 as authors of the code. All rights reserved. 688 Redistribution and use in source and binary forms, with 689 or without modification, is permitted pursuant to, and 690 subject to the license terms contained in, the Revised 691 BSD License set forth in Section 4.c of the IETF Trust's 692 Legal Provisions Relating to IETF Documents 693 (https://trustee.ietf.org/license-info). 695 This version of this YANG module is part of RFC IIII 696 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 697 itself for full legal notices. 699 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 700 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 701 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 702 are to be interpreted as described in BCP 14 (RFC 2119) 703 (RFC 8174) when, and only when, they appear in all 704 capitals, as shown here."; 706 revision 2022-03-07 { 707 description 708 "Initial version"; 709 reference 710 "RFC IIII: RESTCONF Client and Server Models"; 711 } 713 // Features 715 feature https-initiate { 716 description 717 "The 'https-initiate' feature indicates that the RESTCONF 718 client supports initiating HTTPS connections to RESTCONF 719 servers. This feature exists as HTTPS might not be a 720 mandatory to implement transport in the future."; 721 reference 722 "RFC 8040: RESTCONF Protocol"; 723 } 724 feature http-listen { 725 description 726 "The 'https-listen' feature indicates that the RESTCONF client 727 supports opening a port to listen for incoming RESTCONF 728 server call-home connections. This feature exists as not 729 all RESTCONF clients may support RESTCONF call home."; 730 reference 731 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 732 } 734 feature https-listen { 735 description 736 "The 'https-listen' feature indicates that the RESTCONF client 737 supports opening a port to listen for incoming RESTCONF 738 server call-home connections. This feature exists as not 739 all RESTCONF clients may support RESTCONF call home."; 740 reference 741 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 742 } 744 // Groupings 746 grouping restconf-client-grouping { 747 description 748 "A reusable grouping for configuring a RESTCONF client 749 without any consideration for how underlying transport 750 sessions are established. 752 This grouping currently does not define any nodes."; 753 } 755 grouping restconf-client-initiate-stack-grouping { 756 description 757 "A reusable grouping for configuring a RESTCONF client 758 'initiate' protocol stack for a single connection."; 760 choice transport { 761 mandatory true; 762 description 763 "Selects between available transports. This is a 764 'choice' statement so as to support additional 765 transport options to be augmented in."; 766 case https { 767 if-feature "https-initiate"; 768 container https { 769 must 'tls-client-parameters/client-identity 770 or http-client-parameters/client-identity'; 771 description 772 "Specifies HTTPS-specific transport 773 configuration."; 774 container tcp-client-parameters { 775 description 776 "A wrapper around the TCP client parameters 777 to avoid name collisions."; 778 uses tcpc:tcp-client-grouping { 779 refine "remote-port" { 780 default "443"; 781 description 782 "The RESTCONF client will attempt to 783 connect to the IANA-assigned well-known 784 port value for 'https' (443) if no value 785 is specified."; 786 } 787 } 788 } 789 container tls-client-parameters { 790 description 791 "A wrapper around the TLS client parameters 792 to avoid name collisions."; 793 uses tlsc:tls-client-grouping; 794 } 795 container http-client-parameters { 796 description 797 "A wrapper around the HTTP client parameters 798 to avoid name collisions."; 799 uses httpc:http-client-grouping; 800 } 801 container restconf-client-parameters { 802 description 803 "A wrapper around the HTTP client parameters 804 to avoid name collisions."; 805 uses rcc:restconf-client-grouping; 806 } 807 } 808 } 809 } 810 } // restconf-client-initiate-stack-grouping 812 grouping restconf-client-listen-stack-grouping { 813 description 814 "A reusable grouping for configuring a RESTCONF client 815 'listen' protocol stack for a single connection. The 816 'listen' stack supports call home connections, as 817 described in RFC 8071"; 818 reference 819 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 821 choice transport { 822 mandatory true; 823 description 824 "Selects between available transports. This is a 825 'choice' statement so as to support additional 826 transport options to be augmented in."; 827 case http { 828 if-feature "http-listen"; 829 container http { 830 description 831 "HTTP-specific listening configuration for inbound 832 connections. 834 This transport option is made available to support 835 deployments where the TLS connections are terminated 836 by another system (e.g., a load balanacer) fronting 837 the client."; 838 container tcp-server-parameters { 839 description 840 "A wrapper around the TCP client parameters 841 to avoid name collisions."; 842 uses tcps:tcp-server-grouping { 843 refine "local-port" { 844 default "4336"; 845 description 846 "The RESTCONF client will listen on the IANA- 847 assigned well-known port for 'restconf-ch-tls' 848 (4336) if no value is specified."; 849 } 850 } 851 } 852 container http-client-parameters { 853 description 854 "A wrapper around the HTTP client parameters 855 to avoid name collisions."; 856 uses httpc:http-client-grouping; 857 } 858 container restconf-client-parameters { 859 description 860 "A wrapper around the RESTCONF client parameters 861 to avoid name collisions."; 862 uses rcc:restconf-client-grouping; 863 } 864 } 865 } 866 case https { 867 if-feature "https-listen"; 868 container https { 869 must 'tls-client-parameters/client-identity 870 or http-client-parameters/client-identity'; 871 description 872 "HTTPS-specific listening configuration for inbound 873 connections."; 874 container tcp-server-parameters { 875 description 876 "A wrapper around the TCP client parameters 877 to avoid name collisions."; 878 uses tcps:tcp-server-grouping { 879 refine "local-port" { 880 default "4336"; 881 description 882 "The RESTCONF client will listen on the IANA- 883 assigned well-known port for 'restconf-ch-tls' 884 (4336) if no value is specified."; 885 } 886 } 887 } 888 container tls-client-parameters { 889 description 890 "A wrapper around the TLS client parameters 891 to avoid name collisions."; 892 uses tlsc:tls-client-grouping; 893 } 894 container http-client-parameters { 895 description 896 "A wrapper around the HTTP client parameters 897 to avoid name collisions."; 898 uses httpc:http-client-grouping; 899 } 900 container restconf-client-parameters { 901 description 902 "A wrapper around the RESTCONF client parameters 903 to avoid name collisions."; 904 uses rcc:restconf-client-grouping; 905 } 906 } 907 } 908 } 909 } // restconf-client-listen-stack-grouping 911 grouping restconf-client-app-grouping { 912 description 913 "A reusable grouping for configuring a RESTCONF client 914 application that supports both 'initiate' and 'listen' 915 protocol stacks for a multiplicity of connections."; 916 container initiate { 917 if-feature "https-initiate"; 918 presence 919 "Indicates that client-initiated connections have been 920 configured. This statement is present so the mandatory 921 descendant nodes do not imply that this node must be 922 configured."; 923 description 924 "Configures client initiating underlying TCP connections."; 925 list restconf-server { 926 key "name"; 927 min-elements 1; 928 description 929 "List of RESTCONF servers the RESTCONF client is to 930 maintain simultaneous connections with."; 931 leaf name { 932 type string; 933 description 934 "An arbitrary name for the RESTCONF server."; 935 } 936 container endpoints { 937 description 938 "Container for the list of endpoints."; 939 list endpoint { 940 key "name"; 941 min-elements 1; 942 ordered-by user; 943 description 944 "A non-empty user-ordered list of endpoints for this 945 RESTCONF client to try to connect to in sequence. 946 Defining more than one enables high-availability."; 947 leaf name { 948 type string; 949 description 950 "An arbitrary name for this endpoint."; 951 } 952 uses restconf-client-initiate-stack-grouping; 953 } 954 } 955 container connection-type { 956 description 957 "Indicates the RESTCONF client's preference for how 958 the RESTCONF connection is maintained."; 959 choice connection-type { 960 mandatory true; 961 description 962 "Selects between available connection types."; 963 case persistent-connection { 964 container persistent { 965 presence 966 "Indicates that a persistent connection is to be 967 maintained."; 968 description 969 "Maintain a persistent connection to the 970 RESTCONF server. If the connection goes down, 971 immediately start trying to reconnect to the 972 RESTCONF server, using the reconnection strategy. 974 This connection type minimizes any RESTCONF server 975 to RESTCONF client data-transfer delay, albeit 976 at the expense of holding resources longer."; 977 } 978 } 979 case periodic-connection { 980 container periodic { 981 presence 982 "Indicates that a periodic connection is to be 983 maintained."; 984 description 985 "Periodically connect to the RESTCONF server. 987 This connection type increases resource 988 utilization, albeit with increased delay 989 in RESTCONF server to RESTCONF client 990 interactions. 992 The RESTCONF client SHOULD gracefully close 993 the underlying TLS connection upon completing 994 planned activities. 996 In the case that the previous connection is 997 still active, establishing a new connection 998 is NOT RECOMMENDED."; 999 leaf period { 1000 type uint16; 1001 units "minutes"; 1002 default "60"; 1003 description 1004 "Duration of time between periodic 1005 connections."; 1006 } 1007 leaf anchor-time { 1008 type yang:date-and-time { 1009 // constrained to minute-level granularity 1010 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1011 + '(Z|[\+\-]\d{2}:\d{2})'; 1012 } 1013 description 1014 "Designates a timestamp before or after which 1015 a series of periodic connections are 1016 determined. The periodic connections occur 1017 at a whole multiple interval from the anchor 1018 time. For example, for an anchor time is 15 1019 minutes past midnight and a period interval 1020 of 24 hours, then a periodic connection will 1021 occur 15 minutes past midnight everyday."; 1022 } 1023 leaf idle-timeout { 1024 type uint16; 1025 units "seconds"; 1026 default "120"; // two minutes 1027 description 1028 "Specifies the maximum number of seconds 1029 that the underlying TCP session may remain 1030 idle. A TCP session will be dropped if it 1031 is idle for an interval longer than this 1032 number of seconds If set to zero, then the 1033 RESTCONF client will never drop a session 1034 because it is idle."; 1035 } 1036 } 1037 } // periodic-connection 1038 } // connection-type 1039 } // connection-type 1040 container reconnect-strategy { 1041 description 1042 "The reconnection strategy directs how a RESTCONF 1043 client reconnects to a RESTCONF server, after 1044 discovering its connection to the server has 1045 dropped, even if due to a reboot. The RESTCONF 1046 client starts with the specified endpoint and 1047 tries to connect to it max-attempts times before 1048 trying the next endpoint in the list (round 1049 robin)."; 1050 leaf start-with { 1051 type enumeration { 1052 enum first-listed { 1053 description 1054 "Indicates that reconnections should start 1055 with the first endpoint listed."; 1056 } 1057 enum last-connected { 1058 description 1059 "Indicates that reconnections should start 1060 with the endpoint last connected to. If 1061 no previous connection has ever been 1062 established, then the first endpoint 1063 configured is used. RESTCONF clients 1064 SHOULD be able to remember the last 1065 endpoint connected to across reboots."; 1066 } 1067 enum random-selection { 1068 description 1069 "Indicates that reconnections should start with 1070 a random endpoint."; 1071 } 1072 } 1073 default "first-listed"; 1074 description 1075 "Specifies which of the RESTCONF server's 1076 endpoints the RESTCONF client should start 1077 with when trying to connect to the RESTCONF 1078 server."; 1079 } 1080 leaf max-attempts { 1081 type uint8 { 1082 range "1..max"; 1083 } 1084 default "3"; 1085 description 1086 "Specifies the number times the RESTCONF client 1087 tries to connect to a specific endpoint before 1088 moving on to the next endpoint in the list 1089 (round robin)."; 1090 } 1091 } 1092 } 1093 } // initiate 1094 container listen { 1095 if-feature "http-listen or https-listen"; 1096 presence 1097 "Indicates that client-listening ports have been configured. 1098 This statement is present so the mandatory descendant nodes 1099 do not imply that this node must be configured."; 1100 description 1101 "Configures the client to accept call-home TCP connections."; 1102 leaf idle-timeout { 1103 type uint16; 1104 units "seconds"; 1105 default "3600"; // one hour 1106 description 1107 "Specifies the maximum number of seconds that an 1108 underlying TCP session may remain idle. A TCP session 1109 will be dropped if it is idle for an interval longer 1110 then this number of seconds. If set to zero, then 1111 the server will never drop a session because it is 1112 idle. Sessions that have a notification subscription 1113 active are never dropped."; 1114 } 1115 list endpoint { 1116 key "name"; 1117 min-elements 1; 1118 description 1119 "List of endpoints to listen for RESTCONF connections."; 1120 leaf name { 1121 type string; 1122 description 1123 "An arbitrary name for the RESTCONF listen endpoint."; 1124 } 1125 uses restconf-client-listen-stack-grouping; 1126 } 1127 } 1128 } // restconf-client-app-grouping 1130 // Protocol accessible node for servers that implement this module. 1131 container restconf-client { 1132 uses restconf-client-app-grouping; 1133 description 1134 "Top-level container for RESTCONF client configuration."; 1135 } 1136 } 1138 1140 3. The "ietf-restconf-server" Module 1142 The RESTCONF server model presented in this section supports both 1143 listening for connections as well as initiating call-home 1144 connections. 1146 YANG feature statements are used to enable implementations to 1147 advertise which potentially uncommon parts of the model the RESTCONF 1148 server supports. 1150 3.1. Data Model Overview 1152 This section provides an overview of the "ietf-restconf-server" 1153 module in terms of its features and groupings. 1155 3.1.1. Features 1157 The following diagram lists all the "feature" statements defined in 1158 the "ietf-restconf-server" module: 1160 Features: 1161 +-- http-listen 1162 +-- https-listen 1163 +-- https-call-home 1165 | The diagram above uses syntax that is similar to but not 1166 | defined in [RFC8340]. 1168 3.1.2. Groupings 1170 The "ietf-restconf-server" module defines the following "grouping" 1171 statements: 1173 * restconf-server-grouping 1174 * restconf-server-listen-stack-grouping 1175 * restconf-server-callhome-stack-grouping 1176 * restconf-server-app-grouping 1178 Each of these groupings are presented in the following subsections. 1180 3.1.2.1. The "restconf-server-grouping" Grouping 1182 The following tree diagram [RFC8340] illustrates the "restconf- 1183 server-grouping" grouping: 1185 grouping restconf-server-grouping 1186 +-- client-identity-mappings 1187 +---u x509c2n:cert-to-name 1189 Comments: 1191 * The "restconf-server-grouping" defines the configuration for just 1192 "RESTCONF" part of a protocol stack. It does not, for instance, 1193 define any configuration for the "TCP", "TLS", or "HTTP" protocol 1194 layers (for that, see Section 3.1.2.2 and Section 3.1.2.3). 1196 * The "client-identity-mappings" node, which must be enabled by 1197 "feature" statements, defines a mapping from certificate fields to 1198 RESTCONF user names. 1200 * For the referenced grouping statement(s): 1202 - The "cert-to-name" grouping is discussed in Section 4.1 of 1203 [RFC7407]. 1205 3.1.2.2. The "restconf-server-listen-stack-grouping" Grouping 1207 The following tree diagram [RFC8340] illustrates the "restconf- 1208 server-listen-stack-grouping" grouping: 1210 grouping restconf-server-listen-stack-grouping 1211 +-- (transport) 1212 +--:(http) {http-listen}? 1213 | +-- http 1214 | +-- external-endpoint! 1215 | | +-- address inet:ip-address 1216 | | +-- port? inet:port-number 1217 | +-- tcp-server-parameters 1218 | | +---u tcps:tcp-server-grouping 1219 | +-- http-server-parameters 1220 | | +---u https:http-server-grouping 1221 | +-- restconf-server-parameters 1222 | +---u rcs:restconf-server-grouping 1223 +--:(https) {https-listen}? 1224 +-- https 1225 +-- tcp-server-parameters 1226 | +---u tcps:tcp-server-grouping 1227 +-- tls-server-parameters 1228 | +---u tlss:tls-server-grouping 1229 +-- http-server-parameters 1230 | +---u https:http-server-grouping 1231 +-- restconf-server-parameters 1232 +---u rcs:restconf-server-grouping 1234 Comments: 1236 * The "restconf-server-listen-stack-grouping" defines the 1237 configuration for a full RESTCONF protocol stack for RESTCONF 1238 servers that listen for standard connections from RESTCONF 1239 clients, as opposed to initiating call-home [RFC8071] connections. 1241 * The "transport" choice node enables both the HTTP and HTTPS 1242 transports to be configured, with each option enabled by a 1243 "feature" statement. The HTTP option is provided to support cases 1244 where a TLS-terminator is deployed in front of the RESTCONF- 1245 server. 1247 * For the referenced grouping statement(s): 1249 - The "tcp-server-grouping" grouping is discussed in 1250 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1251 - The "tls-server-grouping" grouping is discussed in 1252 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 1384 1385 1386 1387 restconf/https 1388 1389 1390 11.22.33.44 1391 1392 1393 1394 1395 1396 rsa-asymmetric-key 1397 ex-rsa-cert 1398 1399 1400 1401 1402 1403 trusted-client-ca-certs 1405 1406 1407 trusted-client-ee-certs 1409 1410 1411 1412 1413 1414 1415 1416 foo.example.com 1417 1418 1419 1420 1421 1 1422 11:0A:05:11:00 1423 x509c2n:specified 1424 scooby-doo 1425 1426 1427 2 1428 x509c2n:san-any 1429 1430 1431 1432 1433 1434 1436 1437 1438 1439 config-manager 1440 1441 1442 east-data-center 1443 1444 1445 east.example.com 1446 1447 15 1448 3 1449 30 1450 1451 1452 1453 1454 1455 1456 rsa-asymmetric-key 1458 ex-rsa-cert 1459 1460 1461 1462 1463 1464 trusted-client-ca-certs 1466 1467 1468 trusted-client-ee-certs 1470 1471 1472 1473 1474 30 1475 3 1476 1477 1478 1479 1480 foo.example.com 1481 1482 1483 1484 1485 1 1486 11:0A:05:11:00 1487 x509c2n:specified 1488 scooby-doo 1490 1491 1492 2 1493 x509c2n:san-any 1494 1495 1496 1497 1498 1499 1500 west-data-center 1501 1502 1503 west.example.com 1504 1505 15 1506 3 1507 30 1508 1509 1510 1511 1512 1513 1514 rsa-asymmetric-key 1516 ex-rsa-cert 1517 1518 1519 1520 1521 1522 trusted-client-ca-certs 1524 1525 1526 trusted-client-ee-certs 1528 1529 1530 1531 1532 30 1533 3 1534 1535 1536 1537 1538 foo.example.com 1539 1540 1541 1542 1543 1 1544 11:0A:05:11:00 1545 x509c2n:specified 1546 scooby-doo 1547 1548 1549 2 1550 x509c2n:san-any 1551 1552 1553 1554 1555 1556 1557 1558 1559 300 1560 60 1561 1562 1563 1564 last-connected 1565 3 1566 1567 1568 1569 1571 3.3. YANG Module 1573 This YANG module has normative references to [RFC6991], [RFC7407], 1574 [RFC8040], [RFC8071], [I-D.ietf-netconf-tcp-client-server], 1575 [I-D.ietf-netconf-tls-client-server], and 1576 [I-D.ietf-netconf-http-client-server]. 1578 file "ietf-restconf-server@2022-03-07.yang" 1580 module ietf-restconf-server { 1581 yang-version 1.1; 1582 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1583 prefix rcs; 1585 import ietf-yang-types { 1586 prefix yang; 1587 reference 1588 "RFC 6991: Common YANG Data Types"; 1589 } 1591 import ietf-inet-types { 1592 prefix inet; 1593 reference 1594 "RFC 6991: Common YANG Data Types"; 1595 } 1597 import ietf-x509-cert-to-name { 1598 prefix x509c2n; 1599 reference 1600 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1601 } 1603 import ietf-tcp-client { 1604 prefix tcpc; 1605 reference 1606 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1607 } 1609 import ietf-tcp-server { 1610 prefix tcps; 1611 reference 1612 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1613 } 1615 import ietf-tls-server { 1616 prefix tlss; 1617 reference 1618 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1619 } 1621 import ietf-http-server { 1622 prefix https; 1623 reference 1624 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 1625 } 1627 organization 1628 "IETF NETCONF (Network Configuration) Working Group"; 1630 contact 1631 "WG Web: https://datatracker.ietf.org/wg/netconf 1632 WG List: NETCONF WG list 1633 Author: Kent Watsen 1634 Author: Gary Wu 1635 Author: Juergen Schoenwaelder 1636 "; 1638 description 1639 "This module contains a collection of YANG definitions 1640 for configuring RESTCONF servers. 1642 Copyright (c) 2021 IETF Trust and the persons identified 1643 as authors of the code. All rights reserved. 1645 Redistribution and use in source and binary forms, with 1646 or without modification, is permitted pursuant to, and 1647 subject to the license terms contained in, the Revised 1648 BSD License set forth in Section 4.c of the IETF Trust's 1649 Legal Provisions Relating to IETF Documents 1650 (https://trustee.ietf.org/license-info). 1652 This version of this YANG module is part of RFC IIII 1653 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 1654 itself for full legal notices. 1656 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1657 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1658 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1659 are to be interpreted as described in BCP 14 (RFC 2119) 1660 (RFC 8174) when, and only when, they appear in all 1661 capitals, as shown here."; 1663 revision 2022-03-07 { 1664 description 1665 "Initial version"; 1666 reference 1667 "RFC IIII: RESTCONF Client and Server Models"; 1668 } 1670 // Features 1672 feature http-listen { 1673 description 1674 "The 'http-listen' feature indicates that the RESTCONF server 1675 supports opening a port to listen for incoming RESTCONF over 1676 TPC client connections, whereby the TLS connections are 1677 terminated by an external system."; 1678 reference 1679 "RFC 8040: RESTCONF Protocol"; 1680 } 1681 feature https-listen { 1682 description 1683 "The 'https-listen' feature indicates that the RESTCONF server 1684 supports opening a port to listen for incoming RESTCONF over 1685 TLS client connections, whereby the TLS connections are 1686 terminated by the server itself."; 1687 reference 1688 "RFC 8040: RESTCONF Protocol"; 1689 } 1691 feature https-call-home { 1692 description 1693 "The 'https-call-home' feature indicates that the RESTCONF 1694 server supports initiating connections to RESTCONF clients."; 1695 reference 1696 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1697 } 1699 // Groupings 1701 grouping restconf-server-grouping { 1702 description 1703 "A reusable grouping for configuring a RESTCONF server 1704 without any consideration for how underlying transport 1705 sessions are established. 1707 Note that this grouping uses a fairly typical descendant 1708 node name such that a stack of 'uses' statements will 1709 have name conflicts. It is intended that the consuming 1710 data model will resolve the issue by wrapping the 'uses' 1711 statement in a container called, e.g., 1712 'restconf-server-parameters'. This model purposely does 1713 not do this itself so as to provide maximum flexibility 1714 to consuming models."; 1716 container client-identity-mappings { 1717 description 1718 "Specifies mappings through which RESTCONF client X.509 1719 certificates are used to determine a RESTCONF username. 1720 If no matching and valid cert-to-name list entry can be 1721 found, then the RESTCONF server MUST close the connection, 1722 and MUST NOT accept RESTCONF messages over it."; 1723 reference 1724 "RFC 7407: A YANG Data Model for SNMP Configuration."; 1725 uses x509c2n:cert-to-name { 1726 refine "cert-to-name/fingerprint" { 1727 mandatory false; 1728 description 1729 "A 'fingerprint' value does not need to be specified 1730 when the 'cert-to-name' mapping is independent of 1731 fingerprint matching. A 'cert-to-name' having no 1732 fingerprint value will match any client certificate 1733 and therefore should only be present at the end of 1734 the user-ordered 'cert-to-name' list."; 1735 } 1736 } 1737 } 1738 } 1740 grouping restconf-server-listen-stack-grouping { 1741 description 1742 "A reusable grouping for configuring a RESTCONF server 1743 'listen' protocol stack for a single connection."; 1744 choice transport { 1745 mandatory true; 1746 description 1747 "Selects between available transports. This is a 1748 'choice' statement so as to support additional 1749 transport options to be augmented in."; 1750 case http { 1751 if-feature "http-listen"; 1752 container http { 1753 description 1754 "Configures RESTCONF server stack assuming that 1755 TLS-termination is handled externally."; 1756 container external-endpoint { 1757 presence 1758 "Identifies that an external endpoint has been 1759 configured. This statement is present so the 1760 mandatory descendant nodes do not imply that 1761 this node must be configured."; 1762 description 1763 "Identifies contact information for the external 1764 system that terminates connections before passing 1765 them thru to this server (e.g., a network address 1766 translator or a load balancer). These values have 1767 no effect on the local operation of this server, 1768 but may be used by the application when needing to 1769 inform other systems how to contact this server."; 1770 leaf address { 1771 type inet:ip-address; 1772 mandatory true; 1773 description 1774 "The IP address or hostname of the external system 1775 that terminates incoming RESTCONF client 1776 connections before forwarding them to this 1777 server."; 1778 } 1779 leaf port { 1780 type inet:port-number; 1781 default "443"; 1782 description 1783 "The port number that the external system listens 1784 on for incoming RESTCONF client connections that 1785 are forwarded to this server. The default HTTPS 1786 port (443) is used, as expected for a RESTCONF 1787 connection."; 1788 } 1789 } 1790 container tcp-server-parameters { 1791 description 1792 "A wrapper around the TCP server parameters 1793 to avoid name collisions."; 1794 uses tcps:tcp-server-grouping { 1795 refine "local-port" { 1796 default "80"; 1797 description 1798 "The RESTCONF server will listen on the IANA- 1799 assigned well-known port value for 'http' 1800 (80) if no value is specified."; 1801 } 1802 } 1803 } 1804 container http-server-parameters { 1805 description 1806 "A wrapper around the HTTP server parameters 1807 to avoid name collisions."; 1808 uses https:http-server-grouping; 1809 } 1810 container restconf-server-parameters { 1811 description 1812 "A wrapper around the RESTCONF server parameters 1813 to avoid name collisions."; 1814 uses rcs:restconf-server-grouping; 1815 } 1816 } 1817 } 1818 case https { 1819 if-feature "https-listen"; 1820 container https { 1821 description 1822 "Configures RESTCONF server stack assuming that 1823 TLS-termination is handled internally."; 1824 container tcp-server-parameters { 1825 description 1826 "A wrapper around the TCP server parameters 1827 to avoid name collisions."; 1828 uses tcps:tcp-server-grouping { 1829 refine "local-port" { 1830 default "443"; 1831 description 1832 "The RESTCONF server will listen on the IANA- 1833 assigned well-known port value for 'https' 1834 (443) if no value is specified."; 1835 } 1836 } 1837 } 1838 container tls-server-parameters { 1839 description 1840 "A wrapper around the TLS server parameters 1841 to avoid name collisions."; 1842 uses tlss:tls-server-grouping; 1843 } 1844 container http-server-parameters { 1845 description 1846 "A wrapper around the HTTP server parameters 1847 to avoid name collisions."; 1848 uses https:http-server-grouping; 1849 } 1850 container restconf-server-parameters { 1851 description 1852 "A wrapper around the RESTCONF server parameters 1853 to avoid name collisions."; 1854 uses rcs:restconf-server-grouping; 1855 } 1856 } 1857 } 1858 } 1859 } 1861 grouping restconf-server-callhome-stack-grouping { 1862 description 1863 "A reusable grouping for configuring a RESTCONF server 1864 'call-home' protocol stack, for a single connection."; 1865 choice transport { 1866 mandatory true; 1867 description 1868 "Selects between available transports. This is a 1869 'choice' statement so as to support additional 1870 transport options to be augmented in."; 1871 case https { 1872 if-feature "https-listen"; 1873 container https { 1874 description 1875 "Configures RESTCONF server stack assuming that 1876 TLS-termination is handled internally."; 1877 container tcp-client-parameters { 1878 description 1879 "A wrapper around the TCP client parameters 1880 to avoid name collisions."; 1881 uses tcpc:tcp-client-grouping { 1882 refine "remote-port" { 1883 default "4336"; 1884 description 1885 "The RESTCONF server will attempt to 1886 connect to the IANA-assigned well-known 1887 port for 'restconf-ch-tls' (4336) if no 1888 value is specified."; 1889 } 1890 } 1891 } 1892 container tls-server-parameters { 1893 description 1894 "A wrapper around the TLS server parameters 1895 to avoid name collisions."; 1896 uses tlss:tls-server-grouping; 1897 } 1898 container http-server-parameters { 1899 description 1900 "A wrapper around the HTTP server parameters 1901 to avoid name collisions."; 1902 uses https:http-server-grouping; 1903 } 1904 container restconf-server-parameters { 1905 description 1906 "A wrapper around the RESTCONF server parameters 1907 to avoid name collisions."; 1908 uses rcs:restconf-server-grouping; 1909 } 1910 } 1911 } 1912 } 1913 } 1915 grouping restconf-server-app-grouping { 1916 description 1917 "A reusable grouping for configuring a RESTCONF server 1918 application that supports both 'listen' and 'call-home' 1919 protocol stacks for a multiplicity of connections."; 1920 container listen { 1921 if-feature "http-listen or https-listen"; 1922 presence 1923 "Identifies that the server has been configured to 1924 listen for incoming client connections. This statement 1925 is present so the mandatory descendant nodes do not 1926 imply that this node must be configured."; 1927 description 1928 "Configures the RESTCONF server to listen for RESTCONF 1929 client connections."; 1930 list endpoint { 1931 key "name"; 1932 min-elements 1; 1933 description 1934 "List of endpoints to listen for RESTCONF connections."; 1935 leaf name { 1936 type string; 1937 description 1938 "An arbitrary name for the RESTCONF listen endpoint."; 1939 } 1940 uses restconf-server-listen-stack-grouping; 1941 } 1942 } 1943 container call-home { 1944 if-feature "https-call-home"; 1945 presence 1946 "Identifies that the server has been configured to initiate 1947 call home connections. This statement is present so the 1948 mandatory descendant nodes do not imply that this node 1949 must be configured."; 1950 description 1951 "Configures the RESTCONF server to initiate the underlying 1952 transport connection to RESTCONF clients."; 1953 list restconf-client { 1954 key "name"; 1955 min-elements 1; 1956 description 1957 "List of RESTCONF clients the RESTCONF server is to 1958 maintain simultaneous call-home connections with."; 1959 leaf name { 1960 type string; 1961 description 1962 "An arbitrary name for the remote RESTCONF client."; 1963 } 1964 container endpoints { 1965 description 1966 "Container for the list of endpoints."; 1967 list endpoint { 1968 key "name"; 1969 min-elements 1; 1970 ordered-by user; 1971 description 1972 "User-ordered list of endpoints for this RESTCONF 1973 client. Defining more than one enables high- 1974 availability."; 1975 leaf name { 1976 type string; 1977 description 1978 "An arbitrary name for this endpoint."; 1979 } 1980 uses restconf-server-callhome-stack-grouping; 1981 } 1982 } 1983 container connection-type { 1984 description 1985 "Indicates the RESTCONF server's preference for how the 1986 RESTCONF connection is maintained."; 1987 choice connection-type { 1988 mandatory true; 1989 description 1990 "Selects between available connection types."; 1991 case persistent-connection { 1992 container persistent { 1993 presence 1994 "Indicates that a persistent connection is to be 1995 maintained."; 1996 description 1997 "Maintain a persistent connection to the RESTCONF 1998 client. If the connection goes down, immediately 1999 start trying to reconnect to the RESTCONF server, 2000 using the reconnection strategy. 2002 This connection type minimizes any RESTCONF 2003 client to RESTCONF server data-transfer delay, 2004 albeit at the expense of holding resources 2005 longer."; 2006 } 2007 } 2008 case periodic-connection { 2009 container periodic { 2010 presence 2011 "Indicates that a periodic connection is to be 2012 maintained."; 2013 description 2014 "Periodically connect to the RESTCONF client. 2016 This connection type increases resource 2017 utilization, albeit with increased delay in 2018 RESTCONF client to RESTCONF client interactions. 2020 The RESTCONF client SHOULD gracefully close 2021 the underlying TLS connection upon completing 2022 planned activities. If the underlying TLS 2023 connection is not closed gracefully, the 2024 RESTCONF server MUST immediately attempt 2025 to reestablish the connection. 2027 In the case that the previous connection is 2028 still active (i.e., the RESTCONF client has not 2029 closed it yet), establishing a new connection 2030 is NOT RECOMMENDED."; 2032 leaf period { 2033 type uint16; 2034 units "minutes"; 2035 default "60"; 2036 description 2037 "Duration of time between periodic connections."; 2038 } 2039 leaf anchor-time { 2040 type yang:date-and-time { 2041 // constrained to minute-level granularity 2042 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2043 + '(Z|[\+\-]\d{2}:\d{2})'; 2044 } 2045 description 2046 "Designates a timestamp before or after which a 2047 series of periodic connections are determined. 2048 The periodic connections occur at a whole 2049 multiple interval from the anchor time. For 2050 example, for an anchor time is 15 minutes past 2051 midnight and a period interval of 24 hours, then 2052 a periodic connection will occur 15 minutes past 2053 midnight everyday."; 2054 } 2055 leaf idle-timeout { 2056 type uint16; 2057 units "seconds"; 2058 default "120"; // two minutes 2059 description 2060 "Specifies the maximum number of seconds that 2061 the underlying TCP session may remain idle. 2062 A TCP session will be dropped if it is idle 2063 for an interval longer than this number of 2064 seconds. If set to zero, then the server 2065 will never drop a session because it is idle."; 2066 } 2067 } 2068 } 2069 } 2070 } 2071 container reconnect-strategy { 2072 description 2073 "The reconnection strategy directs how a RESTCONF server 2074 reconnects to a RESTCONF client after discovering its 2075 connection to the client has dropped, even if due to a 2076 reboot. The RESTCONF server starts with the specified 2077 endpoint and tries to connect to it max-attempts times 2078 before trying the next endpoint in the list (round 2079 robin)."; 2080 leaf start-with { 2081 type enumeration { 2082 enum first-listed { 2083 description 2084 "Indicates that reconnections should start with 2085 the first endpoint listed."; 2086 } 2087 enum last-connected { 2088 description 2089 "Indicates that reconnections should start with 2090 the endpoint last connected to. If no previous 2091 connection has ever been established, then the 2092 first endpoint configured is used. RESTCONF 2093 servers SHOULD be able to remember the last 2094 endpoint connected to across reboots."; 2095 } 2096 enum random-selection { 2097 description 2098 "Indicates that reconnections should start with 2099 a random endpoint."; 2100 } 2101 } 2102 default "first-listed"; 2103 description 2104 "Specifies which of the RESTCONF client's endpoints 2105 the RESTCONF server should start with when trying 2106 to connect to the RESTCONF client."; 2107 } 2108 leaf max-attempts { 2109 type uint8 { 2110 range "1..max"; 2111 } 2112 default "3"; 2113 description 2114 "Specifies the number times the RESTCONF server tries 2115 to connect to a specific endpoint before moving on to 2116 the next endpoint in the list (round robin)."; 2117 } 2118 } 2119 } // restconf-client 2120 } // call-home 2121 } // restconf-server-app-grouping 2123 // Protocol accessible node for servers that implement this module. 2124 container restconf-server { 2125 uses restconf-server-app-grouping; 2126 description 2127 "Top-level container for RESTCONF server configuration."; 2128 } 2129 } 2131 2133 4. Security Considerations 2135 4.1. The "ietf-restconf-client" YANG Module 2137 The "ietf-restconf-client" YANG module defines data nodes that are 2138 designed to be accessed via YANG based management protocols, such as 2139 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2140 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2141 with mutual authentication. 2143 The NETCONF access control model (NACM) [RFC8341] provides the means 2144 to restrict access for particular users to a pre-configured subset of 2145 all available protocol operations and content. 2147 None of the readable data nodes in this YANG module are considered 2148 sensitive or vulnerable in network environments. The NACM "default- 2149 deny-all" extension has not been set for any data nodes defined in 2150 this module. 2152 None of the writable data nodes in this YANG module are considered 2153 sensitive or vulnerable in network environments. The NACM "default- 2154 deny-write" extension has not been set for any data nodes defined in 2155 this module. 2157 This module does not define any RPCs, actions, or notifications, and 2158 thus the security consideration for such is not provided here. 2160 Please be aware that this module uses groupings defined in other RFCs 2161 that define data nodes that do set the NACM "default-deny-all" and 2162 "default-deny-write" extensions. 2164 4.2. The "ietf-restconf-server" YANG Module 2166 The "ietf-restconf-server" YANG module defines data nodes that are 2167 designed to be accessed via YANG based management protocols, such as 2168 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2169 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2170 with mutual authentication. 2172 The NETCONF access control model (NACM) [RFC8341] provides the means 2173 to restrict access for particular users to a pre-configured subset of 2174 all available protocol operations and content. 2176 None of the readable data nodes in this YANG module are considered 2177 sensitive or vulnerable in network environments. The NACM "default- 2178 deny-all" extension has not been set for any data nodes defined in 2179 this module. 2181 None of the writable data nodes in this YANG module are considered 2182 sensitive or vulnerable in network environments. The NACM "default- 2183 deny-write" extension has not been set for any data nodes defined in 2184 this module. 2186 This module does not define any RPCs, actions, or notifications, and 2187 thus the security consideration for such is not provided here. 2189 Please be aware that this module uses groupings defined in other RFCs 2190 that define data nodes that do set the NACM "default-deny-all" and 2191 "default-deny-write" extensions. 2193 5. IANA Considerations 2195 5.1. The "IETF XML" Registry 2197 This document registers two URIs in the "ns" subregistry of the IETF 2198 XML Registry [RFC3688]. Following the format in [RFC3688], the 2199 following registrations are requested: 2201 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2202 Registrant Contact: The IESG 2203 XML: N/A, the requested URI is an XML namespace. 2205 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2206 Registrant Contact: The IESG 2207 XML: N/A, the requested URI is an XML namespace. 2209 5.2. The "YANG Module Names" Registry 2211 This document registers two YANG modules in the YANG Module Names 2212 registry [RFC6020]. Following the format in [RFC6020], the following 2213 registrations are requested: 2215 name: ietf-restconf-client 2216 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2217 prefix: ncc 2218 reference: RFC IIII 2220 name: ietf-restconf-server 2221 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2222 prefix: ncs 2223 reference: RFC IIII 2225 6. References 2227 6.1. Normative References 2229 [I-D.ietf-netconf-http-client-server] 2230 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2231 Servers", Work in Progress, Internet-Draft, draft-ietf- 2232 netconf-http-client-server-08, 14 December 2021, 2233 . 2236 [I-D.ietf-netconf-keystore] 2237 Watsen, K., "A YANG Data Model for a Keystore", Work in 2238 Progress, Internet-Draft, draft-ietf-netconf-keystore-23, 2239 14 December 2021, . 2242 [I-D.ietf-netconf-tcp-client-server] 2243 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2244 and TCP Servers", Work in Progress, Internet-Draft, draft- 2245 ietf-netconf-tcp-client-server-11, 14 December 2021, 2246 . 2249 [I-D.ietf-netconf-tls-client-server] 2250 Watsen, K., "YANG Groupings for TLS Clients and TLS 2251 Servers", Work in Progress, Internet-Draft, draft-ietf- 2252 netconf-tls-client-server-26, 14 December 2021, 2253 . 2256 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2257 Requirement Levels", BCP 14, RFC 2119, 2258 DOI 10.17487/RFC2119, March 1997, 2259 . 2261 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2262 the Network Configuration Protocol (NETCONF)", RFC 6020, 2263 DOI 10.17487/RFC6020, October 2010, 2264 . 2266 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2267 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2268 . 2270 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2271 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2272 December 2014, . 2274 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2275 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2276 . 2278 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2279 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2280 . 2282 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2283 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2284 . 2286 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2287 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2288 May 2017, . 2290 6.2. Informative References 2292 [I-D.ietf-netconf-crypto-types] 2293 Watsen, K., "YANG Data Types and Groupings for 2294 Cryptography", Work in Progress, Internet-Draft, draft- 2295 ietf-netconf-crypto-types-21, 14 September 2021, 2296 . 2299 [I-D.ietf-netconf-netconf-client-server] 2300 Watsen, K., "NETCONF Client and Server Models", Work in 2301 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2302 client-server-24, 14 December 2021, 2303 . 2306 [I-D.ietf-netconf-restconf-client-server] 2307 Watsen, K., "RESTCONF Client and Server Models", Work in 2308 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2309 client-server-24, 14 December 2021, 2310 . 2313 [I-D.ietf-netconf-ssh-client-server] 2314 Watsen, K., "YANG Groupings for SSH Clients and SSH 2315 Servers", Work in Progress, Internet-Draft, draft-ietf- 2316 netconf-ssh-client-server-26, 14 December 2021, 2317 . 2320 [I-D.ietf-netconf-trust-anchors] 2321 Watsen, K., "A YANG Data Model for a Truststore", Work in 2322 Progress, Internet-Draft, draft-ietf-netconf-trust- 2323 anchors-16, 14 December 2021, 2324 . 2327 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2328 DOI 10.17487/RFC3688, January 2004, 2329 . 2331 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2332 and A. Bierman, Ed., "Network Configuration Protocol 2333 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2334 . 2336 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2337 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2338 . 2340 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2341 Access Control Model", STD 91, RFC 8341, 2342 DOI 10.17487/RFC8341, March 2018, 2343 . 2345 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2346 and R. Wilton, "Network Management Datastore Architecture 2347 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2348 . 2350 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2351 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2352 . 2354 Appendix A. Change Log 2356 This section is to be removed before publishing as an RFC. 2358 A.1. 00 to 01 2360 * Renamed "keychain" to "keystore". 2362 A.2. 01 to 02 2364 * Filled in previously missing 'ietf-restconf-client' module. 2366 * Updated the ietf-restconf-server module to accommodate new 2367 grouping 'ietf-tls-server-grouping'. 2369 A.3. 02 to 03 2371 * Refined use of tls-client-grouping to add a must statement 2372 indicating that the TLS client must specify a client-certificate. 2374 * Changed restconf-client??? to be a grouping (not a container). 2376 A.4. 03 to 04 2378 * Added RFC 8174 to Requirements Language Section. 2380 * Replaced refine statement in ietf-restconf-client to add a 2381 mandatory true. 2383 * Added refine statement in ietf-restconf-server to add a must 2384 statement. 2386 * Now there are containers and groupings, for both the client and 2387 server models. 2389 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2391 * Updated examples to inline key and certificates (no longer a 2392 leafref to keystore) 2394 A.5. 04 to 05 2396 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2398 * Updated examples to inline key and certificates (no longer a 2399 leafref to keystore) 2401 A.6. 05 to 06 2403 * Fixed change log missing section issue. 2405 * Updated examples to match latest updates to the crypto-types, 2406 trust-anchors, and keystore drafts. 2408 * Reduced line length of the YANG modules to fit within 69 columns. 2410 A.7. 06 to 07 2412 * removed "idle-timeout" from "persistent" connection config. 2414 * Added "random-selection" for reconnection-strategy's "starts-with" 2415 enum. 2417 * Replaced "connection-type" choice default (persistent) with 2418 "mandatory true". 2420 * Reduced the periodic-connection's "idle-timeout" from 5 to 2 2421 minutes. 2423 * Replaced reconnect-timeout with period/anchor-time combo. 2425 A.8. 07 to 08 2427 * Modified examples to be compatible with new crypto-types algs 2429 A.9. 08 to 09 2431 * Corrected use of "mandatory true" for "address" leafs. 2433 * Updated examples to reflect update to groupings defined in the 2434 keystore draft. 2436 * Updated to use groupings defined in new TCP and HTTP drafts. 2438 * Updated copyright date, boilerplate template, affiliation, and 2439 folding algorithm. 2441 A.10. 09 to 10 2443 * Reformatted YANG modules. 2445 A.11. 10 to 11 2447 * Adjusted for the top-level "demux container" added to groupings 2448 imported from other modules. 2450 * Added "must" expressions to ensure that keepalives are not 2451 configured for "periodic" connections. 2453 * Updated the boilerplate text in module-level "description" 2454 statement to match copyeditor convention. 2456 * Moved "expanded" tree diagrams to the Appendix. 2458 A.12. 11 to 12 2460 * Removed the 'must' statement limiting keepalives in periodic 2461 connections. 2463 * Updated models and examples to reflect removal of the "demux" 2464 containers in the imported models. 2466 * Updated the "periodic-connnection" description statements to 2467 better describe behavior when connections are not closed 2468 gracefully. 2470 * Updated text to better reference where certain examples come from 2471 (e.g., which Section in which draft). 2473 * In the server model, commented out the "must 'pinned-ca-certs or 2474 pinned-client-certs'" statement to reflect change made in the TLS 2475 draft whereby the trust anchors MAY be defined externally. 2477 * Replaced the 'listen', 'initiate', and 'call-home' features with 2478 boolean expressions. 2480 A.13. 12 to 13 2482 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2483 anchors/truststore/g + s/pinned.//) 2485 * In ietf-restconf-server, Added 'http-listen' (not https-listen) 2486 choice, to support case when server is behind a TLS-terminator. 2488 * Refactored server module to be more like other 'server' models. 2489 If folks like it, will also apply to the client model, as well as 2490 to both the netconf client/server models. Now the 'restconf- 2491 server-grouping' is just the RC-specific bits (i.e., the "demux" 2492 container minus the container), 'restconf-server- 2493 [listen|callhome]-stack-grouping' is the protocol stack for a 2494 single connection, and 'restconf-server-app-grouping' is 2495 effectively what was before (both listen+callhome for many 2496 inbound/outbound endpoints). 2498 A.14. 13 to 14 2500 * Updated examples to reflect ietf-crypto-types change (e.g., 2501 identities --> enumerations) 2503 * Adjusting from change in TLS client model (removing the top-level 2504 'certificate' container). 2506 * Added "external-endpoint" to the "http-listen" choice in ietf- 2507 restconf-server. 2509 A.15. 14 to 15 2511 * Added missing "or https-listen" clause in a "must" expression. 2513 * Refactored the client module similar to how the server module was 2514 refactored in -13. Now the 'restconf-client-grouping' is just the 2515 RC-specific bits, the 'restconf-client-[initiate|listen]-stack- 2516 grouping' is the protocol stack for a single connection, and 2517 'restconf-client-app-grouping' is effectively what was before 2518 (both listen+callhome for many inbound/outbound endpoints). 2520 A.16. 15 to 16 2522 * Added refinement to make "cert-to-name/fingerprint" be mandatory 2523 false. 2525 * Commented out refinement to "tls-server-grouping/client- 2526 authentication" until a better "must" expression is defined. 2528 * Updated restconf-client example to reflect that http-client- 2529 grouping no longer has a "protocol-version" leaf. 2531 A.17. 16 to 17 2533 * Updated examples to include the "*-key-format" nodes. 2535 * Updated examples to remove the "required" nodes. 2537 A.18. 17 to 18 2539 * Updated examples to reflect new "bag" addition to truststore. 2541 A.19. 18 to 19 2543 * Updated examples to remove the 'algorithm' nodes. 2545 * Updated examples to reflect the new TLS keepalives structure. 2547 * Removed the 'protocol-versions' node from the restconf-server 2548 examples. 2550 * Added a "Note to Reviewers" note to first page. 2552 A.20. 19 to 20 2554 * Moved and changed "must" statement so that either TLS *or* HTTP 2555 auth must be configured. 2557 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2558 diagrams]. 2560 * Updated the Security Considerations section. 2562 A.21. 20 to 21 2564 * Cleaned up titles in the IANA Consideratons section 2566 * Fixed issues found by the SecDir review of the "keystore" draft. 2568 A.22. 21 to 22 2570 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 2572 A.23. 22 to 23 2574 * Further clarified why some 'presence' statements are present. 2576 * Addressed nits found in YANG Doctor reviews. 2578 * Aligned modules with `pyang -f` formatting. 2580 A.24. 23 to 24 2582 * Removed Appendix A with fully-expanded tree diagrams. 2584 * Replaced "base64encodedvalue==" with "BASE64VALUE=" in examples. 2586 * Minor editorial nits 2588 A.25. 24 to 25 2590 * Fixed up the 'WG Web' and 'WG List' lines in YANG module(s) 2592 * Fixed up copyright (i.e., s/Simplified/Revised/) in YANG module(s) 2594 Acknowledgements 2596 The authors would like to thank for following for lively discussions 2597 on list and in the halls (ordered by first name): Alan Luchuk, Andy 2598 Bierman, Balazs Kovacs, Benoit Claise, Bert Wijnen David Lamparter, 2599 Juergen Schoenwaelder, Ladislav Lhotka, Martin Bjoerklund, Mehmet 2600 Ersue, Phil Shafer, Radek Krejci, Ramkumar Dhanapal, Sean Turner, and 2601 Tom Petch. 2603 Author's Address 2605 Kent Watsen 2606 Watsen Networks 2607 Email: kent+ietf@watsen.net