idnits 2.17.1 draft-ietf-netconf-restconf-client-server-21.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 1212 has weird spacing: '...address ine...' -- The document date (20 August 2020) is 1343 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-04 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-07 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-21 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-17 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-20 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-21 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-12 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 20 August 2020 5 Expires: 21 February 2021 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-21 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 * "2020-08-20" --> 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 21 February 2021. 79 Copyright Notice 81 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . 5 98 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 99 2. The "ietf-restconf-client" Module . . . . . . . . . . . . . . 5 100 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 101 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 10 102 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 14 103 3. The "ietf-restconf-server" Module . . . . . . . . . . . . . . 24 104 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 24 105 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 106 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 33 107 4. Security Considerations . . . . . . . . . . . . . . . . . . . 45 108 4.1. The "ietf-restconf-client" YANG Module . . . . . . . . . 45 109 4.2. The "ietf-restconf-server" YANG Module . . . . . . . . . 46 110 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 111 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 46 112 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 47 113 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 114 6.1. Normative References . . . . . . . . . . . . . . . . . . 47 115 6.2. Informative References . . . . . . . . . . . . . . . . . 48 116 Appendix A. Expanded Tree Diagrams . . . . . . . . . . . . . . . 50 117 A.1. Expanded Tree Diagram for 'ietf-restconf-client' . . . . 50 118 A.2. Expanded Tree Diagram for 'ietf-restconf-server' . . . . 50 119 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 50 120 B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 50 121 B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 51 122 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 51 123 B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 51 124 B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 51 125 B.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 51 126 B.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 52 127 B.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 52 128 B.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 52 129 B.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 52 130 B.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 52 131 B.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 53 132 B.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 53 133 B.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 53 134 B.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 54 135 B.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 54 136 B.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 54 137 B.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 54 138 B.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 54 139 B.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 54 140 B.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 55 141 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 55 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 55 144 1. Introduction 146 This document defines two YANG [RFC7950] modules, one module to 147 configure a RESTCONF client and the other module to configure a 148 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446] 149 transport protocol with both standard RESTCONF and RESTCONF Call Home 150 connections [RFC8071]. 152 1.1. Relation to other RFCs 154 This document presents one or more YANG modules [RFC7950] that are 155 part of a collection of RFCs that work together to define 156 configuration modules for clients and servers of both the NETCONF 157 [RFC6241] and RESTCONF [RFC8040] protocols. 159 The modules have been defined in a modular fashion to enable their 160 use by other efforts, some of which are known to be in progress at 161 the time of this writing, with many more expected to be defined in 162 time. 164 The normative dependency relationship between the various RFCs in the 165 collection is presented in the below diagram. The labels in the 166 diagram represent the primary purpose provided by each RFC. 167 Hyperlinks to each RFC are provided below the diagram. 169 crypto-types 170 ^ ^ 171 / \ 172 / \ 173 truststore keystore 174 ^ ^ ^ ^ 175 | +---------+ | | 176 | | | | 177 | +------------+ | 178 tcp-client-server | / | | 179 ^ ^ ssh-client-server | | 180 | | ^ tls-client-server 181 | | | ^ ^ http-client-server 182 | | | | | ^ 183 | | | +-----+ +---------+ | 184 | | | | | | 185 | +-----------|--------|--------------+ | | 186 | | | | | | 187 +-----------+ | | | | | 188 | | | | | | 189 | | | | | | 190 netconf-client-server restconf-client-server 192 +=======================+===========================================+ 193 | Label in Diagram | Originating RFC | 194 +=======================+===========================================+ 195 | crypto-types | [I-D.ietf-netconf-crypto-types] | 196 +-----------------------+-------------------------------------------+ 197 | truststore | [I-D.ietf-netconf-trust-anchors] | 198 +-----------------------+-------------------------------------------+ 199 | keystore | [I-D.ietf-netconf-keystore] | 200 +-----------------------+-------------------------------------------+ 201 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 202 +-----------------------+-------------------------------------------+ 203 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 204 +-----------------------+-------------------------------------------+ 205 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 206 +-----------------------+-------------------------------------------+ 207 | http-client-server | [I-D.ietf-netconf-http-client-server] | 208 +-----------------------+-------------------------------------------+ 209 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 210 +-----------------------+-------------------------------------------+ 211 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 212 +-----------------------+-------------------------------------------+ 214 Table 1: Label to RFC Mapping 216 1.2. Specification Language 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 220 "OPTIONAL" in this document are to be interpreted as described in BCP 221 14 [RFC2119] [RFC8174] when, and only when, they appear in all 222 capitals, as shown here. 224 1.3. Adherence to the NMDA 226 This document in compliant with the Network Management Datastore 227 Architecture (NMDA) [RFC8342]. For instance, as described in 228 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 229 trust anchors and keys installed during manufacturing are expected to 230 appear in . 232 2. The "ietf-restconf-client" Module 234 The RESTCONF client model presented in this section supports both 235 clients initiating connections to servers, as well as clients 236 listening for connections from servers calling home. 238 YANG feature statements are used to enable implementations to 239 advertise which potentially uncommon parts of the model the RESTCONF 240 client supports. 242 2.1. Data Model Overview 244 This section provides an overview of the "ietf-restconf-client" 245 module in terms of its features and groupings. 247 2.1.1. Features 249 The following diagram lists all the "feature" statements defined in 250 the "ietf-restconf-client" module: 252 Features: 253 +-- https-initiate 254 +-- http-listen 255 +-- https-listen 257 | The diagram above uses syntax that is similar to but not 258 | defined in [RFC8340]. 260 2.1.2. Groupings 262 The following diagram lists all the "grouping" statements defined in 263 the "ietf-restconf-client" module: 265 Groupings: 266 +-- restconf-client-grouping 267 +-- restconf-client-initiate-stack-grouping 268 +-- restconf-client-listen-stack-grouping 269 +-- restconf-client-app-grouping 271 | The diagram above uses syntax that is similar to but not 272 | defined in [RFC8340]. 274 Each of these groupings are presented in the following subsections. 276 2.1.2.1. The "restconf-client-grouping" Grouping 278 The following tree diagram [RFC8340] illustrates the "restconf- 279 client-grouping" grouping: 281 grouping restconf-client-grouping ---> 283 Comments: 285 * This grouping does not define any nodes, but is maintained so that 286 downstream modules can augment nodes into it if needed. 288 * The "restconf-client-grouping" defines, if it can be called that, 289 the configuration for just "RESTCONF" part of a protocol stack. 290 It does not, for instance, define any configuration for the "TCP", 291 "TLS", or "HTTP" protocol layers (for that, see Section 2.1.2.2 292 and Section 2.1.2.3). 294 2.1.2.2. The "restconf-client-initiate-stack-grouping" Grouping 296 The following tree diagram [RFC8340] illustrates the "restconf- 297 client-initiate-stack-grouping" grouping: 299 grouping restconf-client-initiate-stack-grouping 300 +-- (transport) 301 +--:(https) {https-initiate}? 302 +-- https 303 +-- tcp-client-parameters 304 | +---u tcpc:tcp-client-grouping 305 +-- tls-client-parameters 306 | +---u tlsc:tls-client-grouping 307 +-- http-client-parameters 308 | +---u httpc:http-client-grouping 309 +-- restconf-client-parameters 310 +---u rcc:restconf-client-grouping 312 Comments: 314 * The "restconf-client-initiate-stack-grouping" defines the 315 configuration for a full RESTCONF protocol stack, for RESTCONF 316 clients that initiate connections to RESTCONF servers, as opposed 317 to receiving call-home [RFC8071] connections. 319 * The "transport" choice node enables transport options to be 320 configured. This document only defines an "https" option, but 321 other options MAY be augmented in. 323 * For the referenced grouping statement(s): 325 - The "tcp-client-grouping" grouping is discussed in 326 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 327 - The "tls-client-grouping" grouping is discussed in 328 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 329 - The "http-client-grouping" grouping is discussed in 330 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 331 - The "restconf-client-grouping" grouping is discussed in 332 Section 2.1.2.1 in this document. 334 2.1.2.3. The "restconf-client-listen-stack-grouping" Grouping 336 The following tree diagram [RFC8340] illustrates the "restconf- 337 client-listen-stack-grouping" grouping: 339 grouping restconf-client-listen-stack-grouping 340 +-- (transport) 341 +--:(http) {http-listen}? 342 | +-- http 343 | +-- tcp-server-parameters 344 | | +---u tcps:tcp-server-grouping 345 | +-- http-client-parameters 346 | | +---u httpc:http-client-grouping 347 | +-- restconf-client-parameters 348 | +---u rcc:restconf-client-grouping 349 +--:(https) {https-listen}? 350 +-- https 351 +-- tcp-server-parameters 352 | +---u tcps:tcp-server-grouping 353 +-- tls-client-parameters 354 | +---u tlsc:tls-client-grouping 355 +-- http-client-parameters 356 | +---u httpc:http-client-grouping 357 +-- restconf-client-parameters 358 +---u rcc:restconf-client-grouping 360 Comments: 362 * The "restconf-client-listen-stack-grouping" defines the 363 configuration for a full RESTCONF protocol stack, for RESTCONF 364 clients that receive call-home [RFC8071] connections from RESTCONF 365 servers. 367 * The "transport" choice node enables both the HTTP and HTTPS 368 transports to be configured, with each option enabled by a 369 "feature" statement. Note that RESTCONF requires HTTPS, the HTTP 370 option is provided to support cases where a TLS-terminator is 371 deployed in front of the RESTCONF-client. 373 * For the referenced grouping statement(s): 375 - The "tcp-server-grouping" grouping is discussed in 376 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 377 - The "tls-client-grouping" grouping is discussed in 378 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 379 - The "http-client-grouping" grouping is discussed in 380 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 382 - The "restconf-client-grouping" grouping is discussed in 383 Section 2.1.2.1 in this document. 385 2.1.2.4. The "restconf-client-app-grouping" Grouping 387 The following tree diagram [RFC8340] illustrates the "restconf- 388 client-app-grouping" grouping: 390 grouping restconf-client-app-grouping 391 +-- initiate! {https-initiate}? 392 | +-- restconf-server* [name] 393 | +-- name? string 394 | +-- endpoints 395 | | +-- endpoint* [name] 396 | | +-- name? string 397 | | +---u restconf-client-initiate-stack-grouping 398 | +-- connection-type 399 | | +-- (connection-type) 400 | | +--:(persistent-connection) 401 | | | +-- persistent! 402 | | +--:(periodic-connection) 403 | | +-- periodic! 404 | | +-- period? uint16 405 | | +-- anchor-time? yang:date-and-time 406 | | +-- idle-timeout? uint16 407 | +-- reconnect-strategy 408 | +-- start-with? enumeration 409 | +-- max-attempts? uint8 410 +-- listen! {http-listen or https-listen}? 411 +-- idle-timeout? uint16 412 +-- endpoint* [name] 413 +-- name? string 414 +---u restconf-client-listen-stack-grouping 416 Comments: 418 * The "restconf-client-app-grouping" defines the configuration for a 419 RESTCONF client that supports both initiating connections to 420 RESTCONF servers as well as receiving call-home connections from 421 RESTCONF servers. 423 * Both the "initiate" and "listen" subtrees must be enabled by 424 "feature" statements. 426 * For the referenced grouping statement(s): 428 - The "restconf-client-initiate-stack-grouping" grouping is 429 discussed in Section 2.1.2.2 in this document. 431 - The "restconf-client-listen-stack-grouping" grouping is 432 discussed in Section 2.1.2.3 in this document. 434 2.1.3. Protocol-accessible Nodes 436 The following tree diagram [RFC8340] lists all the protocol- 437 accessible nodes defined in the "ietf-restconf-client" module: 439 module: ietf-restconf-client 440 +--rw restconf-client 441 +---u restconf-client-app-grouping 443 Comments: 445 * Protocol-accessible nodes are those nodes that are accessible when 446 the module is "implemented", as described in Section 5.6.5 of 447 [RFC7950]. 449 * For the "ietf-restconf-client" module, the protocol-accessible 450 nodes are an instance of the "restconf-client-app-grouping" 451 discussed in Section 2.1.2.4 grouping. 453 * The reason for why "restconf-client-app-grouping" exists separate 454 from the protocol-accessible nodes definition is so as to enable 455 instances of restconf-client-app-grouping to be instantiated in 456 other locations, as may be needed or desired by some modules. 458 2.2. Example Usage 460 The following example illustrates configuring a RESTCONF client to 461 initiate connections, as well as to listen for call-home connections. 463 This example is consistent with the examples presented in Section 2.2 464 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 465 [I-D.ietf-netconf-keystore]. 467 =============== NOTE: '\' line wrapping per RFC 8792 ================ 469 473 474 475 476 corp-fw1 477 478 479 corp-fw1.example.com 480 481 482 corp-fw1.example.com 483 484 15 485 3 486 30 487 488 489 490 491 492 493 rsa-asymmetric-key 495 ex-rsa-cert 496 497 498 499 500 501 trusted-server-ca-certs 503 504 505 trusted-server-ee-certs 507 508 509 510 511 30 512 3 513 514 515 516 517 518 519 bob 520 secret 521 522 523 524 525 526 527 corp-fw2.example.com 528 529 530 corp-fw2.example.com 531 532 15 533 3 534 30 535 536 537 538 539 540 541 rsa-asymmetric-key 543 ex-rsa-cert 544 545 546 547 548 549 trusted-server-ca-certs 551 552 553 trusted-server-ee-certs 555 556 557 558 559 30 560 3 561 562 563 564 565 566 567 bob 568 secret 569 570 571 572 573 574 575 576 577 578 579 581 582 583 584 Intranet-facing listener 585 586 587 11.22.33.44 588 589 590 591 592 593 rsa-asymmetric-key 594 ex-rsa-cert 595 596 597 598 599 600 trusted-server-ca-certs 602 603 604 trusted-server-ee-certs 606 607 608 609 610 611 612 613 614 615 bob 616 secret 617 618 619 620 621 622 624 626 2.3. YANG Module 628 This YANG module has normative references to [RFC6991], [RFC8040], 629 and [RFC8071], [I-D.ietf-netconf-tcp-client-server], 630 [I-D.ietf-netconf-tls-client-server], and 631 [I-D.ietf-netconf-http-client-server]. 633 file "ietf-restconf-client@2020-08-20.yang" 635 module ietf-restconf-client { 636 yang-version 1.1; 637 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 638 prefix rcc; 640 import ietf-yang-types { 641 prefix yang; 642 reference 643 "RFC 6991: Common YANG Data Types"; 644 } 646 import ietf-tcp-client { 647 prefix tcpc; 648 reference 649 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 650 } 652 import ietf-tcp-server { 653 prefix tcps; 654 reference 655 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 656 } 658 import ietf-tls-client { 659 prefix tlsc; 660 reference 661 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 662 } 664 import ietf-http-client { 665 prefix httpc; 666 reference 667 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 668 } 670 organization 671 "IETF NETCONF (Network Configuration) Working Group"; 673 contact 674 "WG Web: 675 WG List: 676 Author: Kent Watsen 677 Author: Gary Wu "; 679 description 680 "This module contains a collection of YANG definitions 681 for configuring RESTCONF clients. 683 Copyright (c) 2020 IETF Trust and the persons identified 684 as authors of the code. All rights reserved. 686 Redistribution and use in source and binary forms, with 687 or without modification, is permitted pursuant to, and 688 subject to the license terms contained in, the Simplified 689 BSD License set forth in Section 4.c of the IETF Trust's 690 Legal Provisions Relating to IETF Documents 691 (https://trustee.ietf.org/license-info). 693 This version of this YANG module is part of RFC IIII 694 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 695 itself for full legal notices. 697 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 698 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 699 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 700 are to be interpreted as described in BCP 14 (RFC 2119) 701 (RFC 8174) when, and only when, they appear in all 702 capitals, as shown here."; 704 revision 2020-08-20 { 705 description 706 "Initial version"; 707 reference 708 "RFC IIII: RESTCONF Client and Server Models"; 709 } 711 // Features 713 feature https-initiate { 714 description 715 "The 'https-initiate' feature indicates that the RESTCONF 716 client supports initiating HTTPS connections to RESTCONF 717 servers. This feature exists as HTTPS might not be a 718 mandatory to implement transport in the future."; 719 reference 720 "RFC 8040: RESTCONF Protocol"; 722 } 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 doesn't 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"; 819 reference 820 "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 "Enables client to initiate TCP connections"; 919 description 920 "Configures client initiating underlying TCP connections."; 921 list restconf-server { 922 key "name"; 923 min-elements 1; 924 description 925 "List of RESTCONF servers the RESTCONF client is to 926 maintain simultaneous connections with."; 927 leaf name { 928 type string; 929 description 930 "An arbitrary name for the RESTCONF server."; 931 } 932 container endpoints { 933 description 934 "Container for the list of endpoints."; 935 list endpoint { 936 key "name"; 937 min-elements 1; 938 ordered-by user; 939 description 940 "A non-empty user-ordered list of endpoints for this 941 RESTCONF client to try to connect to in sequence. 942 Defining more than one enables high-availability."; 943 leaf name { 944 type string; 945 description 946 "An arbitrary name for this endpoint."; 947 } 948 uses restconf-client-initiate-stack-grouping; 949 } 950 } 951 container connection-type { 952 description 953 "Indicates the RESTCONF client's preference for how 954 the RESTCONF connection is maintained."; 955 choice connection-type { 956 mandatory true; 957 description 958 "Selects between available connection types."; 959 case persistent-connection { 960 container persistent { 961 presence "Indicates that a persistent connection 962 is to be maintained."; 964 description 965 "Maintain a persistent connection to the 966 RESTCONF server. If the connection goes down, 967 immediately start trying to reconnect to the 968 RESTCONF server, using the reconnection strategy. 970 This connection type minimizes any RESTCONF server 971 to RESTCONF client data-transfer delay, albeit 972 at the expense of holding resources longer."; 973 } 974 } 975 case periodic-connection { 976 container periodic { 977 presence "Indicates that a periodic connection is 978 to be maintained."; 979 description 980 "Periodically connect to the RESTCONF server. 982 This connection type increases resource 983 utilization, albeit with increased delay 984 in RESTCONF server to RESTCONF client 985 interactions. 987 The RESTCONF client SHOULD gracefully close 988 the underlying TLS connection upon completing 989 planned activities. 991 In the case that the previous connection is 992 still active, establishing a new connection 993 is NOT RECOMMENDED."; 994 leaf period { 995 type uint16; 996 units "minutes"; 997 default "60"; 998 description 999 "Duration of time between periodic 1000 connections."; 1001 } 1002 leaf anchor-time { 1003 type yang:date-and-time { 1004 // constrained to minute-level granularity 1005 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1006 + '(Z|[\+\-]\d{2}:\d{2})'; 1007 } 1008 description 1009 "Designates a timestamp before or after which 1010 a series of periodic connections are 1011 determined. The periodic connections occur 1012 at a whole multiple interval from the anchor 1013 time. For example, for an anchor time is 15 1014 minutes past midnight and a period interval 1015 of 24 hours, then a periodic connection will 1016 occur 15 minutes past midnight everyday."; 1017 } 1018 leaf idle-timeout { 1019 type uint16; 1020 units "seconds"; 1021 default 120; // two minutes 1022 description 1023 "Specifies the maximum number of seconds 1024 that the underlying TCP session may remain 1025 idle. A TCP session will be dropped if it 1026 is idle for an interval longer than this 1027 number of seconds If set to zero, then the 1028 RESTCONF client will never drop a session 1029 because it is idle."; 1030 } 1031 } 1032 } // periodic-connection 1033 } // connection-type 1034 } // connection-type 1035 container reconnect-strategy { 1036 description 1037 "The reconnection strategy directs how a RESTCONF 1038 client reconnects to a RESTCONF server, after 1039 discovering its connection to the server has 1040 dropped, even if due to a reboot. The RESTCONF 1041 client starts with the specified endpoint and 1042 tries to connect to it max-attempts times before 1043 trying the next endpoint in the list (round 1044 robin)."; 1045 leaf start-with { 1046 type enumeration { 1047 enum first-listed { 1048 description 1049 "Indicates that reconnections should start 1050 with the first endpoint listed."; 1051 } 1052 enum last-connected { 1053 description 1054 "Indicates that reconnections should start 1055 with the endpoint last connected to. If 1056 no previous connection has ever been 1057 established, then the first endpoint 1058 configured is used. RESTCONF clients 1059 SHOULD be able to remember the last 1060 endpoint connected to across reboots."; 1061 } 1062 enum random-selection { 1063 description 1064 "Indicates that reconnections should start with 1065 a random endpoint."; 1066 } 1067 } 1068 default "first-listed"; 1069 description 1070 "Specifies which of the RESTCONF server's 1071 endpoints the RESTCONF client should start 1072 with when trying to connect to the RESTCONF 1073 server."; 1074 } 1075 leaf max-attempts { 1076 type uint8 { 1077 range "1..max"; 1078 } 1079 default "3"; 1080 description 1081 "Specifies the number times the RESTCONF client 1082 tries to connect to a specific endpoint before 1083 moving on to the next endpoint in the list 1084 (round robin)."; 1085 } 1086 } 1087 } 1088 } // initiate 1089 container listen { 1090 if-feature "http-listen or https-listen"; 1091 presence "Enables client to accept call-home connections"; 1092 description 1093 "Configures the client to accept call-home TCP connections."; 1094 leaf idle-timeout { 1095 type uint16; 1096 units "seconds"; 1097 default 3600; // one hour 1098 description 1099 "Specifies the maximum number of seconds that an 1100 underlying TCP session may remain idle. A TCP session 1101 will be dropped if it is idle for an interval longer 1102 then this number of seconds. If set to zero, then 1103 the server will never drop a session because it is 1104 idle. Sessions that have a notification subscription 1105 active are never dropped."; 1106 } 1107 list endpoint { 1108 key "name"; 1109 min-elements 1; 1110 description 1111 "List of endpoints to listen for RESTCONF connections."; 1112 leaf name { 1113 type string; 1114 description 1115 "An arbitrary name for the RESTCONF listen endpoint."; 1116 } 1117 uses restconf-client-listen-stack-grouping; 1118 } 1119 } 1120 } // restconf-client-app-grouping 1122 // Protocol accessible node, for servers that implement 1123 // this module. 1124 container restconf-client { 1125 uses restconf-client-app-grouping; 1126 description 1127 "Top-level container for RESTCONF client configuration."; 1128 } 1129 } 1131 1133 3. The "ietf-restconf-server" Module 1135 The RESTCONF server model presented in this section supports both 1136 listening for connections as well as initiating call-home 1137 connections. 1139 YANG feature statements are used to enable implementations to 1140 advertise which potentially uncommon parts of the model the RESTCONF 1141 server supports. 1143 3.1. Data Model Overview 1145 This section provides an overview of the "ietf-restconf-server" 1146 module in terms of its features and groupings. 1148 3.1.1. Features 1150 The following diagram lists all the "feature" statements defined in 1151 the "ietf-restconf-server" module: 1153 Features: 1154 +-- http-listen 1155 +-- https-listen 1156 +-- https-call-home 1158 | The diagram above uses syntax that is similar to but not 1159 | defined in [RFC8340]. 1161 3.1.2. Groupings 1163 The following diagram lists all the "grouping" statements defined in 1164 the "ietf-restconf-server" module: 1166 Groupings: 1167 +-- restconf-server-grouping 1168 +-- restconf-server-listen-stack-grouping 1169 +-- restconf-server-callhome-stack-grouping 1170 +-- restconf-server-app-grouping 1172 | The diagram above uses syntax that is similar to but not 1173 | defined in [RFC8340]. 1175 Each of these groupings are presented in the following subsections. 1177 3.1.2.1. The "restconf-server-grouping" Grouping 1179 The following tree diagram [RFC8340] illustrates the "restconf- 1180 server-grouping" grouping: 1182 grouping restconf-server-grouping 1183 +-- client-identity-mappings 1184 +---u x509c2n:cert-to-name 1186 Comments: 1188 * The "restconf-server-grouping" defines the configuration for just 1189 "RESTCONF" part of a protocol stack. It does not, for instance, 1190 define any configuration for the "TCP", "TLS", or "HTTP" protocol 1191 layers (for that, see Section 3.1.2.2 and Section 3.1.2.3). 1193 * The "client-identity-mappings" node, which must be enabled by 1194 "feature" statements, defines a mapping from certificate fields to 1195 RESTCONF user names. 1197 * For the referenced grouping statement(s): 1199 - The "cert-to-name" grouping is discussed in Section 4.1 of 1200 [RFC7407]. 1202 3.1.2.2. The "restconf-server-listen-stack-grouping" Grouping 1204 The following tree diagram [RFC8340] illustrates the "restconf- 1205 server-listen-stack-grouping" grouping: 1207 grouping restconf-server-listen-stack-grouping 1208 +-- (transport) 1209 +--:(http) {http-listen}? 1210 | +-- http 1211 | +-- external-endpoint! 1212 | | +-- address inet:ip-address 1213 | | +-- port? inet:port-number 1214 | +-- tcp-server-parameters 1215 | | +---u tcps:tcp-server-grouping 1216 | +-- http-server-parameters 1217 | | +---u https:http-server-grouping 1218 | +-- restconf-server-parameters 1219 | +---u rcs:restconf-server-grouping 1220 +--:(https) {https-listen}? 1221 +-- https 1222 +-- tcp-server-parameters 1223 | +---u tcps:tcp-server-grouping 1224 +-- tls-server-parameters 1225 | +---u tlss:tls-server-grouping 1226 +-- http-server-parameters 1227 | +---u https:http-server-grouping 1228 +-- restconf-server-parameters 1229 +---u rcs:restconf-server-grouping 1231 Comments: 1233 * The "restconf-server-listen-stack-grouping" defines the 1234 configuration for a full RESTCONF protocol stack for RESTCONF 1235 servers that listen for standard connections from RESTCONF 1236 clients, as opposed to initiating call-home [RFC8071] connections. 1238 * The "transport" choice node enables both the HTTP and HTTPS 1239 transports to be configured, with each option enabled by a 1240 "feature" statement. The HTTP option is provided to support cases 1241 where a TLS-terminator is deployed in front of the RESTCONF- 1242 server. 1244 * For the referenced grouping statement(s): 1246 - The "tcp-server-grouping" grouping is discussed in 1247 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1248 - The "tls-server-grouping" grouping is discussed in 1249 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1251 - The "http-server-grouping" grouping is discussed in 1252 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1253 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1254 of this document. 1256 3.1.2.3. The "restconf-server-callhome-stack-grouping" Grouping 1258 The following tree diagram [RFC8340] illustrates the "restconf- 1259 server-callhome-stack-grouping" grouping: 1261 grouping restconf-server-callhome-stack-grouping 1262 +-- (transport) 1263 +--:(https) {https-listen}? 1264 +-- https 1265 +-- tcp-client-parameters 1266 | +---u tcpc:tcp-client-grouping 1267 +-- tls-server-parameters 1268 | +---u tlss:tls-server-grouping 1269 +-- http-server-parameters 1270 | +---u https:http-server-grouping 1271 +-- restconf-server-parameters 1272 +---u rcs:restconf-server-grouping 1274 Comments: 1276 * The "restconf-server-callhome-stack-grouping" defines the 1277 configuration for a full RESTCONF protocol stack, for RESTCONF 1278 servers that initiate call-home [RFC8071] connections to RESTCONF 1279 clients. 1281 * The "transport" choice node enables transport options to be 1282 configured. This document only defines an "https" option, but 1283 other options MAY be augmented in. 1285 * For the referenced grouping statement(s): 1287 - The "tcp-client-grouping" grouping is discussed in 1288 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1289 - The "tls-server-grouping" grouping is discussed in 1290 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1291 - The "http-server-grouping" grouping is discussed in 1292 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1293 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1294 of this document. 1296 3.1.2.4. The "restconf-server-app-grouping" Grouping 1298 The following tree diagram [RFC8340] illustrates the "restconf- 1299 server-app-grouping" grouping: 1301 grouping restconf-server-app-grouping 1302 +-- listen! {http-listen or https-listen}? 1303 | +-- endpoint* [name] 1304 | +-- name? string 1305 | +---u restconf-server-listen-stack-grouping 1306 +-- call-home! {https-call-home}? 1307 +-- restconf-client* [name] 1308 +-- name? string 1309 +-- endpoints 1310 | +-- endpoint* [name] 1311 | +-- name? string 1312 | +---u restconf-server-callhome-stack-grouping 1313 +-- connection-type 1314 | +-- (connection-type) 1315 | +--:(persistent-connection) 1316 | | +-- persistent! 1317 | +--:(periodic-connection) 1318 | +-- periodic! 1319 | +-- period? uint16 1320 | +-- anchor-time? yang:date-and-time 1321 | +-- idle-timeout? uint16 1322 +-- reconnect-strategy 1323 +-- start-with? enumeration 1324 +-- max-attempts? uint8 1326 Comments: 1328 * The "restconf-server-app-grouping" defines the configuration for a 1329 RESTCONF server that supports both listening for connections from 1330 RESTCONF clients as well as initiatiating call-home connections to 1331 RESTCONF clients. 1333 * Both the "listen" and "call-home" subtrees must be enabled by 1334 "feature" statements. 1336 * For the referenced grouping statement(s): 1338 - The "restconf-server-listen-stack-grouping" grouping is 1339 discussed in Section 3.1.2.2 in this document. 1340 - The "restconf-server-callhome-stack-grouping" grouping is 1341 discussed in Section 3.1.2.3 in this document. 1343 3.1.3. Protocol-accessible Nodes 1345 The following tree diagram [RFC8340] lists all the protocol- 1346 accessible nodes defined in the "ietf-restconf-server" module: 1348 module: ietf-restconf-server 1349 +--rw restconf-server 1350 +---u restconf-server-app-grouping 1352 Comments: 1354 * Protocol-accessible nodes are those nodes that are accessible when 1355 the module is "implemented", as described in Section 5.6.5 of 1356 [RFC7950]. 1358 * For the "ietf-restconf-server" module, the protocol-accessible 1359 nodes are an instance of the "restconf-server-app-grouping" 1360 discussed in Section 3.1.2.4 grouping. 1362 * The reason for why "restconf-server-app-grouping" exists separate 1363 from the protocol-accessible nodes definition is so as to enable 1364 instances of restconf-server-app-grouping to be instantiated in 1365 other locations, as may be needed or desired by some modules. 1367 3.2. Example Usage 1369 The following example illustrates configuring a RESTCONF server to 1370 listen for RESTCONF client connections, as well as configuring call- 1371 home to one RESTCONF client. 1373 This example is consistent with the examples presented in Section 2.2 1374 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 1375 [I-D.ietf-netconf-keystore]. 1377 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1379 1384 1385 1386 1387 restconf/https 1388 1389 1390 11.22.33.44 1392 1393 1394 1395 1396 1397 rsa-asymmetric-key 1398 ex-rsa-cert 1399 1400 1401 1402 1403 1404 trusted-client-ca-certs 1406 1407 1408 trusted-client-ee-certs 1410 1411 1412 1413 1414 1415 1416 1417 foo.example.com 1418 1419 1420 1421 1422 1 1423 11:0A:05:11:00 1424 x509c2n:specified 1425 scooby-doo 1426 1427 1428 2 1429 x509c2n:san-any 1430 1431 1432 1433 1434 1435 1437 1438 1439 1440 config-manager 1441 1442 1443 east-data-center 1444 1445 1446 east.example.com 1447 1448 15 1449 3 1450 30 1451 1452 1453 1454 1455 1456 1457 rsa-asymmetric-key 1459 ex-rsa-cert 1460 1461 1462 1463 1464 1465 trusted-client-ca-certs 1467 1468 1469 trusted-client-ee-certs 1471 1472 1473 1474 1475 30 1476 3 1477 1478 1479 1480 1481 foo.example.com 1482 1483 1484 1485 1486 1 1487 11:0A:05:11:00 1488 x509c2n:specified 1489 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 1537 1538 1539 foo.example.com 1540 1541 1542 1543 1544 1 1545 11:0A:05:11:00 1546 x509c2n:specified 1547 scooby-doo 1548 1549 1550 2 1551 x509c2n:san-any 1552 1553 1554 1555 1556 1557 1558 1559 1560 300 1561 60 1562 1563 1564 1565 last-connected 1566 3 1567 1568 1569 1570 1572 3.3. YANG Module 1574 This YANG module has normative references to [RFC6991], [RFC7407], 1575 [RFC8040], [RFC8071], [I-D.ietf-netconf-tcp-client-server], 1576 [I-D.ietf-netconf-tls-client-server], and 1577 [I-D.ietf-netconf-http-client-server]. 1579 file "ietf-restconf-server@2020-08-20.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: 1632 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) 2020 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 Simplified 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 2020-08-20 { 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 } 1682 feature https-listen { 1683 description 1684 "The 'https-listen' feature indicates that the RESTCONF server 1685 supports opening a port to listen for incoming RESTCONF over 1686 TLS client connections, whereby the TLS connections are 1687 terminated by the server itself."; 1688 reference 1689 "RFC 8040: RESTCONF Protocol"; 1690 } 1692 feature https-call-home { 1693 description 1694 "The 'https-call-home' feature indicates that the RESTCONF 1695 server supports initiating connections to RESTCONF clients."; 1696 reference 1697 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1698 } 1700 // Groupings 1702 grouping restconf-server-grouping { 1703 description 1704 "A reusable grouping for configuring a RESTCONF server 1705 without any consideration for how underlying transport 1706 sessions are established. 1708 Note that this grouping uses a fairly typical descendent 1709 node name such that a stack of 'uses' statements will 1710 have name conflicts. It is intended that the consuming 1711 data model will resolve the issue by wrapping the 'uses' 1712 statement in a container called, e.g., 1713 'restconf-server-parameters'. This model purposely does 1714 not do this itself so as to provide maximum flexibility 1715 to consuming models."; 1717 container client-identity-mappings { 1718 description 1719 "Specifies mappings through which RESTCONF client X.509 1720 certificates are used to determine a RESTCONF username. 1721 If no matching and valid cert-to-name list entry can be 1722 found, then the RESTCONF server MUST close the connection, 1723 and MUST NOT accept RESTCONF messages over it."; 1724 reference 1725 "RFC 7407: A YANG Data Model for SNMP Configuration."; 1726 uses x509c2n:cert-to-name { 1727 refine "cert-to-name/fingerprint" { 1728 mandatory false; 1729 description 1730 "A 'fingerprint' value does not need to be specified 1731 when the 'cert-to-name' mapping is independent of 1732 fingerprint matching. A 'cert-to-name' having no 1733 fingerprint value will match any client certificate 1734 and therefore should only be present at the end of 1735 the user-ordered 'cert-to-name' list."; 1736 } 1737 } 1738 } 1739 } 1741 grouping restconf-server-listen-stack-grouping { 1742 description 1743 "A reusable grouping for configuring a RESTCONF server 1744 'listen' protocol stack for a single connection."; 1745 choice transport { 1746 mandatory true; 1747 description 1748 "Selects between available transports. This is a 1749 'choice' statement so as to support additional 1750 transport options to be augmented in."; 1751 case http { 1752 if-feature "http-listen"; 1753 container http { 1754 description 1755 "Configures RESTCONF server stack assuming that 1756 TLS-termination is handled externally."; 1757 container external-endpoint { 1758 presence 1759 "Specifies configuration for an external endpoint."; 1760 description 1761 "Identifies contact information for the external 1762 system that terminates connections before passing 1763 them thru to this server (e.g., a network address 1764 translator or a load balancer). These values have 1765 no effect on the local operation of this server, but 1766 may be used by the application when needing to 1767 inform other systems how to contact this server."; 1768 leaf address { 1769 type inet:ip-address; 1770 mandatory true; 1771 description 1772 "The IP address or hostname of the external system 1773 that terminates incoming RESTCONF client 1774 connections before forwarding them to this 1775 server."; 1776 } 1777 leaf port { 1778 type inet:port-number; 1779 default "443"; 1780 description 1781 "The port number that the external system listens 1782 on for incoming RESTCONF client connections that 1783 are forwarded to this server. The default HTTPS 1784 port (443) is used, as expected for a RESTCONF 1785 connection."; 1786 } 1787 } 1788 container tcp-server-parameters { 1789 description 1790 "A wrapper around the TCP server parameters 1791 to avoid name collisions."; 1792 uses tcps:tcp-server-grouping { 1793 refine "local-port" { 1794 default "80"; 1795 description 1796 "The RESTCONF server will listen on the IANA- 1797 assigned well-known port value for 'http' 1798 (80) if no value is specified."; 1799 } 1800 } 1801 } 1802 container http-server-parameters { 1803 description 1804 "A wrapper around the HTTP server parameters 1805 to avoid name collisions."; 1806 uses https:http-server-grouping; 1807 } 1808 container restconf-server-parameters { 1809 description 1810 "A wrapper around the RESTCONF server parameters 1811 to avoid name collisions."; 1812 uses rcs:restconf-server-grouping; 1813 } 1814 } 1815 } 1816 case https { 1817 if-feature "https-listen"; 1818 container https { 1819 description 1820 "Configures RESTCONF server stack assuming that 1821 TLS-termination is handled internally."; 1822 container tcp-server-parameters { 1823 description 1824 "A wrapper around the TCP server parameters 1825 to avoid name collisions."; 1826 uses tcps:tcp-server-grouping { 1827 refine "local-port" { 1828 default "443"; 1829 description 1830 "The RESTCONF server will listen on the IANA- 1831 assigned well-known port value for 'https' 1832 (443) if no value is specified."; 1833 } 1834 } 1835 } 1836 container tls-server-parameters { 1837 description 1838 "A wrapper around the TLS server parameters 1839 to avoid name collisions."; 1840 uses tlss:tls-server-grouping; 1841 } 1842 container http-server-parameters { 1843 description 1844 "A wrapper around the HTTP server parameters 1845 to avoid name collisions."; 1846 uses https:http-server-grouping; 1847 } 1848 container restconf-server-parameters { 1849 description 1850 "A wrapper around the RESTCONF server parameters 1851 to avoid name collisions."; 1852 uses rcs:restconf-server-grouping; 1853 } 1854 } 1855 } 1856 } 1857 } 1859 grouping restconf-server-callhome-stack-grouping { 1860 description 1861 "A reusable grouping for configuring a RESTCONF server 1862 'call-home' protocol stack, for a single connection."; 1863 choice transport { 1864 mandatory true; 1865 description 1866 "Selects between available transports. This is a 1867 'choice' statement so as to support additional 1868 transport options to be augmented in."; 1869 case https { 1870 if-feature "https-listen"; 1871 container https { 1872 description 1873 "Configures RESTCONF server stack assuming that 1874 TLS-termination is handled internally."; 1875 container tcp-client-parameters { 1876 description 1877 "A wrapper around the TCP client parameters 1878 to avoid name collisions."; 1879 uses tcpc:tcp-client-grouping { 1880 refine "remote-port" { 1881 default "4336"; 1882 description 1883 "The RESTCONF server will attempt to 1884 connect to the IANA-assigned well-known 1885 port for 'restconf-ch-tls' (4336) if no 1886 value is specified."; 1887 } 1888 } 1889 } 1890 container tls-server-parameters { 1891 description 1892 "A wrapper around the TLS server parameters 1893 to avoid name collisions."; 1894 uses tlss:tls-server-grouping; 1895 } 1896 container http-server-parameters { 1897 description 1898 "A wrapper around the HTTP server parameters 1899 to avoid name collisions."; 1900 uses https:http-server-grouping; 1901 } 1902 container restconf-server-parameters { 1903 description 1904 "A wrapper around the RESTCONF server parameters 1905 to avoid name collisions."; 1906 uses rcs:restconf-server-grouping; 1907 } 1908 } 1909 } 1910 } 1911 } 1913 grouping restconf-server-app-grouping { 1914 description 1915 "A reusable grouping for configuring a RESTCONF server 1916 application that supports both 'listen' and 'call-home' 1917 protocol stacks for a multiplicity of connections."; 1918 container listen { 1919 if-feature "http-listen or https-listen"; 1920 presence 1921 "Enables the RESTCONF server to listen for RESTCONF 1922 client connections."; 1923 description "Configures listen behavior"; 1924 list endpoint { 1925 key "name"; 1926 min-elements 1; 1927 description 1928 "List of endpoints to listen for RESTCONF connections."; 1929 leaf name { 1930 type string; 1931 description 1932 "An arbitrary name for the RESTCONF listen endpoint."; 1933 } 1934 uses restconf-server-listen-stack-grouping; 1935 } 1936 } 1937 container call-home { 1938 if-feature "https-call-home"; 1939 presence 1940 "Enables the RESTCONF server to initiate the underlying 1941 transport connection to RESTCONF clients."; 1942 description "Configures call-home behavior"; 1943 list restconf-client { 1944 key "name"; 1945 min-elements 1; 1946 description 1947 "List of RESTCONF clients the RESTCONF server is to 1948 maintain simultaneous call-home connections with."; 1949 leaf name { 1950 type string; 1951 description 1952 "An arbitrary name for the remote RESTCONF client."; 1953 } 1954 container endpoints { 1955 description 1956 "Container for the list of endpoints."; 1957 list endpoint { 1958 key "name"; 1959 min-elements 1; 1960 ordered-by user; 1961 description 1962 "User-ordered list of endpoints for this RESTCONF 1963 client. Defining more than one enables high- 1964 availability."; 1965 leaf name { 1966 type string; 1967 description 1968 "An arbitrary name for this endpoint."; 1969 } 1970 uses restconf-server-callhome-stack-grouping; 1971 } 1972 } 1973 container connection-type { 1974 description 1975 "Indicates the RESTCONF server's preference for how the 1976 RESTCONF connection is maintained."; 1977 choice connection-type { 1978 mandatory true; 1979 description 1980 "Selects between available connection types."; 1981 case persistent-connection { 1982 container persistent { 1983 presence "Indicates that a persistent connection is 1984 to be maintained."; 1985 description 1986 "Maintain a persistent connection to the RESTCONF 1987 client. If the connection goes down, immediately 1988 start trying to reconnect to the RESTCONF server, 1989 using the reconnection strategy. 1991 This connection type minimizes any RESTCONF 1992 client to RESTCONF server data-transfer delay, 1993 albeit at the expense of holding resources 1994 longer."; 1995 } 1996 } 1997 case periodic-connection { 1998 container periodic { 1999 presence "Indicates that a periodic connection is 2000 to be maintained."; 2001 description 2002 "Periodically connect to the RESTCONF client. 2004 This connection type increases resource 2005 utilization, albeit with increased delay in 2006 RESTCONF client to RESTCONF client interactions. 2008 The RESTCONF client SHOULD gracefully close 2009 the underlying TLS connection upon completing 2010 planned activities. If the underlying TLS 2011 connection is not closed gracefully, the 2012 RESTCONF server MUST immediately attempt 2013 to reestablish the connection. 2015 In the case that the previous connection is 2016 still active (i.e., the RESTCONF client has not 2017 closed it yet), establishing a new connection 2018 is NOT RECOMMENDED."; 2020 leaf period { 2021 type uint16; 2022 units "minutes"; 2023 default "60"; 2024 description 2025 "Duration of time between periodic connections."; 2026 } 2027 leaf anchor-time { 2028 type yang:date-and-time { 2029 // constrained to minute-level granularity 2030 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2031 + '(Z|[\+\-]\d{2}:\d{2})'; 2032 } 2033 description 2034 "Designates a timestamp before or after which a 2035 series of periodic connections are determined. 2036 The periodic connections occur at a whole 2037 multiple interval from the anchor time. For 2038 example, for an anchor time is 15 minutes past 2039 midnight and a period interval of 24 hours, then 2040 a periodic connection will occur 15 minutes past 2041 midnight everyday."; 2042 } 2043 leaf idle-timeout { 2044 type uint16; 2045 units "seconds"; 2046 default 120; // two minutes 2047 description 2048 "Specifies the maximum number of seconds that 2049 the underlying TCP session may remain idle. 2050 A TCP session will be dropped if it is idle 2051 for an interval longer than this number of 2052 seconds. If set to zero, then the server 2053 will never drop a session because it is idle."; 2054 } 2055 } 2056 } 2057 } 2059 } 2060 container reconnect-strategy { 2061 description 2062 "The reconnection strategy directs how a RESTCONF server 2063 reconnects to a RESTCONF client after discovering its 2064 connection to the client has dropped, even if due to a 2065 reboot. The RESTCONF server starts with the specified 2066 endpoint and tries to connect to it max-attempts times 2067 before trying the next endpoint in the list (round 2068 robin)."; 2069 leaf start-with { 2070 type enumeration { 2071 enum first-listed { 2072 description 2073 "Indicates that reconnections should start with 2074 the first endpoint listed."; 2075 } 2076 enum last-connected { 2077 description 2078 "Indicates that reconnections should start with 2079 the endpoint last connected to. If no previous 2080 connection has ever been established, then the 2081 first endpoint configured is used. RESTCONF 2082 servers SHOULD be able to remember the last 2083 endpoint connected to across reboots."; 2084 } 2085 enum random-selection { 2086 description 2087 "Indicates that reconnections should start with 2088 a random endpoint."; 2089 } 2090 } 2091 default "first-listed"; 2092 description 2093 "Specifies which of the RESTCONF client's endpoints 2094 the RESTCONF server should start with when trying 2095 to connect to the RESTCONF client."; 2096 } 2097 leaf max-attempts { 2098 type uint8 { 2099 range "1..max"; 2100 } 2101 default "3"; 2102 description 2103 "Specifies the number times the RESTCONF server tries 2104 to connect to a specific endpoint before moving on to 2105 the next endpoint in the list (round robin)."; 2106 } 2108 } 2109 } // restconf-client 2110 } // call-home 2111 } // restconf-server-app-grouping 2113 // Protocol accessible node, for servers that implement 2114 // this module. 2115 container restconf-server { 2116 uses restconf-server-app-grouping; 2117 description 2118 "Top-level container for RESTCONF server configuration."; 2119 } 2121 } 2123 2125 4. Security Considerations 2127 4.1. The "ietf-restconf-client" YANG Module 2129 The "ietf-restconf-client" YANG module defines data nodes that are 2130 designed to be accessed via YANG based management protocols, such as 2131 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2132 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2133 with mutual authentication. 2135 The NETCONF access control model (NACM) [RFC8341] provides the means 2136 to restrict access for particular users to a pre-configured subset of 2137 all available protocol operations and content. 2139 None of the readable data nodes in this YANG module are considered 2140 sensitive or vulnerable in network environments. The NACM "default- 2141 deny-all" extension has not been set for any data nodes defined in 2142 this module. 2144 None of the writable data nodes in this YANG module are considered 2145 sensitive or vulnerable in network environments. The NACM "default- 2146 deny-write" extension has not been set for any data nodes defined in 2147 this module. 2149 This module does not define any RPCs, actions, or notifications, and 2150 thus the security consideration for such is not provided here. 2152 Please be aware that this module uses groupings defined in other RFCs 2153 that define data nodes that do set the NACM "default-deny-all" and 2154 "default-deny-write" extensions. 2156 4.2. The "ietf-restconf-server" YANG Module 2158 The "ietf-restconf-server" YANG module defines data nodes that are 2159 designed to be accessed via YANG based management protocols, such as 2160 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2161 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2162 with mutual authentication. 2164 The NETCONF access control model (NACM) [RFC8341] provides the means 2165 to restrict access for particular users to a pre-configured subset of 2166 all available protocol operations and content. 2168 None of the readable data nodes in this YANG module are considered 2169 sensitive or vulnerable in network environments. The NACM "default- 2170 deny-all" extension has not been set for any data nodes defined in 2171 this module. 2173 None of the writable data nodes in this YANG module are considered 2174 sensitive or vulnerable in network environments. The NACM "default- 2175 deny-write" extension has not been set for any data nodes defined in 2176 this module. 2178 This module does not define any RPCs, actions, or notifications, and 2179 thus the security consideration for such is not provided here. 2181 Please be aware that this module uses groupings defined in other RFCs 2182 that define data nodes that do set the NACM "default-deny-all" and 2183 "default-deny-write" extensions. 2185 5. IANA Considerations 2187 5.1. The "IETF XML" Registry 2189 This document registers two URIs in the "ns" subregistry of the IETF 2190 XML Registry [RFC3688]. Following the format in [RFC3688], the 2191 following registrations are requested: 2193 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2194 Registrant Contact: The NETCONF WG of the IETF. 2195 XML: N/A, the requested URI is an XML namespace. 2197 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2198 Registrant Contact: The NETCONF WG of the IETF. 2199 XML: N/A, the requested URI is an XML namespace. 2201 5.2. The "YANG Module Names" Registry 2203 This document registers two YANG modules in the YANG Module Names 2204 registry [RFC6020]. Following the format in [RFC6020], the following 2205 registrations are requested: 2207 name: ietf-restconf-client 2208 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2209 prefix: ncc 2210 reference: RFC IIII 2212 name: ietf-restconf-server 2213 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2214 prefix: ncs 2215 reference: RFC IIII 2217 6. References 2219 6.1. Normative References 2221 [I-D.ietf-netconf-http-client-server] 2222 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2223 Servers", Work in Progress, Internet-Draft, draft-ietf- 2224 netconf-http-client-server-04, 8 July 2020, 2225 . 2228 [I-D.ietf-netconf-keystore] 2229 Watsen, K., "A YANG Data Model for a Keystore", Work in 2230 Progress, Internet-Draft, draft-ietf-netconf-keystore-19, 2231 10 July 2020, . 2234 [I-D.ietf-netconf-tcp-client-server] 2235 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2236 and TCP Servers", Work in Progress, Internet-Draft, draft- 2237 ietf-netconf-tcp-client-server-07, 8 July 2020, 2238 . 2241 [I-D.ietf-netconf-tls-client-server] 2242 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2243 TLS Servers", Work in Progress, Internet-Draft, draft- 2244 ietf-netconf-tls-client-server-21, 10 July 2020, 2245 . 2248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2249 Requirement Levels", BCP 14, RFC 2119, 2250 DOI 10.17487/RFC2119, March 1997, 2251 . 2253 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2254 the Network Configuration Protocol (NETCONF)", RFC 6020, 2255 DOI 10.17487/RFC6020, October 2010, 2256 . 2258 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2259 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2260 . 2262 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2263 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2264 December 2014, . 2266 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2267 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2268 . 2270 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2271 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2272 . 2274 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2275 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2276 . 2278 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2279 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2280 May 2017, . 2282 6.2. Informative References 2284 [I-D.ietf-netconf-crypto-types] 2285 Watsen, K., "YANG Data Types and Groupings for 2286 Cryptography", Work in Progress, Internet-Draft, draft- 2287 ietf-netconf-crypto-types-17, 10 July 2020, 2288 . 2291 [I-D.ietf-netconf-netconf-client-server] 2292 Watsen, K., "NETCONF Client and Server Models", Work in 2293 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2294 client-server-20, 8 July 2020, 2295 . 2298 [I-D.ietf-netconf-restconf-client-server] 2299 Watsen, K., "RESTCONF Client and Server Models", Work in 2300 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2301 client-server-20, 8 July 2020, 2302 . 2305 [I-D.ietf-netconf-ssh-client-server] 2306 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2307 SSH Servers", Work in Progress, Internet-Draft, draft- 2308 ietf-netconf-ssh-client-server-21, 10 July 2020, 2309 . 2312 [I-D.ietf-netconf-trust-anchors] 2313 Watsen, K., "A YANG Data Model for a Truststore", Work in 2314 Progress, Internet-Draft, draft-ietf-netconf-trust- 2315 anchors-12, 10 July 2020, . 2318 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2319 DOI 10.17487/RFC3688, January 2004, 2320 . 2322 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2323 and A. Bierman, Ed., "Network Configuration Protocol 2324 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2325 . 2327 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2328 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2329 . 2331 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2332 Access Control Model", STD 91, RFC 8341, 2333 DOI 10.17487/RFC8341, March 2018, 2334 . 2336 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2337 and R. Wilton, "Network Management Datastore Architecture 2338 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2339 . 2341 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2342 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2343 . 2345 Appendix A. Expanded Tree Diagrams 2347 A.1. Expanded Tree Diagram for 'ietf-restconf-client' 2349 The following tree diagram [RFC8340] provides an overview of the data 2350 model for the "ietf-restconf-client" module. 2352 This tree diagram shows all the nodes defined in this module, 2353 including those defined by "grouping" statements used by this module. 2355 Please see Section 2.1 for a tree diagram that illustrates what the 2356 module looks like without all the "grouping" statements expanded. 2358 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-client-tree.txt) 2360 A.2. Expanded Tree Diagram for 'ietf-restconf-server' 2362 The following tree diagram [RFC8340] provides an overview of the data 2363 model for the "ietf-restconf-server" module. 2365 This tree diagram shows all the nodes defined in this module, 2366 including those defined by "grouping" statements used by this module. 2368 Please see Section 3.1 for a tree diagram that illustrates what the 2369 module looks like without all the "grouping" statements expanded. 2371 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-server-tree.txt) 2373 Appendix B. Change Log 2375 This section is to be removed before publishing as an RFC. 2377 B.1. 00 to 01 2379 * Renamed "keychain" to "keystore". 2381 B.2. 01 to 02 2383 * Filled in previously missing 'ietf-restconf-client' module. 2385 * Updated the ietf-restconf-server module to accommodate new 2386 grouping 'ietf-tls-server-grouping'. 2388 B.3. 02 to 03 2390 * Refined use of tls-client-grouping to add a must statement 2391 indicating that the TLS client must specify a client-certificate. 2393 * Changed restconf-client??? to be a grouping (not a container). 2395 B.4. 03 to 04 2397 * Added RFC 8174 to Requirements Language Section. 2399 * Replaced refine statement in ietf-restconf-client to add a 2400 mandatory true. 2402 * Added refine statement in ietf-restconf-server to add a must 2403 statement. 2405 * Now there are containers and groupings, for both the client and 2406 server models. 2408 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2410 * Updated examples to inline key and certificates (no longer a 2411 leafref to keystore) 2413 B.5. 04 to 05 2415 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2417 * Updated examples to inline key and certificates (no longer a 2418 leafref to keystore) 2420 B.6. 05 to 06 2422 * Fixed change log missing section issue. 2424 * Updated examples to match latest updates to the crypto-types, 2425 trust-anchors, and keystore drafts. 2427 * Reduced line length of the YANG modules to fit within 69 columns. 2429 B.7. 06 to 07 2431 * removed "idle-timeout" from "persistent" connection config. 2433 * Added "random-selection" for reconnection-strategy's "starts-with" 2434 enum. 2436 * Replaced "connection-type" choice default (persistent) with 2437 "mandatory true". 2439 * Reduced the periodic-connection's "idle-timeout" from 5 to 2 2440 minutes. 2442 * Replaced reconnect-timeout with period/anchor-time combo. 2444 B.8. 07 to 08 2446 * Modified examples to be compatible with new crypto-types algs 2448 B.9. 08 to 09 2450 * Corrected use of "mandatory true" for "address" leafs. 2452 * Updated examples to reflect update to groupings defined in the 2453 keystore draft. 2455 * Updated to use groupings defined in new TCP and HTTP drafts. 2457 * Updated copyright date, boilerplate template, affiliation, and 2458 folding algorithm. 2460 B.10. 09 to 10 2462 * Reformatted YANG modules. 2464 B.11. 10 to 11 2466 * Adjusted for the top-level "demux container" added to groupings 2467 imported from other modules. 2469 * Added "must" expressions to ensure that keepalives are not 2470 configured for "periodic" connections. 2472 * Updated the boilerplate text in module-level "description" 2473 statement to match copyeditor convention. 2475 * Moved "expanded" tree diagrams to the Appendix. 2477 B.12. 11 to 12 2479 * Removed the 'must' statement limiting keepalives in periodic 2480 connections. 2482 * Updated models and examples to reflect removal of the "demux" 2483 containers in the imported models. 2485 * Updated the "periodic-connnection" description statements to 2486 better describe behavior when connections are not closed 2487 gracefully. 2489 * Updated text to better reference where certain examples come from 2490 (e.g., which Section in which draft). 2492 * In the server model, commented out the "must 'pinned-ca-certs or 2493 pinned-client-certs'" statement to reflect change made in the TLS 2494 draft whereby the trust anchors MAY be defined externally. 2496 * Replaced the 'listen', 'initiate', and 'call-home' features with 2497 boolean expressions. 2499 B.13. 12 to 13 2501 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2502 anchors/truststore/g + s/pinned.//) 2504 * In ietf-restconf-server, Added 'http-listen' (not https-listen) 2505 choice, to support case when server is behind a TLS-terminator. 2507 * Refactored server module to be more like other 'server' models. 2508 If folks like it, will also apply to the client model, as well as 2509 to both the netconf client/server models. Now the 'restconf- 2510 server-grouping' is just the RC-specific bits (i.e., the "demux" 2511 container minus the container), 'restconf-server- 2512 [listen|callhome]-stack-grouping' is the protocol stack for a 2513 single connection, and 'restconf-server-app-grouping' is 2514 effectively what was before (both listen+callhome for many 2515 inbound/outbound endpoints). 2517 B.14. 13 to 14 2519 * Updated examples to reflect ietf-crypto-types change (e.g., 2520 identities --> enumerations) 2522 * Adjusting from change in TLS client model (removing the top-level 2523 'certificate' container). 2525 * Added "external-endpoint" to the "http-listen" choice in ietf- 2526 restconf-server. 2528 B.15. 14 to 15 2530 * Added missing "or https-listen" clause in a "must" expression. 2532 * Refactored the client module similar to how the server module was 2533 refactored in -13. Now the 'restconf-client-grouping' is just the 2534 RC-specific bits, the 'restconf-client-[initiate|listen]-stack- 2535 grouping' is the protocol stack for a single connection, and 2536 'restconf-client-app-grouping' is effectively what was before 2537 (both listen+callhome for many inbound/outbound endpoints). 2539 B.16. 15 to 16 2541 * Added refinement to make "cert-to-name/fingerprint" be mandatory 2542 false. 2544 * Commented out refinement to "tls-server-grouping/client- 2545 authentication" until a better "must" expression is defined. 2547 * Updated restconf-client example to reflect that http-client- 2548 grouping no longer has a "protocol-version" leaf. 2550 B.17. 16 to 17 2552 * Updated examples to include the "*-key-format" nodes. 2554 * Updated examples to remove the "required" nodes. 2556 B.18. 17 to 18 2558 * Updated examples to reflect new "bag" addition to truststore. 2560 B.19. 18 to 19 2562 * Updated examples to remove the 'algorithm' nodes. 2564 * Updated examples to reflect the new TLS keepalives structure. 2566 * Removed the 'protocol-versions' node from the restconf-server 2567 examples. 2569 * Added a "Note to Reviewers" note to first page. 2571 B.20. 19 to 20 2572 * Moved and changed "must" statement so that either TLS *or* HTTP 2573 auth must be configured. 2575 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2576 diagrams]. 2578 * Updated the Security Considerations section. 2580 B.21. 20 to 21 2582 * Cleaned up titles in the IANA Consideratons section 2584 * Fixed issues found by the SecDir review of the "keystore" draft. 2586 Acknowledgements 2588 The authors would like to thank for following for lively discussions 2589 on list and in the halls (ordered by last name): Andy Bierman, Martin 2590 Bjorklund, Benoit Claise, Mehmet Ersue, Ramkumar Dhanapal, Balazs 2591 Kovacs, Radek Krejci, David Lamparter, Ladislav Lhotka, Alan Luchuk, 2592 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, Bert 2593 Wijnen. 2595 Author's Address 2597 Kent Watsen 2598 Watsen Networks 2600 Email: kent+ietf@watsen.net