idnits 2.17.1 draft-ietf-netconf-restconf-client-server-20.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 1188 has weird spacing: '...address ine...' -- The document date (8 July 2020) is 1381 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-03 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-15 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 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 8 July 2020 5 Expires: 9 January 2021 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-20 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-07-08" --> 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 9 January 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 . . . . . . . . . 45 110 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 111 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 46 112 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 46 113 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 114 6.1. Normative References . . . . . . . . . . . . . . . . . . 47 115 6.2. Informative References . . . . . . . . . . . . . . . . . 48 116 Appendix A. Expanded Tree Diagrams . . . . . . . . . . . . . . . 49 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 . . . . . . . . . . . . . . . . . . . . . . . . 50 122 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 50 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 . . . . . . . . . . . . . . . . . . . . . . . . 51 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 . . . . . . . . . . . . . . . . . . . . . . . . 52 132 B.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 53 133 B.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 53 134 B.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 53 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 55 141 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 55 143 1. Introduction 145 This document defines two YANG [RFC7950] modules, one module to 146 configure a RESTCONF client and the other module to configure a 147 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446] 148 transport protocol with both standard RESTCONF and RESTCONF Call Home 149 connections [RFC8071]. 151 1.1. Relation to other RFCs 153 This document presents one or more YANG modules [RFC7950] that are 154 part of a collection of RFCs that work together to define 155 configuration modules for clients and servers of both the NETCONF 156 [RFC6241] and RESTCONF [RFC8040] protocols. 158 The modules have been defined in a modular fashion to enable their 159 use by other efforts, some of which are known to be in progress at 160 the time of this writing, with many more expected to be defined in 161 time. 163 The relationship between the various RFCs in the collection is 164 presented in the below diagram. The labels in the diagram represent 165 the primary purpose provided by each RFC. Links the each RFC are 166 provided below the diagram. 168 crypto-types 169 ^ ^ 170 / \ 171 / \ 172 truststore keystore 173 ^ ^ ^ ^ 174 | +---------+ | | 175 | | | | 176 | +------------+ | 177 tcp-client-server | / | | 178 ^ ^ ssh-client-server | | 179 | | ^ tls-client-server 180 | | | ^ ^ http-client-server 181 | | | | | ^ 182 | | | +-----+ +---------+ | 183 | | | | | | 184 | +-----------|--------|--------------+ | | 185 | | | | | | 186 +-----------+ | | | | | 187 | | | | | | 188 | | | | | | 189 netconf-client-server restconf-client-server 191 +=======================+===========================================+ 192 | Label in Diagram | Originating RFC | 193 +=======================+===========================================+ 194 | crypto-types | [I-D.ietf-netconf-crypto-types] | 195 +-----------------------+-------------------------------------------+ 196 | truststore | [I-D.ietf-netconf-trust-anchors] | 197 +-----------------------+-------------------------------------------+ 198 | keystore | [I-D.ietf-netconf-keystore] | 199 +-----------------------+-------------------------------------------+ 200 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 201 +-----------------------+-------------------------------------------+ 202 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 203 +-----------------------+-------------------------------------------+ 204 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 205 +-----------------------+-------------------------------------------+ 206 | http-client-server | [I-D.ietf-netconf-http-client-server] | 207 +-----------------------+-------------------------------------------+ 208 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 211 +-----------------------+-------------------------------------------+ 213 Table 1: Label to RFC Mapping 215 1.2. Specification Language 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in BCP 220 14 [RFC2119] [RFC8174] when, and only when, they appear in all 221 capitals, as shown here. 223 1.3. Adherence to the NMDA 225 This document in compliant with the Network Management Datastore 226 Architecture (NMDA) [RFC8342]. For instance, as described in 227 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 228 trust anchors and keys installed during manufacturing are expected to 229 appear in . 231 2. The "ietf-restconf-client" Module 233 The RESTCONF client model presented in this section supports both 234 clients initiating connections to servers, as well as clients 235 listening for connections from servers calling home. 237 YANG feature statements are used to enable implementations to 238 advertise which potentially uncommon parts of the model the RESTCONF 239 client supports. 241 2.1. Data Model Overview 243 2.1.1. Features 245 The following diagram lists all the "feature" statements defined in 246 the "ietf-restconf-client" module: 248 Features: 249 +-- https-initiate 250 +-- http-listen 251 +-- https-listen 253 2.1.2. Groupings 255 The following diagram lists all the "grouping" statements defined in 256 the "ietf-restconf-client" module: 258 Groupings: 259 +-- restconf-client-grouping 260 +-- restconf-client-initiate-stack-grouping 261 +-- restconf-client-listen-stack-grouping 262 +-- restconf-client-app-grouping 264 Each of these groupings are presented in the following subsections. 266 2.1.2.1. The "restconf-client-grouping" Grouping 268 The following tree diagram [RFC8340] illustrates the "restconf- 269 client-grouping" grouping: 271 grouping restconf-client-grouping ---> 273 Comments: 275 * This grouping does not define any nodes, but is maintained so that 276 downstream modules can augment nodes into it if needed. 278 * The "restconf-client-grouping" defines, if it can be called that, 279 the configuration for just "RESTCONF" part of a protocol stack. 280 It does not, for instance, define any configuration for the "TCP", 281 "TLS", or "HTTP" protocol layers (for that, see Section 2.1.2.2 282 and Section 2.1.2.3). 284 2.1.2.2. The "restconf-client-initiate-stack-grouping" Grouping 286 The following tree diagram [RFC8340] illustrates the "restconf- 287 client-initiate-stack-grouping" grouping: 289 grouping restconf-client-initiate-stack-grouping 290 +-- (transport) 291 +--:(https) {https-initiate}? 292 +-- https 293 +-- tcp-client-parameters 294 | +---u tcpc:tcp-client-grouping 295 +-- tls-client-parameters 296 | +---u tlsc:tls-client-grouping 297 +-- http-client-parameters 298 | +---u httpc:http-client-grouping 299 +-- restconf-client-parameters 300 +---u rcc:restconf-client-grouping 302 Comments: 304 * The "restconf-client-initiate-stack-grouping" defines the 305 configuration for a full RESTCONF protocol stack, for RESTCONF 306 clients that initiate connections to RESTCONF servers, as opposed 307 to receiving call-home [RFC8071] connections. 309 * The "transport" choice node enables transport options to be 310 configured. This document only defines an "https" option, but 311 other options MAY be augmented in. 313 * For the referenced grouping statement(s): 315 - The "tcp-client-grouping" grouping is discussed in 316 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 317 - The "tls-client-grouping" grouping is discussed in 318 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 319 - The "http-client-grouping" grouping is discussed in 320 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 321 - The "restconf-client-grouping" grouping is discussed in 322 Section 2.1.2.1 in this document. 324 2.1.2.3. The "restconf-client-listen-stack-grouping" Grouping 326 The following tree diagram [RFC8340] illustrates the "restconf- 327 client-listen-stack-grouping" grouping: 329 grouping restconf-client-listen-stack-grouping 330 +-- (transport) 331 +--:(http) {http-listen}? 332 | +-- http 333 | +-- tcp-server-parameters 334 | | +---u tcps:tcp-server-grouping 335 | +-- http-client-parameters 336 | | +---u httpc:http-client-grouping 337 | +-- restconf-client-parameters 338 | +---u rcc:restconf-client-grouping 339 +--:(https) {https-listen}? 340 +-- https 341 +-- tcp-server-parameters 342 | +---u tcps:tcp-server-grouping 343 +-- tls-client-parameters 344 | +---u tlsc:tls-client-grouping 345 +-- http-client-parameters 346 | +---u httpc:http-client-grouping 347 +-- restconf-client-parameters 348 +---u rcc:restconf-client-grouping 350 Comments: 352 * The "restconf-client-listen-stack-grouping" defines the 353 configuration for a full RESTCONF protocol stack, for RESTCONF 354 clients that receive call-home [RFC8071] connections from RESTCONF 355 servers. 357 * The "transport" choice node enables both the HTTP and HTTPS 358 transports to be configured, with each option enabled by a 359 "feature" statement. Note that RESTCONF requires HTTPS, the HTTP 360 option is provided to support cases where a TLS-terminator is 361 deployed in front of the RESTCONF-client. 363 * For the referenced grouping statement(s): 365 - The "tcp-server-grouping" grouping is discussed in 366 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 367 - The "tls-client-grouping" grouping is discussed in 368 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 369 - The "http-client-grouping" grouping is discussed in 370 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 371 - The "restconf-client-grouping" grouping is discussed in 372 Section 2.1.2.1 in this document. 374 2.1.2.4. The "restconf-client-app-grouping" Grouping 376 The following tree diagram [RFC8340] illustrates the "restconf- 377 client-app-grouping" grouping: 379 grouping restconf-client-app-grouping 380 +-- initiate! {https-initiate}? 381 | +-- restconf-server* [name] 382 | +-- name? string 383 | +-- endpoints 384 | | +-- endpoint* [name] 385 | | +-- name? string 386 | | +---u restconf-client-initiate-stack-grouping 387 | +-- connection-type 388 | | +-- (connection-type) 389 | | +--:(persistent-connection) 390 | | | +-- persistent! 391 | | +--:(periodic-connection) 392 | | +-- periodic! 393 | | +-- period? uint16 394 | | +-- anchor-time? yang:date-and-time 395 | | +-- idle-timeout? uint16 396 | +-- reconnect-strategy 397 | +-- start-with? enumeration 398 | +-- max-attempts? uint8 399 +-- listen! {http-listen or https-listen}? 400 +-- idle-timeout? uint16 401 +-- endpoint* [name] 402 +-- name? string 403 +---u restconf-client-listen-stack-grouping 405 Comments: 407 * The "restconf-client-app-grouping" defines the configuration for a 408 RESTCONF client that supports both initiating connections to 409 RESTCONF servers as well as receiving call-home connections from 410 RESTCONF servers. 412 * Both the "initiate" and "listen" subtrees must be enabled by 413 "feature" statements. 415 * For the referenced grouping statement(s): 417 - The "restconf-client-initiate-stack-grouping" grouping is 418 discussed in Section 2.1.2.2 in this document. 419 - The "restconf-client-listen-stack-grouping" grouping is 420 discussed in Section 2.1.2.3 in this document. 422 2.1.3. Protocol-accessible Nodes 424 The following diagram lists all the protocol-accessible nodes defined 425 in the "ietf-restconf-client" module: 427 module: ietf-restconf-client 428 +--rw restconf-client 429 +---u restconf-client-app-grouping 431 Comments: 433 * Protocol-accessible nodes are those nodes that are accessible when 434 the module is "implemented", as described in Section 5.6.5 of 435 [RFC7950]. 437 * For the "ietf-restconf-client" module, the protocol-accessible 438 nodes are an instance of the "restconf-client-app-grouping" 439 discussed in Section 2.1.2.4 grouping. 441 * The reason for why "restconf-client-app-grouping" exists separate 442 from the protocol-accessible nodes definition is so as to enable 443 instances of restconf-client-app-grouping to be instantiated in 444 other locations, as may be needed or desired by some modules. 446 2.2. Example Usage 448 The following example illustrates configuring a RESTCONF client to 449 initiate connections, as well as to listen for call-home connections. 451 This example is consistent with the examples presented in Section 2.2 452 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 453 [I-D.ietf-netconf-keystore]. 455 =============== NOTE: '\' line wrapping per RFC 8792 ================ 457 461 462 463 464 corp-fw1 465 466 467 corp-fw1.example.com 468 469 470 corp-fw1.example.com 471 472 15 473 3 474 30 475 476 477 478 479 480 481 rsa-asymmetric-key 483 ex-rsa-cert 484 485 486 487 488 489 trusted-server-ca-certs 491 492 493 trusted-server-ee-certs 495 496 497 498 499 30 500 3 501 502 503 504 505 506 507 bob 508 secret 509 510 511 512 513 514 515 corp-fw2.example.com 516 517 518 corp-fw2.example.com 519 520 15 521 3 522 30 523 524 525 526 527 528 529 rsa-asymmetric-key 531 ex-rsa-cert 532 533 534 535 536 537 trusted-server-ca-certs 539 540 541 trusted-server-ee-certs 543 544 545 546 547 30 548 3 549 550 551 552 553 554 555 bob 556 secret 557 558 559 560 561 562 563 564 565 567 568 570 571 572 573 Intranet-facing listener 574 575 576 11.22.33.44 577 578 579 580 581 582 rsa-asymmetric-key 583 ex-rsa-cert 584 585 586 587 588 589 trusted-server-ca-certs 591 592 593 trusted-server-ee-certs 595 596 597 598 599 600 601 602 603 604 bob 605 secret 606 607 608 609 610 611 612 614 2.3. YANG Module 616 This YANG module has normative references to [RFC6991], [RFC8040], 617 and [RFC8071], [I-D.ietf-netconf-tcp-client-server], 618 [I-D.ietf-netconf-tls-client-server], and 619 [I-D.ietf-netconf-http-client-server]. 621 file "ietf-restconf-client@2020-07-08.yang" 623 module ietf-restconf-client { 624 yang-version 1.1; 625 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 626 prefix rcc; 628 import ietf-yang-types { 629 prefix yang; 630 reference 631 "RFC 6991: Common YANG Data Types"; 632 } 634 import ietf-tcp-client { 635 prefix tcpc; 636 reference 637 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 638 } 640 import ietf-tcp-server { 641 prefix tcps; 642 reference 643 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 644 } 646 import ietf-tls-client { 647 prefix tlsc; 648 reference 649 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 650 } 652 import ietf-http-client { 653 prefix httpc; 654 reference 655 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 656 } 658 organization 659 "IETF NETCONF (Network Configuration) Working Group"; 661 contact 662 "WG Web: 663 WG List: 664 Author: Kent Watsen 665 Author: Gary Wu "; 667 description 668 "This module contains a collection of YANG definitions 669 for configuring RESTCONF clients. 671 Copyright (c) 2020 IETF Trust and the persons identified 672 as authors of the code. All rights reserved. 674 Redistribution and use in source and binary forms, with 675 or without modification, is permitted pursuant to, and 676 subject to the license terms contained in, the Simplified 677 BSD License set forth in Section 4.c of the IETF Trust's 678 Legal Provisions Relating to IETF Documents 679 (https://trustee.ietf.org/license-info). 681 This version of this YANG module is part of RFC IIII 682 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 683 itself for full legal notices. 685 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 686 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 687 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 688 are to be interpreted as described in BCP 14 (RFC 2119) 689 (RFC 8174) when, and only when, they appear in all 690 capitals, as shown here."; 692 revision 2020-07-08 { 693 description 694 "Initial version"; 695 reference 696 "RFC IIII: RESTCONF Client and Server Models"; 697 } 699 // Features 701 feature https-initiate { 702 description 703 "The 'https-initiate' feature indicates that the RESTCONF 704 client supports initiating HTTPS connections to RESTCONF 705 servers. This feature exists as HTTPS might not be a 706 mandatory to implement transport in the future."; 707 reference 708 "RFC 8040: RESTCONF Protocol"; 709 } 710 feature http-listen { 711 description 712 "The 'https-listen' feature indicates that the RESTCONF client 713 supports opening a port to listen for incoming RESTCONF 714 server call-home connections. This feature exists as not 715 all RESTCONF clients may support RESTCONF call home."; 716 reference 717 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 718 } 720 feature https-listen { 721 description 722 "The 'https-listen' feature indicates that the RESTCONF client 723 supports opening a port to listen for incoming RESTCONF 724 server call-home connections. This feature exists as not 725 all RESTCONF clients may support RESTCONF call home."; 726 reference 727 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 728 } 730 // Groupings 732 grouping restconf-client-grouping { 733 description 734 "A reusable grouping for configuring a RESTCONF client 735 without any consideration for how underlying transport 736 sessions are established. 738 This grouping currently doesn't define any nodes."; 739 } 741 grouping restconf-client-initiate-stack-grouping { 742 description 743 "A reusable grouping for configuring a RESTCONF client 744 'initiate' protocol stack for a single connection."; 746 choice transport { 747 mandatory true; 748 description 749 "Selects between available transports. This is a 750 'choice' statement so as to support additional 751 transport options to be augmented in."; 752 case https { 753 if-feature "https-initiate"; 754 container https { 755 must 'tls-client-parameters/client-identity 756 or http-client-parameters/client-identity'; 757 description 758 "Specifies HTTPS-specific transport 759 configuration."; 760 container tcp-client-parameters { 761 description 762 "A wrapper around the TCP client parameters 763 to avoid name collisions."; 764 uses tcpc:tcp-client-grouping { 765 refine "remote-port" { 766 default "443"; 767 description 768 "The RESTCONF client will attempt to 769 connect to the IANA-assigned well-known 770 port value for 'https' (443) if no value 771 is specified."; 772 } 773 } 774 } 775 container tls-client-parameters { 776 description 777 "A wrapper around the TLS client parameters 778 to avoid name collisions."; 779 uses tlsc:tls-client-grouping; 780 } 781 container http-client-parameters { 782 description 783 "A wrapper around the HTTP client parameters 784 to avoid name collisions."; 785 uses httpc:http-client-grouping; 786 } 787 container restconf-client-parameters { 788 description 789 "A wrapper around the HTTP client parameters 790 to avoid name collisions."; 791 uses rcc:restconf-client-grouping; 792 } 793 } 794 } 795 } 796 } // restconf-client-initiate-stack-grouping 798 grouping restconf-client-listen-stack-grouping { 799 description 800 "A reusable grouping for configuring a RESTCONF client 801 'listen' protocol stack for a single connection. The 802 'listen' stack supports call home connections, as 803 described in RFC 8071"; 804 reference 805 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 807 choice transport { 808 mandatory true; 809 description 810 "Selects between available transports. This is a 811 'choice' statement so as to support additional 812 transport options to be augmented in."; 813 case http { 814 if-feature "http-listen"; 815 container http { 816 description 817 "HTTP-specific listening configuration for inbound 818 connections. 820 This transport option is made available to support 821 deployments where the TLS connections are terminated 822 by another system (e.g., a load balanacer) fronting 823 the client."; 824 container tcp-server-parameters { 825 description 826 "A wrapper around the TCP client parameters 827 to avoid name collisions."; 828 uses tcps:tcp-server-grouping { 829 refine "local-port" { 830 default "4336"; 831 description 832 "The RESTCONF client will listen on the IANA- 833 assigned well-known port for 'restconf-ch-tls' 834 (4336) if no value is specified."; 835 } 836 } 837 } 838 container http-client-parameters { 839 description 840 "A wrapper around the HTTP client parameters 841 to avoid name collisions."; 842 uses httpc:http-client-grouping; 843 } 844 container restconf-client-parameters { 845 description 846 "A wrapper around the RESTCONF client parameters 847 to avoid name collisions."; 848 uses rcc:restconf-client-grouping; 849 } 850 } 851 } 852 case https { 853 if-feature "https-listen"; 854 container https { 855 must 'tls-client-parameters/client-identity 856 or http-client-parameters/client-identity'; 857 description 858 "HTTPS-specific listening configuration for inbound 859 connections."; 860 container tcp-server-parameters { 861 description 862 "A wrapper around the TCP client parameters 863 to avoid name collisions."; 864 uses tcps:tcp-server-grouping { 865 refine "local-port" { 866 default "4336"; 867 description 868 "The RESTCONF client will listen on the IANA- 869 assigned well-known port for 'restconf-ch-tls' 870 (4336) if no value is specified."; 871 } 872 } 873 } 874 container tls-client-parameters { 875 description 876 "A wrapper around the TLS client parameters 877 to avoid name collisions."; 878 uses tlsc:tls-client-grouping; 879 } 880 container http-client-parameters { 881 description 882 "A wrapper around the HTTP client parameters 883 to avoid name collisions."; 884 uses httpc:http-client-grouping; 885 } 886 container restconf-client-parameters { 887 description 888 "A wrapper around the RESTCONF client parameters 889 to avoid name collisions."; 890 uses rcc:restconf-client-grouping; 891 } 892 } 893 } 894 } 895 } // restconf-client-listen-stack-grouping 897 grouping restconf-client-app-grouping { 898 description 899 "A reusable grouping for configuring a RESTCONF client 900 application that supports both 'initiate' and 'listen' 901 protocol stacks for a multiplicity of connections."; 902 container initiate { 903 if-feature "https-initiate"; 904 presence "Enables client to initiate TCP connections"; 905 description 906 "Configures client initiating underlying TCP connections."; 907 list restconf-server { 908 key "name"; 909 min-elements 1; 910 description 911 "List of RESTCONF servers the RESTCONF client is to 912 maintain simultaneous connections with."; 913 leaf name { 914 type string; 915 description 916 "An arbitrary name for the RESTCONF server."; 917 } 918 container endpoints { 919 description 920 "Container for the list of endpoints."; 921 list endpoint { 922 key "name"; 923 min-elements 1; 924 ordered-by user; 925 description 926 "A non-empty user-ordered list of endpoints for this 927 RESTCONF client to try to connect to in sequence. 928 Defining more than one enables high-availability."; 929 leaf name { 930 type string; 931 description 932 "An arbitrary name for this endpoint."; 933 } 934 uses restconf-client-initiate-stack-grouping; 935 } 936 } 937 container connection-type { 938 description 939 "Indicates the RESTCONF client's preference for how 940 the RESTCONF connection is maintained."; 941 choice connection-type { 942 mandatory true; 943 description 944 "Selects between available connection types."; 945 case persistent-connection { 946 container persistent { 947 presence "Indicates that a persistent connection 948 is to be maintained."; 949 description 950 "Maintain a persistent connection to the 951 RESTCONF server. If the connection goes down, 952 immediately start trying to reconnect to the 953 RESTCONF server, using the reconnection strategy. 955 This connection type minimizes any RESTCONF server 956 to RESTCONF client data-transfer delay, albeit 957 at the expense of holding resources longer."; 958 } 959 } 960 case periodic-connection { 961 container periodic { 962 presence "Indicates that a periodic connection is 963 to be maintained."; 964 description 965 "Periodically connect to the RESTCONF server. 967 This connection type increases resource 968 utilization, albeit with increased delay 969 in RESTCONF server to RESTCONF client 970 interactions. 972 The RESTCONF client SHOULD gracefully close 973 the underlying TLS connection upon completing 974 planned activities. 976 In the case that the previous connection is 977 still active, establishing a new connection 978 is NOT RECOMMENDED."; 979 leaf period { 980 type uint16; 981 units "minutes"; 982 default "60"; 983 description 984 "Duration of time between periodic 985 connections."; 986 } 987 leaf anchor-time { 988 type yang:date-and-time { 989 // constrained to minute-level granularity 990 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 991 + '(Z|[\+\-]\d{2}:\d{2})'; 992 } 993 description 994 "Designates a timestamp before or after which 995 a series of periodic connections are 996 determined. The periodic connections occur 997 at a whole multiple interval from the anchor 998 time. For example, for an anchor time is 15 999 minutes past midnight and a period interval 1000 of 24 hours, then a periodic connection will 1001 occur 15 minutes past midnight everyday."; 1002 } 1003 leaf idle-timeout { 1004 type uint16; 1005 units "seconds"; 1006 default 120; // two minutes 1007 description 1008 "Specifies the maximum number of seconds 1009 that the underlying TCP session may remain 1010 idle. A TCP session will be dropped if it 1011 is idle for an interval longer than this 1012 number of seconds If set to zero, then the 1013 RESTCONF client will never drop a session 1014 because it is idle."; 1015 } 1016 } 1017 } // periodic-connection 1018 } // connection-type 1019 } // connection-type 1020 container reconnect-strategy { 1021 description 1022 "The reconnection strategy directs how a RESTCONF 1023 client reconnects to a RESTCONF server, after 1024 discovering its connection to the server has 1025 dropped, even if due to a reboot. The RESTCONF 1026 client starts with the specified endpoint and 1027 tries to connect to it max-attempts times before 1028 trying the next endpoint in the list (round 1029 robin)."; 1030 leaf start-with { 1031 type enumeration { 1032 enum first-listed { 1033 description 1034 "Indicates that reconnections should start 1035 with the first endpoint listed."; 1036 } 1037 enum last-connected { 1038 description 1039 "Indicates that reconnections should start 1040 with the endpoint last connected to. If 1041 no previous connection has ever been 1042 established, then the first endpoint 1043 configured is used. RESTCONF clients 1044 SHOULD be able to remember the last 1045 endpoint connected to across reboots."; 1046 } 1047 enum random-selection { 1048 description 1049 "Indicates that reconnections should start with 1050 a random endpoint."; 1051 } 1052 } 1053 default "first-listed"; 1054 description 1055 "Specifies which of the RESTCONF server's 1056 endpoints the RESTCONF client should start 1057 with when trying to connect to the RESTCONF 1058 server."; 1059 } 1060 leaf max-attempts { 1061 type uint8 { 1062 range "1..max"; 1063 } 1064 default "3"; 1065 description 1066 "Specifies the number times the RESTCONF client 1067 tries to connect to a specific endpoint before 1068 moving on to the next endpoint in the list 1069 (round robin)."; 1070 } 1071 } 1072 } 1073 } // initiate 1074 container listen { 1075 if-feature "http-listen or https-listen"; 1076 presence "Enables client to accept call-home connections"; 1077 description 1078 "Configures the client to accept call-home TCP connections."; 1079 leaf idle-timeout { 1080 type uint16; 1081 units "seconds"; 1082 default 3600; // one hour 1083 description 1084 "Specifies the maximum number of seconds that an 1085 underlying TCP session may remain idle. A TCP session 1086 will be dropped if it is idle for an interval longer 1087 then this number of seconds. If set to zero, then 1088 the server will never drop a session because it is 1089 idle. Sessions that have a notification subscription 1090 active are never dropped."; 1091 } 1092 list endpoint { 1093 key "name"; 1094 min-elements 1; 1095 description 1096 "List of endpoints to listen for RESTCONF connections."; 1097 leaf name { 1098 type string; 1099 description 1100 "An arbitrary name for the RESTCONF listen endpoint."; 1101 } 1102 uses restconf-client-listen-stack-grouping; 1103 } 1104 } 1105 } // restconf-client-app-grouping 1107 // Protocol accessible node, for servers that implement 1108 // this module. 1109 container restconf-client { 1110 uses restconf-client-app-grouping; 1111 description 1112 "Top-level container for RESTCONF client configuration."; 1113 } 1114 } 1116 1118 3. The "ietf-restconf-server" Module 1120 The RESTCONF server model presented in this section supports both 1121 listening for connections as well as initiating call-home 1122 connections. 1124 YANG feature statements are used to enable implementations to 1125 advertise which potentially uncommon parts of the model the RESTCONF 1126 server supports. 1128 3.1. Data Model Overview 1130 3.1.1. Features 1132 The following diagram lists all the "feature" statements defined in 1133 the "ietf-restconf-server" module: 1135 Features: 1136 +-- http-listen 1137 +-- https-listen 1138 +-- https-call-home 1140 3.1.2. Groupings 1142 The following diagram lists all the "grouping" statements defined in 1143 the "ietf-restconf-server" module: 1145 Groupings: 1146 +-- restconf-server-grouping 1147 +-- restconf-server-listen-stack-grouping 1148 +-- restconf-server-callhome-stack-grouping 1149 +-- restconf-server-app-grouping 1151 Each of these groupings are presented in the following subsections. 1153 3.1.2.1. The "restconf-server-grouping" Grouping 1155 The following tree diagram [RFC8340] illustrates the "restconf- 1156 server-grouping" grouping: 1158 grouping restconf-server-grouping 1159 +-- client-identity-mappings 1160 +---u x509c2n:cert-to-name 1162 Comments: 1164 * The "restconf-server-grouping" defines the configuration for just 1165 "RESTCONF" part of a protocol stack. It does not, for instance, 1166 define any configuration for the "TCP", "TLS", or "HTTP" protocol 1167 layers (for that, see Section 3.1.2.2 and Section 3.1.2.3). 1169 * The "client-identity-mappings" node, which must be enabled by 1170 "feature" statements, defines a mapping from certificate fields to 1171 RESTCONF user names. 1173 * For the referenced grouping statement(s): 1175 - The "cert-to-name" grouping is discussed in Section 4.1 of 1176 [RFC7407]. 1178 3.1.2.2. The "restconf-server-listen-stack-grouping" Grouping 1180 The following tree diagram [RFC8340] illustrates the "restconf- 1181 server-listen-stack-grouping" grouping: 1183 grouping restconf-server-listen-stack-grouping 1184 +-- (transport) 1185 +--:(http) {http-listen}? 1186 | +-- http 1187 | +-- external-endpoint! 1188 | | +-- address inet:ip-address 1189 | | +-- port? inet:port-number 1190 | +-- tcp-server-parameters 1191 | | +---u tcps:tcp-server-grouping 1192 | +-- http-server-parameters 1193 | | +---u https:http-server-grouping 1194 | +-- restconf-server-parameters 1195 | +---u rcs:restconf-server-grouping 1196 +--:(https) {https-listen}? 1197 +-- https 1198 +-- tcp-server-parameters 1199 | +---u tcps:tcp-server-grouping 1200 +-- tls-server-parameters 1201 | +---u tlss:tls-server-grouping 1202 +-- http-server-parameters 1203 | +---u https:http-server-grouping 1204 +-- restconf-server-parameters 1205 +---u rcs:restconf-server-grouping 1207 Comments: 1209 * The "restconf-server-listen-stack-grouping" defines the 1210 configuration for a full RESTCONF protocol stack for RESTCONF 1211 servers that listen for standard connections from RESTCONF 1212 clients, as opposed to initiating call-home [RFC8071] connections. 1214 * The "transport" choice node enables both the HTTP and HTTPS 1215 transports to be configured, with each option enabled by a 1216 "feature" statement. The HTTP option is provided to support cases 1217 where a TLS-terminator is deployed in front of the RESTCONF- 1218 server. 1220 * For the referenced grouping statement(s): 1222 - The "tcp-server-grouping" grouping is discussed in 1223 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1224 - The "tls-server-grouping" grouping is discussed in 1225 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1226 - The "http-server-grouping" grouping is discussed in 1227 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1228 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1229 of this document. 1231 3.1.2.3. The "restconf-server-callhome-stack-grouping" Grouping 1233 The following tree diagram [RFC8340] illustrates the "restconf- 1234 server-callhome-stack-grouping" grouping: 1236 grouping restconf-server-callhome-stack-grouping 1237 +-- (transport) 1238 +--:(https) {https-listen}? 1239 +-- https 1240 +-- tcp-client-parameters 1241 | +---u tcpc:tcp-client-grouping 1242 +-- tls-server-parameters 1243 | +---u tlss:tls-server-grouping 1244 +-- http-server-parameters 1245 | +---u https:http-server-grouping 1246 +-- restconf-server-parameters 1247 +---u rcs:restconf-server-grouping 1249 Comments: 1251 * The "restconf-server-callhome-stack-grouping" defines the 1252 configuration for a full RESTCONF protocol stack, for RESTCONF 1253 servers that initiate call-home [RFC8071] connections to RESTCONF 1254 clients. 1256 * The "transport" choice node enables transport options to be 1257 configured. This document only defines an "https" option, but 1258 other options MAY be augmented in. 1260 * For the referenced grouping statement(s): 1262 - The "tcp-client-grouping" grouping is discussed in 1263 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1264 - The "tls-server-grouping" grouping is discussed in 1265 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1266 - The "http-server-grouping" grouping is discussed in 1267 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1268 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1269 of this document. 1271 3.1.2.4. The "restconf-server-app-grouping" Grouping 1273 The following tree diagram [RFC8340] illustrates the "restconf- 1274 server-app-grouping" grouping: 1276 grouping restconf-server-app-grouping 1277 +-- listen! {http-listen or https-listen}? 1278 | +-- endpoint* [name] 1279 | +-- name? string 1280 | +---u restconf-server-listen-stack-grouping 1281 +-- call-home! {https-call-home}? 1282 +-- restconf-client* [name] 1283 +-- name? string 1284 +-- endpoints 1285 | +-- endpoint* [name] 1286 | +-- name? string 1287 | +---u restconf-server-callhome-stack-grouping 1288 +-- connection-type 1289 | +-- (connection-type) 1290 | +--:(persistent-connection) 1291 | | +-- persistent! 1292 | +--:(periodic-connection) 1293 | +-- periodic! 1294 | +-- period? uint16 1295 | +-- anchor-time? yang:date-and-time 1296 | +-- idle-timeout? uint16 1297 +-- reconnect-strategy 1298 +-- start-with? enumeration 1299 +-- max-attempts? uint8 1301 Comments: 1303 * The "restconf-server-app-grouping" defines the configuration for a 1304 RESTCONF server that supports both listening for connections from 1305 RESTCONF clients as well as initiatiating call-home connections to 1306 RESTCONF clients. 1308 * Both the "listen" and "call-home" subtrees must be enabled by 1309 "feature" statements. 1311 * For the referenced grouping statement(s): 1313 - The "restconf-server-listen-stack-grouping" grouping is 1314 discussed in Section 3.1.2.2 in this document. 1315 - The "restconf-server-callhome-stack-grouping" grouping is 1316 discussed in Section 3.1.2.3 in this document. 1318 3.1.3. Protocol-accessible Nodes 1320 The following diagram lists all the protocol-accessible nodes defined 1321 in the "ietf-restconf-server" module: 1323 module: ietf-restconf-server 1324 +--rw restconf-server 1325 +---u restconf-server-app-grouping 1327 Comments: 1329 * Protocol-accessible nodes are those nodes that are accessible when 1330 the module is "implemented", as described in Section 5.6.5 of 1331 [RFC7950]. 1333 * For the "ietf-restconf-server" module, the protocol-accessible 1334 nodes are an instance of the "restconf-server-app-grouping" 1335 discussed in Section 3.1.2.4 grouping. 1337 * The reason for why "restconf-server-app-grouping" exists separate 1338 from the protocol-accessible nodes definition is so as to enable 1339 instances of restconf-server-app-grouping to be instantiated in 1340 other locations, as may be needed or desired by some modules. 1342 3.2. Example Usage 1344 The following example illustrates configuring a RESTCONF server to 1345 listen for RESTCONF client connections, as well as configuring call- 1346 home to one RESTCONF client. 1348 This example is consistent with the examples presented in Section 2.2 1349 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 1350 [I-D.ietf-netconf-keystore]. 1352 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1354 1359 1360 1361 1362 restconf/https 1363 1364 1365 11.22.33.44 1366 1367 1368 1369 1370 1371 rsa-asymmetric-key 1372 ex-rsa-cert 1373 1374 1375 1376 1377 1378 trusted-client-ca-certs 1380 1381 1382 trusted-client-ee-certs 1384 1385 1386 1387 1388 1389 1390 1391 foo.example.com 1392 1393 1394 1395 1396 1 1397 11:0A:05:11:00 1398 x509c2n:specified 1399 scooby-doo 1400 1401 1402 2 1403 x509c2n:san-any 1404 1405 1406 1407 1408 1409 1411 1412 1413 1414 config-manager 1415 1416 1417 east-data-center 1418 1419 1420 east.example.com 1421 1422 15 1423 3 1424 30 1425 1426 1427 1428 1429 1430 1431 rsa-asymmetric-key 1433 ex-rsa-cert 1434 1435 1436 1437 1438 1439 trusted-client-ca-certs 1441 1442 1443 trusted-client-ee-certs 1445 1446 1447 1448 1449 30 1450 3 1451 1452 1453 1454 1455 foo.example.com 1456 1457 1458 1459 1460 1 1461 11:0A:05:11:00 1462 x509c2n:specified 1463 scooby-doo 1464 1465 1466 2 1467 x509c2n:san-any 1468 1469 1470 1471 1472 1473 1474 west-data-center 1475 1476 1477 west.example.com 1478 1479 15 1480 3 1481 30 1482 1483 1484 1485 1486 1487 1488 rsa-asymmetric-key 1490 ex-rsa-cert 1491 1492 1493 1494 1495 1496 trusted-client-ca-certs 1498 1499 1500 trusted-client-ee-certs 1502 1503 1504 1505 1506 30 1507 3 1508 1509 1510 1511 1512 foo.example.com 1513 1514 1515 1516 1517 1 1518 11:0A:05:11:00 1519 x509c2n:specified 1520 scooby-doo 1521 1522 1523 2 1524 x509c2n:san-any 1525 1526 1527 1528 1529 1530 1531 1532 1533 300 1534 60 1535 1536 1537 1538 last-connected 1539 3 1540 1541 1542 1543 1545 3.3. YANG Module 1547 This YANG module has normative references to [RFC6991], [RFC7407], 1548 [RFC8040], [RFC8071], [I-D.ietf-netconf-tcp-client-server], 1549 [I-D.ietf-netconf-tls-client-server], and 1550 [I-D.ietf-netconf-http-client-server]. 1552 file "ietf-restconf-server@2020-07-08.yang" 1554 module ietf-restconf-server { 1555 yang-version 1.1; 1556 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1557 prefix rcs; 1559 import ietf-yang-types { 1560 prefix yang; 1561 reference 1562 "RFC 6991: Common YANG Data Types"; 1564 } 1566 import ietf-inet-types { 1567 prefix inet; 1568 reference 1569 "RFC 6991: Common YANG Data Types"; 1570 } 1572 import ietf-x509-cert-to-name { 1573 prefix x509c2n; 1574 reference 1575 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1576 } 1578 import ietf-tcp-client { 1579 prefix tcpc; 1580 reference 1581 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1582 } 1584 import ietf-tcp-server { 1585 prefix tcps; 1586 reference 1587 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1588 } 1590 import ietf-tls-server { 1591 prefix tlss; 1592 reference 1593 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1594 } 1596 import ietf-http-server { 1597 prefix https; 1598 reference 1599 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 1600 } 1602 organization 1603 "IETF NETCONF (Network Configuration) Working Group"; 1605 contact 1606 "WG Web: 1607 WG List: 1608 Author: Kent Watsen 1609 Author: Gary Wu 1610 Author: Juergen Schoenwaelder 1611 "; 1613 description 1614 "This module contains a collection of YANG definitions 1615 for configuring RESTCONF servers. 1617 Copyright (c) 2020 IETF Trust and the persons identified 1618 as authors of the code. All rights reserved. 1620 Redistribution and use in source and binary forms, with 1621 or without modification, is permitted pursuant to, and 1622 subject to the license terms contained in, the Simplified 1623 BSD License set forth in Section 4.c of the IETF Trust's 1624 Legal Provisions Relating to IETF Documents 1625 (https://trustee.ietf.org/license-info). 1627 This version of this YANG module is part of RFC IIII 1628 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 1629 itself for full legal notices. 1631 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1632 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1633 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1634 are to be interpreted as described in BCP 14 (RFC 2119) 1635 (RFC 8174) when, and only when, they appear in all 1636 capitals, as shown here."; 1638 revision 2020-07-08 { 1639 description 1640 "Initial version"; 1641 reference 1642 "RFC IIII: RESTCONF Client and Server Models"; 1643 } 1645 // Features 1647 feature http-listen { 1648 description 1649 "The 'http-listen' feature indicates that the RESTCONF server 1650 supports opening a port to listen for incoming RESTCONF over 1651 TPC client connections, whereby the TLS connections are 1652 terminated by an external system."; 1653 reference 1654 "RFC 8040: RESTCONF Protocol"; 1655 } 1657 feature https-listen { 1658 description 1659 "The 'https-listen' feature indicates that the RESTCONF server 1660 supports opening a port to listen for incoming RESTCONF over 1661 TLS client connections, whereby the TLS connections are 1662 terminated by the server itself."; 1663 reference 1664 "RFC 8040: RESTCONF Protocol"; 1665 } 1667 feature https-call-home { 1668 description 1669 "The 'https-call-home' feature indicates that the RESTCONF 1670 server supports initiating connections to RESTCONF clients."; 1671 reference 1672 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1673 } 1675 // Groupings 1677 grouping restconf-server-grouping { 1678 description 1679 "A reusable grouping for configuring a RESTCONF server 1680 without any consideration for how underlying transport 1681 sessions are established. 1683 Note that this grouping uses a fairly typical descendent 1684 node name such that a stack of 'uses' statements will 1685 have name conflicts. It is intended that the consuming 1686 data model will resolve the issue by wrapping the 'uses' 1687 statement in a container called, e.g., 1688 'restconf-server-parameters'. This model purposely does 1689 not do this itself so as to provide maximum flexibility 1690 to consuming models."; 1692 container client-identity-mappings { 1693 description 1694 "Specifies mappings through which RESTCONF client X.509 1695 certificates are used to determine a RESTCONF username. 1696 If no matching and valid cert-to-name list entry can be 1697 found, then the RESTCONF server MUST close the connection, 1698 and MUST NOT accept RESTCONF messages over it."; 1699 reference 1700 "RFC 7407: A YANG Data Model for SNMP Configuration."; 1701 uses x509c2n:cert-to-name { 1702 refine "cert-to-name/fingerprint" { 1703 mandatory false; 1704 description 1705 "A 'fingerprint' value does not need to be specified 1706 when the 'cert-to-name' mapping is independent of 1707 fingerprint matching. A 'cert-to-name' having no 1708 fingerprint value will match any client certificate 1709 and therefore should only be present at the end of 1710 the user-ordered 'cert-to-name' list."; 1711 } 1712 } 1713 } 1714 } 1716 grouping restconf-server-listen-stack-grouping { 1717 description 1718 "A reusable grouping for configuring a RESTCONF server 1719 'listen' protocol stack for a single connection."; 1720 choice transport { 1721 mandatory true; 1722 description 1723 "Selects between available transports. This is a 1724 'choice' statement so as to support additional 1725 transport options to be augmented in."; 1726 case http { 1727 if-feature "http-listen"; 1728 container http { 1729 description 1730 "Configures RESTCONF server stack assuming that 1731 TLS-termination is handled externally."; 1732 container external-endpoint { 1733 presence 1734 "Specifies configuration for an external endpoint."; 1735 description 1736 "Identifies contact information for the external 1737 system that terminates connections before passing 1738 them thru to this server (e.g., a network address 1739 translator or a load balancer). These values have 1740 no effect on the local operation of this server, but 1741 may be used by the application when needing to 1742 inform other systems how to contact this server."; 1743 leaf address { 1744 type inet:ip-address; 1745 mandatory true; 1746 description 1747 "The IP address or hostname of the external system 1748 that terminates incoming RESTCONF client 1749 connections before forwarding them to this 1750 server."; 1751 } 1752 leaf port { 1753 type inet:port-number; 1754 default "443"; 1755 description 1756 "The port number that the external system listens 1757 on for incoming RESTCONF client connections that 1758 are forwarded to this server. The default HTTPS 1759 port (443) is used, as expected for a RESTCONF 1760 connection."; 1761 } 1762 } 1763 container tcp-server-parameters { 1764 description 1765 "A wrapper around the TCP server parameters 1766 to avoid name collisions."; 1767 uses tcps:tcp-server-grouping { 1768 refine "local-port" { 1769 default "80"; 1770 description 1771 "The RESTCONF server will listen on the IANA- 1772 assigned well-known port value for 'http' 1773 (80) if no value is specified."; 1774 } 1775 } 1776 } 1777 container http-server-parameters { 1778 description 1779 "A wrapper around the HTTP server parameters 1780 to avoid name collisions."; 1781 uses https:http-server-grouping; 1782 } 1783 container restconf-server-parameters { 1784 description 1785 "A wrapper around the RESTCONF server parameters 1786 to avoid name collisions."; 1787 uses rcs:restconf-server-grouping; 1788 } 1789 } 1790 } 1791 case https { 1792 if-feature "https-listen"; 1793 container https { 1794 description 1795 "Configures RESTCONF server stack assuming that 1796 TLS-termination is handled internally."; 1797 container tcp-server-parameters { 1798 description 1799 "A wrapper around the TCP server parameters 1800 to avoid name collisions."; 1801 uses tcps:tcp-server-grouping { 1802 refine "local-port" { 1803 default "443"; 1804 description 1805 "The RESTCONF server will listen on the IANA- 1806 assigned well-known port value for 'https' 1807 (443) if no value is specified."; 1808 } 1809 } 1810 } 1811 container tls-server-parameters { 1812 description 1813 "A wrapper around the TLS server parameters 1814 to avoid name collisions."; 1815 uses tlss:tls-server-grouping; 1816 } 1817 container http-server-parameters { 1818 description 1819 "A wrapper around the HTTP server parameters 1820 to avoid name collisions."; 1821 uses https:http-server-grouping; 1822 } 1823 container restconf-server-parameters { 1824 description 1825 "A wrapper around the RESTCONF server parameters 1826 to avoid name collisions."; 1827 uses rcs:restconf-server-grouping; 1828 } 1829 } 1830 } 1831 } 1832 } 1834 grouping restconf-server-callhome-stack-grouping { 1835 description 1836 "A reusable grouping for configuring a RESTCONF server 1837 'call-home' protocol stack, for a single connection."; 1838 choice transport { 1839 mandatory true; 1840 description 1841 "Selects between available transports. This is a 1842 'choice' statement so as to support additional 1843 transport options to be augmented in."; 1844 case https { 1845 if-feature "https-listen"; 1846 container https { 1847 description 1848 "Configures RESTCONF server stack assuming that 1849 TLS-termination is handled internally."; 1850 container tcp-client-parameters { 1851 description 1852 "A wrapper around the TCP client parameters 1853 to avoid name collisions."; 1854 uses tcpc:tcp-client-grouping { 1855 refine "remote-port" { 1856 default "4336"; 1857 description 1858 "The RESTCONF server will attempt to 1859 connect to the IANA-assigned well-known 1860 port for 'restconf-ch-tls' (4336) if no 1861 value is specified."; 1862 } 1863 } 1864 } 1865 container tls-server-parameters { 1866 description 1867 "A wrapper around the TLS server parameters 1868 to avoid name collisions."; 1869 uses tlss:tls-server-grouping; 1870 } 1871 container http-server-parameters { 1872 description 1873 "A wrapper around the HTTP server parameters 1874 to avoid name collisions."; 1875 uses https:http-server-grouping; 1876 } 1877 container restconf-server-parameters { 1878 description 1879 "A wrapper around the RESTCONF server parameters 1880 to avoid name collisions."; 1881 uses rcs:restconf-server-grouping; 1882 } 1883 } 1884 } 1885 } 1886 } 1888 grouping restconf-server-app-grouping { 1889 description 1890 "A reusable grouping for configuring a RESTCONF server 1891 application that supports both 'listen' and 'call-home' 1892 protocol stacks for a multiplicity of connections."; 1893 container listen { 1894 if-feature "http-listen or https-listen"; 1895 presence 1896 "Enables the RESTCONF server to listen for RESTCONF 1897 client connections."; 1898 description "Configures listen behavior"; 1899 list endpoint { 1900 key "name"; 1901 min-elements 1; 1902 description 1903 "List of endpoints to listen for RESTCONF connections."; 1904 leaf name { 1905 type string; 1906 description 1907 "An arbitrary name for the RESTCONF listen endpoint."; 1908 } 1909 uses restconf-server-listen-stack-grouping; 1910 } 1911 } 1912 container call-home { 1913 if-feature "https-call-home"; 1914 presence 1915 "Enables the RESTCONF server to initiate the underlying 1916 transport connection to RESTCONF clients."; 1917 description "Configures call-home behavior"; 1918 list restconf-client { 1919 key "name"; 1920 min-elements 1; 1921 description 1922 "List of RESTCONF clients the RESTCONF server is to 1923 maintain simultaneous call-home connections with."; 1924 leaf name { 1925 type string; 1926 description 1927 "An arbitrary name for the remote RESTCONF client."; 1928 } 1929 container endpoints { 1930 description 1931 "Container for the list of endpoints."; 1932 list endpoint { 1933 key "name"; 1934 min-elements 1; 1935 ordered-by user; 1936 description 1937 "User-ordered list of endpoints for this RESTCONF 1938 client. Defining more than one enables high- 1939 availability."; 1940 leaf name { 1941 type string; 1942 description 1943 "An arbitrary name for this endpoint."; 1944 } 1945 uses restconf-server-callhome-stack-grouping; 1946 } 1948 } 1949 container connection-type { 1950 description 1951 "Indicates the RESTCONF server's preference for how the 1952 RESTCONF connection is maintained."; 1953 choice connection-type { 1954 mandatory true; 1955 description 1956 "Selects between available connection types."; 1957 case persistent-connection { 1958 container persistent { 1959 presence "Indicates that a persistent connection is 1960 to be maintained."; 1961 description 1962 "Maintain a persistent connection to the RESTCONF 1963 client. If the connection goes down, immediately 1964 start trying to reconnect to the RESTCONF server, 1965 using the reconnection strategy. 1967 This connection type minimizes any RESTCONF 1968 client to RESTCONF server data-transfer delay, 1969 albeit at the expense of holding resources 1970 longer."; 1971 } 1972 } 1973 case periodic-connection { 1974 container periodic { 1975 presence "Indicates that a periodic connection is 1976 to be maintained."; 1977 description 1978 "Periodically connect to the RESTCONF client. 1980 This connection type increases resource 1981 utilization, albeit with increased delay in 1982 RESTCONF client to RESTCONF client interactions. 1984 The RESTCONF client SHOULD gracefully close 1985 the underlying TLS connection upon completing 1986 planned activities. If the underlying TLS 1987 connection is not closed gracefully, the 1988 RESTCONF server MUST immediately attempt 1989 to reestablish the connection. 1991 In the case that the previous connection is 1992 still active (i.e., the RESTCONF client has not 1993 closed it yet), establishing a new connection 1994 is NOT RECOMMENDED."; 1996 leaf period { 1997 type uint16; 1998 units "minutes"; 1999 default "60"; 2000 description 2001 "Duration of time between periodic connections."; 2002 } 2003 leaf anchor-time { 2004 type yang:date-and-time { 2005 // constrained to minute-level granularity 2006 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2007 + '(Z|[\+\-]\d{2}:\d{2})'; 2008 } 2009 description 2010 "Designates a timestamp before or after which a 2011 series of periodic connections are determined. 2012 The periodic connections occur at a whole 2013 multiple interval from the anchor time. For 2014 example, for an anchor time is 15 minutes past 2015 midnight and a period interval of 24 hours, then 2016 a periodic connection will occur 15 minutes past 2017 midnight everyday."; 2018 } 2019 leaf idle-timeout { 2020 type uint16; 2021 units "seconds"; 2022 default 120; // two minutes 2023 description 2024 "Specifies the maximum number of seconds that 2025 the underlying TCP session may remain idle. 2026 A TCP session will be dropped if it is idle 2027 for an interval longer than this number of 2028 seconds. If set to zero, then the server 2029 will never drop a session because it is idle."; 2030 } 2031 } 2032 } 2033 } 2034 } 2035 container reconnect-strategy { 2036 description 2037 "The reconnection strategy directs how a RESTCONF server 2038 reconnects to a RESTCONF client after discovering its 2039 connection to the client has dropped, even if due to a 2040 reboot. The RESTCONF server starts with the specified 2041 endpoint and tries to connect to it max-attempts times 2042 before trying the next endpoint in the list (round 2043 robin)."; 2045 leaf start-with { 2046 type enumeration { 2047 enum first-listed { 2048 description 2049 "Indicates that reconnections should start with 2050 the first endpoint listed."; 2051 } 2052 enum last-connected { 2053 description 2054 "Indicates that reconnections should start with 2055 the endpoint last connected to. If no previous 2056 connection has ever been established, then the 2057 first endpoint configured is used. RESTCONF 2058 servers SHOULD be able to remember the last 2059 endpoint connected to across reboots."; 2060 } 2061 enum random-selection { 2062 description 2063 "Indicates that reconnections should start with 2064 a random endpoint."; 2065 } 2066 } 2067 default "first-listed"; 2068 description 2069 "Specifies which of the RESTCONF client's endpoints 2070 the RESTCONF server should start with when trying 2071 to connect to the RESTCONF client."; 2072 } 2073 leaf max-attempts { 2074 type uint8 { 2075 range "1..max"; 2076 } 2077 default "3"; 2078 description 2079 "Specifies the number times the RESTCONF server tries 2080 to connect to a specific endpoint before moving on to 2081 the next endpoint in the list (round robin)."; 2082 } 2083 } 2084 } // restconf-client 2085 } // call-home 2086 } // restconf-server-app-grouping 2088 // Protocol accessible node, for servers that implement 2089 // this module. 2090 container restconf-server { 2091 uses restconf-server-app-grouping; 2092 description 2093 "Top-level container for RESTCONF server configuration."; 2094 } 2096 } 2098 2100 4. Security Considerations 2102 4.1. The "ietf-restconf-client" YANG Module 2104 The "ietf-restconf-client" YANG module defines data nodes that are 2105 designed to be accessed via YANG based management protocols, such as 2106 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2107 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2108 with mutual authentication. 2110 The NETCONF access control model (NACM) [RFC8341] provides the means 2111 to restrict access for particular users to a pre-configured subset of 2112 all available protocol operations and content. 2114 None of the readable data nodes in this YANG module are considered 2115 sensitive or vulnerable in network environments. The NACM "default- 2116 deny-all" extension has not been set for any data nodes defined in 2117 this module. 2119 None of the writable data nodes in this YANG module are considered 2120 sensitive or vulnerable in network environments. The NACM "default- 2121 deny-write" extension has not been set for any data nodes defined in 2122 this module. 2124 This module does not define any RPCs, actions, or notifications, and 2125 thus the security consideration for such is not provided here. 2127 Please be aware that this module uses groupings defined in other RFCs 2128 that define data nodes that do set the NACM "default-deny-all" and 2129 "default-deny-write" extensions. 2131 4.2. The "ietf-restconf-server" YANG Module 2133 The "ietf-restconf-server" YANG module defines data nodes that are 2134 designed to be accessed via YANG based management protocols, such as 2135 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2136 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2137 with mutual authentication. 2139 The NETCONF access control model (NACM) [RFC8341] provides the means 2140 to restrict access for particular users to a pre-configured subset of 2141 all available protocol operations and content. 2143 None of the readable data nodes in this YANG module are considered 2144 sensitive or vulnerable in network environments. The NACM "default- 2145 deny-all" extension has not been set for any data nodes defined in 2146 this module. 2148 None of the writable data nodes in this YANG module are considered 2149 sensitive or vulnerable in network environments. The NACM "default- 2150 deny-write" extension has not been set for any data nodes defined in 2151 this module. 2153 This module does not define any RPCs, actions, or notifications, and 2154 thus the security consideration for such is not provided here. 2156 Please be aware that this module uses groupings defined in other RFCs 2157 that define data nodes that do set the NACM "default-deny-all" and 2158 "default-deny-write" extensions. 2160 5. IANA Considerations 2162 5.1. The IETF XML Registry 2164 This document registers two URIs in the "ns" subregistry of the IETF 2165 XML Registry [RFC3688]. Following the format in [RFC3688], the 2166 following registrations are requested: 2168 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2169 Registrant Contact: The NETCONF WG of the IETF. 2170 XML: N/A, the requested URI is an XML namespace. 2172 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2173 Registrant Contact: The NETCONF WG of the IETF. 2174 XML: N/A, the requested URI is an XML namespace. 2176 5.2. The YANG Module Names Registry 2178 This document registers two YANG modules in the YANG Module Names 2179 registry [RFC6020]. Following the format in [RFC6020], the the 2180 following registrations are requested: 2182 name: ietf-restconf-client 2183 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2184 prefix: ncc 2185 reference: RFC IIII 2187 name: ietf-restconf-server 2188 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2189 prefix: ncs 2190 reference: RFC IIII 2192 6. References 2194 6.1. Normative References 2196 [I-D.ietf-netconf-http-client-server] 2197 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2198 Servers", Work in Progress, Internet-Draft, draft-ietf- 2199 netconf-http-client-server-03, 20 May 2020, 2200 . 2203 [I-D.ietf-netconf-keystore] 2204 Watsen, K., "A YANG Data Model for a Keystore", Work in 2205 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 2206 20 May 2020, . 2209 [I-D.ietf-netconf-tcp-client-server] 2210 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2211 and TCP Servers", Work in Progress, Internet-Draft, draft- 2212 ietf-netconf-tcp-client-server-06, 16 June 2020, 2213 . 2216 [I-D.ietf-netconf-tls-client-server] 2217 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 2218 TLS Servers", Work in Progress, Internet-Draft, draft- 2219 ietf-netconf-tls-client-server-19, 20 May 2020, 2220 . 2223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2224 Requirement Levels", BCP 14, RFC 2119, 2225 DOI 10.17487/RFC2119, March 1997, 2226 . 2228 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2229 the Network Configuration Protocol (NETCONF)", RFC 6020, 2230 DOI 10.17487/RFC6020, October 2010, 2231 . 2233 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2234 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2235 . 2237 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2238 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2239 December 2014, . 2241 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2242 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2243 . 2245 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2246 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2247 . 2249 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2250 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2251 . 2253 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2254 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2255 May 2017, . 2257 6.2. Informative References 2259 [I-D.ietf-netconf-crypto-types] 2260 Watsen, K., "Common YANG Data Types for Cryptography", 2261 Work in Progress, Internet-Draft, draft-ietf-netconf- 2262 crypto-types-15, 20 May 2020, 2263 . 2266 [I-D.ietf-netconf-netconf-client-server] 2267 Watsen, K., "NETCONF Client and Server Models", Work in 2268 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2269 client-server-19, 20 May 2020, 2270 . 2273 [I-D.ietf-netconf-restconf-client-server] 2274 Watsen, K., "RESTCONF Client and Server Models", Work in 2275 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2276 client-server-19, 20 May 2020, 2277 . 2280 [I-D.ietf-netconf-ssh-client-server] 2281 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 2282 SSH Servers", Work in Progress, Internet-Draft, draft- 2283 ietf-netconf-ssh-client-server-19, 20 May 2020, 2284 . 2287 [I-D.ietf-netconf-trust-anchors] 2288 Watsen, K., "A YANG Data Model for a Truststore", Work in 2289 Progress, Internet-Draft, draft-ietf-netconf-trust- 2290 anchors-10, 20 May 2020, . 2293 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2294 DOI 10.17487/RFC3688, January 2004, 2295 . 2297 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2298 and A. Bierman, Ed., "Network Configuration Protocol 2299 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2300 . 2302 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2303 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2304 . 2306 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2307 Access Control Model", STD 91, RFC 8341, 2308 DOI 10.17487/RFC8341, March 2018, 2309 . 2311 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2312 and R. Wilton, "Network Management Datastore Architecture 2313 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2314 . 2316 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2317 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2318 . 2320 Appendix A. Expanded Tree Diagrams 2321 A.1. Expanded Tree Diagram for 'ietf-restconf-client' 2323 The following tree diagram [RFC8340] provides an overview of the data 2324 model for the "ietf-restconf-client" module. 2326 This tree diagram shows all the nodes defined in this module, 2327 including those defined by "grouping" statements used by this module. 2329 Please see Section 2.1 for a tree diagram that illustrates what the 2330 module looks like without all the "grouping" statements expanded. 2332 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-client-tree.txt) 2334 A.2. Expanded Tree Diagram for 'ietf-restconf-server' 2336 The following tree diagram [RFC8340] provides an overview of the data 2337 model for the "ietf-restconf-server" module. 2339 This tree diagram shows all the nodes defined in this module, 2340 including those defined by "grouping" statements used by this module. 2342 Please see Section 3.1 for a tree diagram that illustrates what the 2343 module looks like without all the "grouping" statements expanded. 2345 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-server-tree.txt) 2347 Appendix B. Change Log 2349 This section is to be removed before publishing as an RFC. 2351 B.1. 00 to 01 2353 * Renamed "keychain" to "keystore". 2355 B.2. 01 to 02 2357 * Filled in previously missing 'ietf-restconf-client' module. 2359 * Updated the ietf-restconf-server module to accommodate new 2360 grouping 'ietf-tls-server-grouping'. 2362 B.3. 02 to 03 2364 * Refined use of tls-client-grouping to add a must statement 2365 indicating that the TLS client must specify a client-certificate. 2367 * Changed restconf-client??? to be a grouping (not a container). 2369 B.4. 03 to 04 2371 * Added RFC 8174 to Requirements Language Section. 2373 * Replaced refine statement in ietf-restconf-client to add a 2374 mandatory true. 2376 * Added refine statement in ietf-restconf-server to add a must 2377 statement. 2379 * Now there are containers and groupings, for both the client and 2380 server models. 2382 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2384 * Updated examples to inline key and certificates (no longer a 2385 leafref to keystore) 2387 B.5. 04 to 05 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 B.6. 05 to 06 2396 * Fixed change log missing section issue. 2398 * Updated examples to match latest updates to the crypto-types, 2399 trust-anchors, and keystore drafts. 2401 * Reduced line length of the YANG modules to fit within 69 columns. 2403 B.7. 06 to 07 2405 * removed "idle-timeout" from "persistent" connection config. 2407 * Added "random-selection" for reconnection-strategy's "starts-with" 2408 enum. 2410 * Replaced "connection-type" choice default (persistent) with 2411 "mandatory true". 2413 * Reduced the periodic-connection's "idle-timeout" from 5 to 2 2414 minutes. 2416 * Replaced reconnect-timeout with period/anchor-time combo. 2418 B.8. 07 to 08 2420 * Modified examples to be compatible with new crypto-types algs 2422 B.9. 08 to 09 2424 * Corrected use of "mandatory true" for "address" leafs. 2426 * Updated examples to reflect update to groupings defined in the 2427 keystore draft. 2429 * Updated to use groupings defined in new TCP and HTTP drafts. 2431 * Updated copyright date, boilerplate template, affiliation, and 2432 folding algorithm. 2434 B.10. 09 to 10 2436 * Reformatted YANG modules. 2438 B.11. 10 to 11 2440 * Adjusted for the top-level "demux container" added to groupings 2441 imported from other modules. 2443 * Added "must" expressions to ensure that keepalives are not 2444 configured for "periodic" connections. 2446 * Updated the boilerplate text in module-level "description" 2447 statement to match copyeditor convention. 2449 * Moved "expanded" tree diagrams to the Appendix. 2451 B.12. 11 to 12 2453 * Removed the 'must' statement limiting keepalives in periodic 2454 connections. 2456 * Updated models and examples to reflect removal of the "demux" 2457 containers in the imported models. 2459 * Updated the "periodic-connnection" description statements to 2460 better describe behavior when connections are not closed 2461 gracefully. 2463 * Updated text to better reference where certain examples come from 2464 (e.g., which Section in which draft). 2466 * In the server model, commented out the "must 'pinned-ca-certs or 2467 pinned-client-certs'" statement to reflect change made in the TLS 2468 draft whereby the trust anchors MAY be defined externally. 2470 * Replaced the 'listen', 'initiate', and 'call-home' features with 2471 boolean expressions. 2473 B.13. 12 to 13 2475 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2476 anchors/truststore/g + s/pinned.//) 2478 * In ietf-restconf-server, Added 'http-listen' (not https-listen) 2479 choice, to support case when server is behind a TLS-terminator. 2481 * Refactored server module to be more like other 'server' models. 2482 If folks like it, will also apply to the client model, as well as 2483 to both the netconf client/server models. Now the 'restconf- 2484 server-grouping' is just the RC-specific bits (i.e., the "demux" 2485 container minus the container), 'restconf-server- 2486 [listen|callhome]-stack-grouping' is the protocol stack for a 2487 single connection, and 'restconf-server-app-grouping' is 2488 effectively what was before (both listen+callhome for many 2489 inbound/outbound endpoints). 2491 B.14. 13 to 14 2493 * Updated examples to reflect ietf-crypto-types change (e.g., 2494 identities --> enumerations) 2496 * Adjusting from change in TLS client model (removing the top-level 2497 'certificate' container). 2499 * Added "external-endpoint" to the "http-listen" choice in ietf- 2500 restconf-server. 2502 B.15. 14 to 15 2504 * Added missing "or https-listen" clause in a "must" expression. 2506 * Refactored the client module similar to how the server module was 2507 refactored in -13. Now the 'restconf-client-grouping' is just the 2508 RC-specific bits, the 'restconf-client-[initiate|listen]-stack- 2509 grouping' is the protocol stack for a single connection, and 2510 'restconf-client-app-grouping' is effectively what was before 2511 (both listen+callhome for many inbound/outbound endpoints). 2513 B.16. 15 to 16 2515 * Added refinement to make "cert-to-name/fingerprint" be mandatory 2516 false. 2518 * Commented out refinement to "tls-server-grouping/client- 2519 authentication" until a better "must" expression is defined. 2521 * Updated restconf-client example to reflect that http-client- 2522 grouping no longer has a "protocol-version" leaf. 2524 B.17. 16 to 17 2526 * Updated examples to include the "*-key-format" nodes. 2528 * Updated examples to remove the "required" nodes. 2530 B.18. 17 to 18 2532 * Updated examples to reflect new "bag" addition to truststore. 2534 B.19. 18 to 19 2536 * Updated examples to remove the 'algorithm' nodes. 2538 * Updated examples to reflect the new TLS keepalives structure. 2540 * Removed the 'protocol-versions' node from the restconf-server 2541 examples. 2543 * Added a "Note to Reviewers" note to first page. 2545 B.20. 19 to 20 2547 * Moved and changed "must" statement so that either TLS *or* HTTP 2548 auth must be configured. 2550 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2551 diagrams]. 2553 * Updated the Security Considerations section. 2555 Acknowledgements 2557 The authors would like to thank for following for lively discussions 2558 on list and in the halls (ordered by last name): Andy Bierman, Martin 2559 Bjorklund, Benoit Claise, Mehmet Ersue, Ramkumar Dhanapal, Balazs 2560 Kovacs, Radek Krejci, David Lamparter, Ladislav Lhotka, Alan Luchuk, 2561 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, Bert 2562 Wijnen. 2564 Author's Address 2566 Kent Watsen 2567 Watsen Networks 2569 Email: kent+ietf@watsen.net