idnits 2.17.1 draft-ietf-netconf-netconf-client-server-11.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 1988 has weird spacing: '...address ine...' == Line 2133 has weird spacing: '...address ine...' == Line 2236 has weird spacing: '...address ine...' == Line 2351 has weird spacing: '...address ine...' == Line 2442 has weird spacing: '...address ine...' == (3 more instances...) -- The document date (April 7, 2019) is 1845 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 (-35) exists of draft-ietf-netconf-keystore-08 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-11 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-10 == Outdated reference: A later version (-02) exists of draft-kwatsen-netconf-tcp-client-server-00 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 April 7, 2019 5 Expires: October 9, 2019 7 NETCONF Client and Server Models 8 draft-ietf-netconf-netconf-client-server-11 10 Abstract 12 This document defines two YANG modules, one module to configure a 13 NETCONF client and the other module to configure a NETCONF server. 14 Both modules support both the SSH and TLS transport protocols, and 15 support both standard NETCONF and NETCONF Call Home connections. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 This document contains references to other drafts in progress, both 25 in the Normative References section, as well as in body text 26 throughout. Please update the following references to reflect their 27 final RFC assignments: 29 o I-D.ietf-netconf-keystore 31 o I-D.ietf-netconf-tcp-client-server 33 o I-D.ietf-netconf-ssh-client-server 35 o I-D.ietf-netconf-tls-client-server 37 Artwork in this document contains shorthand references to drafts in 38 progress. Please apply the following replacements: 40 o "XXXX" --> the assigned RFC value for this draft 42 o "AAAA" --> the assigned RFC value for I-D.ietf-netconf-tcp-client- 43 server 45 o "YYYY" --> the assigned RFC value for I-D.ietf-netconf-ssh-client- 46 server 48 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-tls-client- 49 server 51 Artwork in this document contains placeholder values for the date of 52 publication of this draft. Please apply the following replacement: 54 o "2019-04-07" --> the publication date of this draft 56 The following Appendix section is to be removed prior to publication: 58 o Appendix B. Change Log 60 Status of This Memo 62 This Internet-Draft is submitted in full conformance with the 63 provisions of BCP 78 and BCP 79. 65 Internet-Drafts are working documents of the Internet Engineering 66 Task Force (IETF). Note that other groups may also distribute 67 working documents as Internet-Drafts. The list of current Internet- 68 Drafts is at https://datatracker.ietf.org/drafts/current/. 70 Internet-Drafts are draft documents valid for a maximum of six months 71 and may be updated, replaced, or obsoleted by other documents at any 72 time. It is inappropriate to use Internet-Drafts as reference 73 material or to cite them other than as "work in progress." 75 This Internet-Draft will expire on October 9, 2019. 77 Copyright Notice 79 Copyright (c) 2019 IETF Trust and the persons identified as the 80 document authors. All rights reserved. 82 This document is subject to BCP 78 and the IETF Trust's Legal 83 Provisions Relating to IETF Documents 84 (https://trustee.ietf.org/license-info) in effect on the date of 85 publication of this document. Please review these documents 86 carefully, as they describe your rights and restrictions with respect 87 to this document. Code Components extracted from this document must 88 include Simplified BSD License text as described in Section 4.e of 89 the Trust Legal Provisions and are provided without warranty as 90 described in the Simplified BSD License. 92 Table of Contents 94 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 95 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 96 3. The NETCONF Client Model . . . . . . . . . . . . . . . . . . 4 97 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 98 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 5 99 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 100 4. The NETCONF Server Model . . . . . . . . . . . . . . . . . . 18 101 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 18 102 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 19 103 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 25 104 5. Design Considerations . . . . . . . . . . . . . . . . . . . . 36 105 5.1. Support all NETCONF transports . . . . . . . . . . . . . 36 106 5.2. Enable each transport to select which keys to use . . . . 36 107 5.3. Support authenticating NETCONF clients certificates . . . 36 108 5.4. Support mapping authenticated NETCONF client certificates 109 to usernames . . . . . . . . . . . . . . . . . . . . . . 36 110 5.5. Support both listening for connections and call home . . 37 111 5.6. For Call Home connections . . . . . . . . . . . . . . . . 37 112 5.6.1. Support more than one NETCONF client . . . . . . . . 37 113 5.6.2. Support NETCONF clients having more than one endpoint 37 114 5.6.3. Support a reconnection strategy . . . . . . . . . . . 37 115 5.6.4. Support both persistent and periodic connections . . 38 116 5.6.5. Reconnection strategy for periodic connections . . . 38 117 5.6.6. Keep-alives for persistent connections . . . . . . . 38 118 5.6.7. Customizations for periodic connections . . . . . . . 38 119 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 120 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 121 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 39 122 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 40 123 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 124 8.1. Normative References . . . . . . . . . . . . . . . . . . 40 125 8.2. Informative References . . . . . . . . . . . . . . . . . 41 126 Appendix A. Expanded Tree Diagrams . . . . . . . . . . . . . . . 43 127 A.1. Expanded Tree Diagram for 'ietf-netconf-client' . . . . . 43 128 A.2. Expanded Tree Diagram for 'ietf-netconf-server' . . . . . 52 129 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 61 130 B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 61 131 B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 61 132 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 62 133 B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 62 134 B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 62 135 B.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 62 136 B.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 62 137 B.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 63 138 B.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 63 139 B.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 63 140 B.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 63 141 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 63 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 64 144 1. Introduction 146 This document defines two YANG [RFC7950] modules, one module to 147 configure a NETCONF [RFC6241] client and the other module to 148 configure a NETCONF server. Both modules support both NETCONF over 149 SSH [RFC6242] and NETCONF over TLS [RFC7589] and NETCONF Call Home 150 connections [RFC8071]. 152 2. Terminology 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 156 "OPTIONAL" in this document are to be interpreted as described in BCP 157 14 [RFC2119] [RFC8174] when, and only when, they appear in all 158 capitals, as shown here. 160 3. The NETCONF Client Model 162 The NETCONF client model presented in this section supports both 163 clients initiating connections to servers, as well as clients 164 listening for connections from servers calling home, using either the 165 SSH and TLS transport protocols. 167 YANG feature statements are used to enable implementations to 168 advertise which potentially uncommon parts of the model the NETCONF 169 client supports. 171 3.1. Tree Diagram 173 The following tree diagram [RFC8340] provides an overview of the data 174 model for the "ietf-netconf-client" module. 176 This tree diagram only shows the nodes defined in this module; it 177 does show the nodes defined by "grouping" statements used by this 178 module. 180 Please see Appendix A.1 for a tree diagram that illustrates what the 181 module looks like with all the "grouping" statements expanded. 183 module: ietf-netconf-client 184 +--rw netconf-client 185 +---u netconf-client-grouping 187 grouping netconf-client-grouping 188 +-- initiate! {initiate}? 189 | +-- netconf-server* [name] 190 | +-- name? string 191 | +-- endpoints 192 | | +-- endpoint* [name] 193 | | +-- name? string 194 | | +-- (transport) 195 | | +--:(ssh) {ssh-initiate}? 196 | | | +-- ssh 197 | | | +---u netconf-client-grouping 198 | | +--:(tls) {tls-initiate}? 199 | | +-- tls 200 | | +---u netconf-client-grouping 201 | +-- connection-type 202 | | +-- (connection-type) 203 | | +--:(persistent-connection) 204 | | | +-- persistent! 205 | | +--:(periodic-connection) 206 | | +-- periodic! 207 | | +-- period? uint16 208 | | +-- anchor-time? yang:date-and-time 209 | | +-- idle-timeout? uint16 210 | +-- reconnect-strategy 211 | +-- start-with? enumeration 212 | +-- max-attempts? uint8 213 +-- listen! {listen}? 214 +-- idle-timeout? uint16 215 +-- endpoint* [name] 216 +-- name? string 217 +-- (transport) 218 +--:(ssh) {ssh-listen}? 219 | +-- ssh 220 | +---u netconf-client-grouping 221 +--:(tls) {tls-listen}? 222 +-- tls 223 +---u netconf-client-grouping 225 3.2. Example Usage 227 The following example illustrates configuring a NETCONF client to 228 initiate connections, using both the SSH and TLS transport protocols, 229 as well as listening for call-home connections, again using both the 230 SSH and TLS transport protocols. 232 This example is consistent with the examples presented in Section 3.2 233 of [I-D.ietf-netconf-keystore]. 235 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 237 240 241 242 243 corp-fw1 244 245 246 corp-fw1.example.com 247 248 249 corp-fw1.example.com 250 251 15 252 3 253 30 254 255 256 257 258 foobar 259 260 261 ct:rsa2048 263 base64encodedvalue== 264 base64encodedvalue== 265 266 267 268 269 explicitly-trusted-server-ca-certs<\ 270 /pinned-ca-certs> 271 explicitly-trusted-server-certs\ 272 273 274 275 30 276 3 277 278 279 281 282 283 corp-fw2.example.com 284 285 286 corp-fw2.example.com 287 288 15 289 3 290 30 291 292 293 294 295 foobar 296 297 298 ct:rsa2048 300 base64encodedvalue== 301 base64encodedvalue== 302 303 304 305 306 explicitly-trusted-server-ca-certs<\ 307 /pinned-ca-certs> 308 explicitly-trusted-server-certs\ 309 310 311 312 30 313 3 314 315 316 317 318 319 320 321 322 323 last-connected 324 325 326 328 329 330 331 Intranet-facing listener 332 333 334 192.0.2.7 335 336 337 338 foobar 339 340 341 ct:rsa2048 343 base64encodedvalue== 344 base64encodedvalue== 345 346 347 348 349 explicitly-trusted-server-ca-certs 351 explicitly-trusted-server-certs 353 explicitly-trusted-ssh-host-keys 355 356 357 358 359 360 362 3.3. YANG Module 364 This YANG module has normative references to [RFC6242], [RFC6991], 365 [RFC7589], [RFC8071], [I-D.kwatsen-netconf-tcp-client-server], 366 [I-D.ietf-netconf-ssh-client-server], and 367 [I-D.ietf-netconf-tls-client-server]. 369 file "ietf-netconf-client@2019-04-07.yang" 370 module ietf-netconf-client { 371 yang-version 1.1; 372 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-client"; 373 prefix ncc; 375 import ietf-yang-types { 376 prefix yang; 377 reference 378 "RFC 6991: Common YANG Data Types"; 379 } 381 import ietf-tcp-client { 382 prefix tcpc; 383 reference 384 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 385 } 386 import ietf-tcp-server { 387 prefix tcps; 388 reference 389 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 390 } 392 import ietf-ssh-client { 393 prefix sshc; 394 revision-date 2019-04-07; // stable grouping definitions 395 reference 396 "RFC BBBB: YANG Groupings for SSH Clients and SSH Servers"; 397 } 399 import ietf-tls-client { 400 prefix tlsc; 401 revision-date 2019-04-07; // stable grouping definitions 402 reference 403 "RFC CCCC: YANG Groupings for TLS Clients and TLS Servers"; 404 } 406 organization 407 "IETF NETCONF (Network Configuration) Working Group"; 409 contact 410 "WG Web: 411 WG List: 412 Author: Kent Watsen 413 Author: Gary Wu "; 415 description 416 "This module contains a collection of YANG definitions 417 for configuring NETCONF clients. 419 Copyright (c) 2019 IETF Trust and the persons identified 420 as authors of the code. All rights reserved. 422 Redistribution and use in source and binary forms, with 423 or without modification, is permitted pursuant to, and 424 subject to the license terms contained in, the Simplified 425 BSD License set forth in Section 4.c of the IETF Trust's 426 Legal Provisions Relating to IETF Documents 427 (https://trustee.ietf.org/license-info). 429 This version of this YANG module is part of RFC XXXX 430 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 431 itself for full legal notices.; 433 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 434 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 435 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 436 are to be interpreted as described in BCP 14 (RFC 2119) 437 (RFC 8174) when, and only when, they appear in all 438 capitals, as shown here."; 440 revision 2019-04-07 { 441 description 442 "Initial version"; 443 reference 444 "RFC XXXX: NETCONF Client and Server Models"; 445 } 447 // Features 449 feature initiate { 450 description 451 "The 'initiate' feature indicates that the NETCONF client 452 supports initiating NETCONF connections to NETCONF servers 453 using at least one transport (e.g., SSH, TLS, etc.)."; 454 } 456 feature ssh-initiate { 457 description 458 "The 'ssh-initiate' feature indicates that the NETCONF client 459 supports initiating SSH connections to NETCONF servers."; 460 reference 461 "RFC 6242: 462 Using the NETCONF Protocol over Secure Shell (SSH)"; 463 } 465 feature tls-initiate { 466 description 467 "The 'tls-initiate' feature indicates that the NETCONF client 468 supports initiating TLS connections to NETCONF servers."; 469 reference 470 "RFC 7589: Using the NETCONF Protocol over Transport 471 Layer Security (TLS) with Mutual X.509 Authentication"; 472 } 473 feature listen { 474 description 475 "The 'listen' feature indicates that the NETCONF client 476 supports opening a port to accept NETCONF server call 477 home connections using at least one transport (e.g., 478 SSH, TLS, etc.)."; 479 } 481 feature ssh-listen { 482 description 483 "The 'ssh-listen' feature indicates that the NETCONF client 484 supports opening a port to listen for incoming NETCONF 485 server call-home SSH connections."; 486 reference 487 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 488 } 490 feature tls-listen { 491 description 492 "The 'tls-listen' feature indicates that the NETCONF client 493 supports opening a port to listen for incoming NETCONF 494 server call-home TLS connections."; 495 reference 496 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 497 } 499 // Groupings 501 grouping netconf-client-grouping { 502 description 503 "Top-level grouping for NETCONF client configuration."; 504 container initiate { 505 if-feature "initiate"; 506 presence "Enables client to initiate TCP connections"; 507 description 508 "Configures client initiating underlying TCP connections."; 509 list netconf-server { 510 key "name"; 511 min-elements 1; 512 description 513 "List of NETCONF servers the NETCONF client is to 514 initiate connections to in parallel."; 515 leaf name { 516 type string; 517 description 518 "An arbitrary name for the NETCONF server."; 519 } 520 container endpoints { 521 description 522 "Container for the list of endpoints."; 523 list endpoint { 524 key "name"; 525 min-elements 1; 526 ordered-by user; 527 description 528 "A user-ordered list of endpoints that the NETCONF 529 client will attempt to connect to in the specified 530 sequence. Defining more than one enables 531 high-availability."; 532 leaf name { 533 type string; 534 description 535 "An arbitrary name for the endpoint."; 536 } 537 choice transport { 538 mandatory true; 539 description 540 "Selects between available transports."; 541 case ssh { 542 if-feature "ssh-initiate"; 543 container ssh { 544 description 545 "Specifies IP and SSH specific configuration 546 for the connection."; 547 uses tcpc:tcp-client-grouping { 548 refine "tcp-client-parameters/remote-port" { 549 default "830"; 550 description 551 "The NETCONF client will attempt to connect 552 to the IANA-assigned well-known port value 553 for 'netconf-ssh' (443) if no value is 554 specified."; 555 } 556 } 557 uses sshc:ssh-client-grouping; 558 } 559 } 560 case tls { 561 if-feature "tls-initiate"; 562 container tls { 563 description 564 "Specifies IP and TLS specific configuration 565 for the connection."; 566 uses tcpc:tcp-client-grouping { 567 refine "tcp-client-parameters/remote-port" { 568 default "6513"; 569 description 570 "The NETCONF client will attempt to connect 571 to the IANA-assigned well-known port value 572 for 'netconf-tls' (6513) if no value is 573 specified."; 574 } 575 } 576 uses tlsc:tls-client-grouping { 577 refine "tls-client-parameters/client-identity" 578 + "/auth-type" { 579 mandatory true; 580 description 581 "NETCONF/TLS clients MUST pass some 582 authentication credentials."; 583 } 584 } 585 } 586 } 587 } // choice transport 588 } // list endpoint 589 } // container endpoints 591 container connection-type { 592 description 593 "Indicates the NETCONF client's preference for how the 594 NETCONF connection is maintained."; 595 choice connection-type { 596 mandatory true; 597 description 598 "Selects between available connection types."; 599 case persistent-connection { 600 container persistent { 601 presence "Indicates that a persistent connection is 602 to be maintained."; 603 description 604 "Maintain a persistent connection to the NETCONF 605 server. If the connection goes down, immediately 606 start trying to reconnect to it, using the 607 reconnection strategy. 609 This connection type minimizes any NETCONF server 610 to NETCONF client data-transfer delay, albeit at 611 the expense of holding resources longer."; 612 } 613 } 614 case periodic-connection { 615 container periodic { 616 must 'not (../../endpoints/endpoint/ssh/' 617 + 'tcp-client-parameters/keepalives ' 618 + 'or ../../endpoints/endpoint/ssh/' 619 + 'ssh-client-parameters/keepalives ' 620 + 'or ../../endpoints/endpoint/tls/' 621 + 'tcp-client-parameters/keepalives ' 622 + 'or ../../endpoints/endpoint/tls/' 623 + 'tls-client-parameters/keepalives)'; 624 presence "Indicates that a periodic connection is 625 to be maintained."; 626 description 627 "Periodically connect to the NETCONF server. The 628 NETCONF server should close the connection upon 629 completing planned activities. 631 This connection type increases resource 632 utilization, albeit with increased delay in 633 NETCONF server to NETCONF client interactions."; 634 leaf period { 635 type uint16; 636 units "minutes"; 637 default "60"; 638 description 639 "Duration of time between periodic connections."; 640 } 641 leaf anchor-time { 642 type yang:date-and-time { 643 // constrained to minute-level granularity 644 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 645 + '(Z|[\+\-]\d{2}:\d{2})'; 646 } 647 description 648 "Designates a timestamp before or after which a 649 series of periodic connections are determined. 650 The periodic connections occur at a whole 651 multiple interval from the anchor time. For 652 example, for an anchor time is 15 minutes past 653 midnight and a period interval of 24 hours, then 654 a periodic connection will occur 15 minutes past 655 midnight everyday."; 656 } 657 leaf idle-timeout { 658 type uint16; 659 units "seconds"; 660 default 120; // two minutes 661 description 662 "Specifies the maximum number of seconds that 663 a NETCONF session may remain idle. A NETCONF 664 session will be dropped if it is idle for an 665 interval longer than this number of seconds. 666 If set to zero, then the NETCONF client will 667 never drop a session because it is idle."; 668 } 669 } 670 } 671 } 672 } 673 container reconnect-strategy { 674 description 675 "The reconnection strategy directs how a NETCONF client 676 reconnects to a NETCONF server, after discovering its 677 connection to the server has dropped, even if due to a 678 reboot. The NETCONF client starts with the specified 679 endpoint and tries to connect to it max-attempts times 680 before trying the next endpoint in the list (round 681 robin)."; 682 leaf start-with { 683 type enumeration { 684 enum first-listed { 685 description 686 "Indicates that reconnections should start with 687 the first endpoint listed."; 688 } 689 enum last-connected { 690 description 691 "Indicates that reconnections should start with 692 the endpoint last connected to. If no previous 693 connection has ever been established, then the 694 first endpoint configured is used. NETCONF 695 clients SHOULD be able to remember the last 696 endpoint connected to across reboots."; 697 } 698 enum random-selection { 699 description 700 "Indicates that reconnections should start with 701 a random endpoint."; 702 } 703 } 704 default "first-listed"; 705 description 706 "Specifies which of the NETCONF server's endpoints 707 the NETCONF client should start with when trying 708 to connect to the NETCONF server."; 709 } 710 leaf max-attempts { 711 type uint8 { 712 range "1..max"; 714 } 715 default "3"; 716 description 717 "Specifies the number times the NETCONF client tries 718 to connect to a specific endpoint before moving on 719 to the next endpoint in the list (round robin)."; 720 } 721 } 722 } // netconf-server 723 } // initiate 725 container listen { 726 if-feature "listen"; 727 presence "Enables client to accept call-home connections"; 728 description 729 "Configures client accepting call-home TCP connections."; 730 leaf idle-timeout { 731 type uint16; 732 units "seconds"; 733 default "3600"; // one hour 734 description 735 "Specifies the maximum number of seconds that a NETCONF 736 session may remain idle. A NETCONF session will be 737 dropped if it is idle for an interval longer than this 738 number of seconds. If set to zero, then the server 739 will never drop a session because it is idle. Sessions 740 that have a notification subscription active are never 741 dropped."; 742 } 743 list endpoint { 744 key "name"; 745 min-elements 1; 746 description 747 "List of endpoints to listen for NETCONF connections."; 748 leaf name { 749 type string; 750 description 751 "An arbitrary name for the NETCONF listen endpoint."; 752 } 753 choice transport { 754 mandatory true; 755 description 756 "Selects between available transports."; 757 case ssh { 758 if-feature "ssh-listen"; 759 container ssh { 760 description 761 "SSH-specific listening configuration for inbound 762 connections."; 763 uses tcps:tcp-server-grouping { 764 refine "tcp-server-parameters/local-port" { 765 default "4334"; 766 description 767 "The NETCONF client will listen on the IANA- 768 assigned well-known port for 'netconf-ch-ssh' 769 (4334) if no value is specified."; 770 } 771 } 772 uses sshc:ssh-client-grouping; 773 } 774 } 775 case tls { 776 if-feature "tls-listen"; 777 container tls { 778 description 779 "TLS-specific listening configuration for inbound 780 connections."; 781 uses tcps:tcp-server-grouping { 782 refine "tcp-server-parameters/local-port" { 783 default "4334"; 784 description 785 "The NETCONF client will listen on the IANA- 786 assigned well-known port for 'netconf-ch-ssh' 787 (4334) if no value is specified."; 788 } 789 } 790 uses tlsc:tls-client-grouping { 791 refine 792 "tls-client-parameters/client-identity/auth-type" { 793 mandatory true; 794 description 795 "NETCONF/TLS clients MUST pass some 796 authentication credentials."; 797 } 798 } 799 } 800 } 801 } // transport 802 } // endpoint 803 } // listen 804 } // netconf-client 806 // Protocol accessible node, for servers that implement this 807 // module. 809 container netconf-client { 810 uses netconf-client-grouping; 811 description 812 "Top-level container for NETCONF client configuration."; 813 } 814 } 815 817 4. The NETCONF Server Model 819 The NETCONF server model presented in this section supports both 820 listening for connections as well as initiating call-home 821 connections, using either the SSH and TLS transport protocols. 823 YANG feature statements are used to enable implementations to 824 advertise which potentially uncommon parts of the model the NETCONF 825 server supports. 827 4.1. Tree Diagram 829 The following tree diagram [RFC8340] provides an overview of the data 830 model for the "ietf-netconf-server" module. 832 This tree diagram only shows the nodes defined in this module; it 833 does show the nodes defined by "grouping" statements used by this 834 module. 836 Please see Appendix A.2 for a tree diagram that illustrates what the 837 module looks like with all the "grouping" statements expanded. 839 module: ietf-netconf-server 840 +--rw netconf-server 841 +---u netconf-server-grouping 843 grouping netconf-server-grouping 844 +-- listen! {listen}? 845 | +-- idle-timeout? uint16 846 | +-- endpoint* [name] 847 | +-- name? string 848 | +-- (transport) 849 | +--:(ssh) {ssh-listen}? 850 | | +-- ssh 851 | | +---u netconf-server-grouping 852 | +--:(tls) {tls-listen}? 853 | +-- tls 854 | +---u netconf-server-grouping 855 +-- call-home! {call-home}? 856 +-- netconf-client* [name] 857 +-- name? string 858 +-- endpoints 859 | +-- endpoint* [name] 860 | +-- name? string 861 | +-- (transport) 862 | +--:(ssh) {ssh-call-home}? 863 | | +-- ssh 864 | | +---u netconf-server-grouping 865 | +--:(tls) {tls-call-home}? 866 | +-- tls 867 | +---u netconf-server-grouping 868 +-- connection-type 869 | +-- (connection-type) 870 | +--:(persistent-connection) 871 | | +-- persistent! 872 | +--:(periodic-connection) 873 | +-- periodic! 874 | +-- period? uint16 875 | +-- anchor-time? yang:date-and-time 876 | +-- idle-timeout? uint16 877 +-- reconnect-strategy 878 +-- start-with? enumeration 879 +-- max-attempts? uint8 881 4.2. Example Usage 883 The following example illustrates configuring a NETCONF server to 884 listen for NETCONF client connections using both the SSH and TLS 885 transport protocols, as well as configuring call-home to two NETCONF 886 clients, one using SSH and the other using TLS. 888 This example is consistent with the examples presented in Section 3.2 889 of [I-D.ietf-netconf-keystore]. 891 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 893 897 898 899 900 netconf/ssh 901 902 903 192.0.2.7 904 905 906 907 908 deployment-specific-certificate 909 910 911 ct:rsa2048 913 base64encodedvalue== 914 base64encodedvalue== 915 916 917 918 919 920 explicitly-trusted-client-ca-certs 922 explicitly-trusted-client-certs 924 925 926 927 928 929 netconf/tls 930 931 932 192.0.2.7 933 934 935 936 937 ct:rsa2048 939 base64encodedvalue== 940 base64encodedvalue== 941 base64encodedvalue== 942 943 944 945 explicitly-trusted-client-ca-certs 947 explicitly-trusted-client-certs 949 950 951 1 952 11:0A:05:11:00 953 x509c2n:san-any 954 955 956 2 957 B3:4F:A1:8C:54 958 x509c2n:specified 959 scooby-doo 960 961 962 963 964 965 966 968 969 970 971 config-mgr 972 973 974 east-data-center 975 976 977 east.config-mgr.example.com 979 980 981 982 983 deployment-specific-certificate 984 985 986 ct:rsa2048 988 base64encodedvalue== 989 base64encodedvalue== 990 991 992 993 994 995 explicitly-trusted-client-ca-certs<\ 996 /pinned-ca-certs> 997 explicitly-trusted-client-certs\ 998 999 1000 1001 1002 1003 1004 west-data-center 1005 1006 1007 west.config-mgr.example.com 1009 1010 1011 1012 1013 deployment-specific-certificate 1014 1015 1016 ct:rsa2048 1018 base64encodedvalue== 1019 base64encodedvalue== 1020 1021 1022 1023 1024 1025 explicitly-trusted-client-ca-certs<\ 1026 /pinned-ca-certs> 1027 explicitly-trusted-client-certs\ 1028 1029 1030 1031 1033 1034 1035 1036 1037 300 1038 60 1039 1040 1041 1042 last-connected 1043 3 1044 1045 1046 1047 data-collector 1048 1049 1050 east-data-center 1051 1052 1053 east.analytics.example.com 1055 1056 15 1057 3 1058 30 1059 1060 1061 1062 1063 1064 ct:rsa2048 1066 base64encodedvalue== 1067 base64encodedvalue== 1068 base64encodedvalue== 1069 1070 1071 1072 explicitly-trusted-client-ca-certs<\ 1073 /pinned-ca-certs> 1074 explicitly-trusted-client-certs\ 1075 1076 1077 1078 1 1079 11:0A:05:11:00 1080 x509c2n:san-any 1082 1083 1084 2 1085 B3:4F:A1:8C:54 1086 x509c2n:specified 1087 scooby-doo 1088 1089 1090 1091 1092 30 1093 3 1094 1095 1096 1097 1098 1099 west-data-center 1100 1101 1102 west.analytics.example.com 1104 1105 15 1106 3 1107 30 1108 1109 1110 1111 1112 1113 ct:rsa2048 1115 base64encodedvalue== 1116 base64encodedvalue== 1117 base64encodedvalue== 1118 1119 1120 1121 explicitly-trusted-client-ca-certs<\ 1122 /pinned-ca-certs> 1123 explicitly-trusted-client-certs\ 1124 1125 1126 1127 1 1128 11:0A:05:11:00 1129 x509c2n:san-any 1131 1132 1133 2 1134 B3:4F:A1:8C:54 1135 x509c2n:specified 1136 scooby-doo 1137 1138 1139 1140 1141 30 1142 3 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 first-listed 1153 3 1154 1155 1156 1157 1159 4.3. YANG Module 1161 This YANG module has normative references to [RFC6242], [RFC6991], 1162 [RFC7407], [RFC7589], [RFC8071], 1163 [I-D.kwatsen-netconf-tcp-client-server], 1164 [I-D.ietf-netconf-ssh-client-server], and 1165 [I-D.ietf-netconf-tls-client-server]. 1167 file "ietf-netconf-server@2019-04-07.yang" 1168 module ietf-netconf-server { 1169 yang-version 1.1; 1170 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server"; 1171 prefix ncs; 1173 import ietf-yang-types { 1174 prefix yang; 1175 reference 1176 "RFC 6991: Common YANG Data Types"; 1177 } 1178 import ietf-x509-cert-to-name { 1179 prefix x509c2n; 1180 reference 1181 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1182 } 1184 import ietf-tcp-client { 1185 prefix tcpc; 1186 reference 1187 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1188 } 1190 import ietf-tcp-server { 1191 prefix tcps; 1192 reference 1193 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1194 } 1196 import ietf-ssh-server { 1197 prefix sshs; 1198 revision-date 2019-04-07; // stable grouping definitions 1199 reference 1200 "RFC BBBB: YANG Groupings for SSH Clients and SSH Servers"; 1201 } 1203 import ietf-tls-server { 1204 prefix tlss; 1205 revision-date 2019-04-07; // stable grouping definitions 1206 reference 1207 "RFC CCCC: YANG Groupings for TLS Clients and TLS Servers"; 1208 } 1210 organization 1211 "IETF NETCONF (Network Configuration) Working Group"; 1213 contact 1214 "WG Web: 1215 WG List: 1216 Author: Kent Watsen 1217 Author: Gary Wu 1218 Author: Juergen Schoenwaelder 1219 "; 1220 description 1221 "This module contains a collection of YANG definitions 1222 for configuring NETCONF servers. 1224 Copyright (c) 2019 IETF Trust and the persons identified 1225 as authors of the code. All rights reserved. 1227 Redistribution and use in source and binary forms, with 1228 or without modification, is permitted pursuant to, and 1229 subject to the license terms contained in, the Simplified 1230 BSD License set forth in Section 4.c of the IETF Trust's 1231 Legal Provisions Relating to IETF Documents 1232 (https://trustee.ietf.org/license-info). 1234 This version of this YANG module is part of RFC XXXX 1235 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 1236 itself for full legal notices.; 1238 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1239 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1240 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1241 are to be interpreted as described in BCP 14 (RFC 2119) 1242 (RFC 8174) when, and only when, they appear in all 1243 capitals, as shown here."; 1245 revision 2019-04-07 { 1246 description 1247 "Initial version"; 1248 reference 1249 "RFC XXXX: NETCONF Client and Server Models"; 1250 } 1252 // Features 1254 feature listen { 1255 description 1256 "The 'listen' feature indicates that the NETCONF server 1257 supports opening a port to accept NETCONF client connections 1258 using at least one transport (e.g., SSH, TLS, etc.)."; 1259 } 1261 feature ssh-listen { 1262 description 1263 "The 'ssh-listen' feature indicates that the NETCONF server 1264 supports opening a port to accept NETCONF over SSH 1265 client connections."; 1266 reference 1267 "RFC 6242: 1268 Using the NETCONF Protocol over Secure Shell (SSH)"; 1269 } 1271 feature tls-listen { 1272 description 1273 "The 'tls-listen' feature indicates that the NETCONF server 1274 supports opening a port to accept NETCONF over TLS 1275 client connections."; 1276 reference 1277 "RFC 7589: Using the NETCONF Protocol over Transport 1278 Layer Security (TLS) with Mutual X.509 1279 Authentication"; 1280 } 1282 feature call-home { 1283 description 1284 "The 'call-home' feature indicates that the NETCONF server 1285 supports initiating NETCONF call home connections to 1286 NETCONF clients using at least one transport (e.g., SSH, 1287 TLS, etc.)."; 1288 reference 1289 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1290 } 1292 feature ssh-call-home { 1293 description 1294 "The 'ssh-call-home' feature indicates that the NETCONF 1295 server supports initiating a NETCONF over SSH call 1296 home connection to NETCONF clients."; 1297 reference 1298 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1299 } 1301 feature tls-call-home { 1302 description 1303 "The 'tls-call-home' feature indicates that the NETCONF 1304 server supports initiating a NETCONF over TLS call 1305 home connection to NETCONF clients."; 1306 reference 1307 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1308 } 1310 // Groupings 1312 grouping netconf-server-grouping { 1313 description 1314 "Top-level grouping for NETCONF server configuration."; 1315 container listen { 1316 if-feature "listen"; 1317 presence "Enables server to listen for TCP connections"; 1318 description 1319 "Configures listen behavior"; 1320 leaf idle-timeout { 1321 type uint16; 1322 units "seconds"; 1323 default 3600; // one hour 1324 description 1325 "Specifies the maximum number of seconds that a NETCONF 1326 session may remain idle. A NETCONF session will be 1327 dropped if it is idle for an interval longer than this 1328 number of seconds. If set to zero, then the server 1329 will never drop a session because it is idle. Sessions 1330 that have a notification subscription active are never 1331 dropped."; 1332 } 1333 list endpoint { 1334 key "name"; 1335 min-elements 1; 1336 description 1337 "List of endpoints to listen for NETCONF connections."; 1338 leaf name { 1339 type string; 1340 description 1341 "An arbitrary name for the NETCONF listen endpoint."; 1342 } 1343 choice transport { 1344 mandatory true; 1345 description 1346 "Selects between available transports."; 1347 case ssh { 1348 if-feature "ssh-listen"; 1349 container ssh { 1350 description 1351 "SSH-specific listening configuration for inbound 1352 connections."; 1353 uses tcps:tcp-server-grouping { 1354 refine "tcp-server-parameters/local-port" { 1355 default "830"; 1356 description 1357 "The NETCONF server will listen on the IANA- 1358 assigned well-known port value for 'netconf-ssh' 1359 (830) if no value is specified."; 1360 } 1361 } 1362 uses sshs:ssh-server-grouping; 1363 } 1364 } 1365 case tls { 1366 if-feature "tls-listen"; 1367 container tls { 1368 description 1369 "TLS-specific listening configuration for inbound 1370 connections."; 1372 uses tcps:tcp-server-grouping { 1373 refine "tcp-server-parameters/local-port" { 1374 default "6513"; 1375 description 1376 "The NETCONF server will listen on the IANA- 1377 assigned well-known port value for 'netconf-tls' 1378 (6513) if no value is specified."; 1379 } 1380 } 1381 uses tlss:tls-server-grouping { 1382 refine 1383 "tls-server-parameters/client-authentication" { 1384 must 'pinned-ca-certs or pinned-client-certs'; 1385 description 1386 "NETCONF/TLS servers MUST validate client 1387 certiticates."; 1388 } 1389 augment 1390 "tls-server-parameters/client-authentication" { 1391 description 1392 "Augments in the cert-to-name structure."; 1393 container cert-maps { 1394 uses x509c2n:cert-to-name; 1395 description 1396 "The cert-maps container is used by a TLS- 1397 based NETCONF server to map the NETCONF 1398 client's presented X.509 certificate to a 1399 NETCONF username. If no matching and valid 1400 cert-to-name list entry can be found, then 1401 the NETCONF server MUST close the connection, 1402 and MUST NOT accept NETCONF messages over 1403 it."; 1404 reference 1405 "RFC WWWW: NETCONF over TLS, Section 7"; 1406 } 1407 } 1408 } 1409 } 1410 } 1411 } 1412 } 1413 } 1414 container call-home { 1415 if-feature "call-home"; 1416 presence "Enables server to initiate TCP connections"; 1417 description "Configures call-home behavior"; 1418 list netconf-client { 1419 key "name"; 1420 min-elements 1; 1421 description 1422 "List of NETCONF clients the NETCONF server is to 1423 initiate call-home connections to in parallel."; 1424 leaf name { 1425 type string; 1426 description 1427 "An arbitrary name for the remote NETCONF client."; 1428 } 1429 container endpoints { 1430 description 1431 "Container for the list of endpoints."; 1432 list endpoint { 1433 key "name"; 1434 min-elements 1; 1435 ordered-by user; 1436 description 1437 "A non-empty user-ordered list of endpoints for this 1438 NETCONF server to try to connect to in sequence. 1439 Defining more than one enables high-availability."; 1440 leaf name { 1441 type string; 1442 description 1443 "An arbitrary name for this endpoint."; 1444 } 1445 choice transport { 1446 mandatory true; 1447 description 1448 "Selects between available transports."; 1449 case ssh { 1450 if-feature "ssh-call-home"; 1451 container ssh { 1452 description 1453 "Specifies SSH-specific call-home transport 1454 configuration."; 1455 uses tcpc:tcp-client-grouping { 1456 refine "tcp-client-parameters/remote-port" { 1457 default "4334"; 1458 description 1459 "The NETCONF server will attempt to connect 1460 to the IANA-assigned well-known port for 1461 'netconf-ch-tls' (4334) if no value is 1462 specified."; 1463 } 1464 } 1465 uses sshs:ssh-server-grouping; 1466 } 1467 } 1468 case tls { 1469 if-feature "tls-call-home"; 1470 container tls { 1471 description 1472 "Specifies TLS-specific call-home transport 1473 configuration."; 1474 uses tcpc:tcp-client-grouping { 1475 refine "tcp-client-parameters/remote-port" { 1476 default "4335"; 1477 description 1478 "The NETCONF server will attempt to connect 1479 to the IANA-assigned well-known port for 1480 'netconf-ch-tls' (4335) if no value is 1481 specified."; 1482 } 1483 } 1484 uses tlss:tls-server-grouping { 1485 refine 1486 "tls-server-parameters/client-authentication" { 1487 must 'pinned-ca-certs or pinned-client-certs'; 1488 description 1489 "NETCONF/TLS servers MUST validate client 1490 certiticates."; 1491 } 1492 augment 1493 "tls-server-parameters/client-authentication" { 1494 description 1495 "Augments in the cert-to-name structure."; 1496 container cert-maps { 1497 uses x509c2n:cert-to-name; 1498 description 1499 "The cert-maps container is used by a 1500 TLS-based NETCONF server to map the 1501 NETCONF client's presented X.509 1502 certificate to a NETCONF username. If 1503 no matching and valid cert-to-name list 1504 entry can be found, then the NETCONF 1505 server MUST close the connection, and 1506 MUST NOT accept NETCONF messages over 1507 it."; 1508 reference 1509 "RFC WWWW: NETCONF over TLS, Section 7"; 1510 } 1511 } 1512 } 1513 } 1514 } // tls 1515 } // choice 1517 } // endpoint 1518 } // endpoints 1519 container connection-type { 1520 description 1521 "Indicates the NETCONF server's preference for how the 1522 NETCONF connection is maintained."; 1523 choice connection-type { 1524 mandatory true; 1525 description 1526 "Selects between available connection types."; 1527 case persistent-connection { 1528 container persistent { 1529 presence "Indicates that a persistent connection is 1530 to be maintained."; 1531 description 1532 "Maintain a persistent connection to the NETCONF 1533 client. If the connection goes down, immediately 1534 start trying to reconnect to it, using the 1535 reconnection strategy. 1537 This connection type minimizes any NETCONF client 1538 to NETCONF server data-transfer delay, albeit at 1539 the expense of holding resources longer."; 1540 } // container persistent 1541 } // case persistent-connection 1542 case periodic-connection { 1543 container periodic { 1544 must 'not (../../endpoints/endpoint/ssh/' 1545 + 'tcp-client-parameters/keepalives ' 1546 + 'or ../../endpoints/endpoint/ssh/' 1547 + 'ssh-server-parameters/keepalives ' 1548 + 'or ../../endpoints/endpoint/tls/' 1549 + 'tcp-client-parameters/keepalives ' 1550 + 'or ../../endpoints/endpoint/tls/' 1551 + 'tls-server-parameters/keepalives)'; 1552 presence "Indicates that a periodic connection is 1553 to be maintained."; 1554 description 1555 "Periodically connect to the NETCONF client. The 1556 NETCONF client should close the underlying TLS 1557 connection upon completing planned activities. 1559 This connection type increases resource 1560 utilization, albeit with increased delay in 1561 NETCONF client to NETCONF client interactions."; 1562 leaf period { 1563 type uint16; 1564 units "minutes"; 1565 default "60"; 1566 description 1567 "Duration of time between periodic connections."; 1568 } 1569 leaf anchor-time { 1570 type yang:date-and-time { 1571 // constrained to minute-level granularity 1572 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1573 + '(Z|[\+\-]\d{2}:\d{2})'; 1574 } 1575 description 1576 "Designates a timestamp before or after which a 1577 series of periodic connections are determined. 1578 The periodic connections occur at a whole 1579 multiple interval from the anchor time. For 1580 example, for an anchor time is 15 minutes past 1581 midnight and a period interval of 24 hours, then 1582 a periodic connection will occur 15 minutes past 1583 midnight everyday."; 1584 } 1585 leaf idle-timeout { 1586 type uint16; 1587 units "seconds"; 1588 default 120; // two minutes 1589 description 1590 "Specifies the maximum number of seconds that 1591 a NETCONF session may remain idle. A NETCONF 1592 session will be dropped if it is idle for an 1593 interval longer than this number of seconds. 1594 If set to zero, then the server will never 1595 drop a session because it is idle."; 1596 } 1597 } // container periodic 1598 } // case periodic-connection 1599 } // choice connection-type 1600 } // container connection-type 1601 container reconnect-strategy { 1602 description 1603 "The reconnection strategy directs how a NETCONF server 1604 reconnects to a NETCONF client, after discovering its 1605 connection to the client has dropped, even if due to a 1606 reboot. The NETCONF server starts with the specified 1607 endpoint and tries to connect to it max-attempts times 1608 before trying the next endpoint in the list (round 1609 robin)."; 1610 leaf start-with { 1611 type enumeration { 1612 enum first-listed { 1613 description 1614 "Indicates that reconnections should start with 1615 the first endpoint listed."; 1616 } 1617 enum last-connected { 1618 description 1619 "Indicates that reconnections should start with 1620 the endpoint last connected to. If no previous 1621 connection has ever been established, then the 1622 first endpoint configured is used. NETCONF 1623 servers SHOULD be able to remember the last 1624 endpoint connected to across reboots."; 1625 } 1626 enum random-selection { 1627 description 1628 "Indicates that reconnections should start with 1629 a random endpoint."; 1630 } 1631 } 1632 default "first-listed"; 1633 description 1634 "Specifies which of the NETCONF client's endpoints 1635 the NETCONF server should start with when trying 1636 to connect to the NETCONF client."; 1637 } 1638 leaf max-attempts { 1639 type uint8 { 1640 range "1..max"; 1641 } 1642 default "3"; 1643 description 1644 "Specifies the number times the NETCONF server tries 1645 to connect to a specific endpoint before moving on 1646 to the next endpoint in the list (round robin)."; 1647 } 1648 } // container reconnect-strategy 1649 } // list netconf-client 1650 } // container call-home 1651 } // grouping netconf-server-grouping 1653 // Protocol accessible node, for servers that implement this 1654 // module. 1656 container netconf-server { 1657 uses netconf-server-grouping; 1658 description 1659 "Top-level container for NETCONF server configuration."; 1660 } 1662 } 1663 1665 5. Design Considerations 1667 Editorial: this section is a hold over from before, previously called 1668 "Objectives". It was only written two support the "server" (not the 1669 "client"). The question is if it's better to add the missing 1670 "client" parts, or remove this section altogether. 1672 The primary purpose of the YANG modules defined herein is to enable 1673 the configuration of the NETCONF client and servers. This scope 1674 includes the following objectives: 1676 5.1. Support all NETCONF transports 1678 The YANG module should support all current NETCONF transports, namely 1679 NETCONF over SSH [RFC6242], NETCONF over TLS [RFC7589], and to be 1680 extensible to support future transports as necessary. 1682 Because implementations may not support all transports, the modules 1683 should use YANG "feature" statements so that implementations can 1684 accurately advertise which transports are supported. 1686 5.2. Enable each transport to select which keys to use 1688 Servers may have a multiplicity of host-keys or server-certificates 1689 from which subsets may be selected for specific uses. For instance, 1690 a NETCONF server may want to use one set of SSH host-keys when 1691 listening on port 830, and a different set of SSH host-keys when 1692 calling home. The data models provided herein should enable 1693 configuration of which keys to use on a per-use basis. 1695 5.3. Support authenticating NETCONF clients certificates 1697 When a certificate is used to authenticate a NETCONF client, there is 1698 a need to configure the server to know how to authenticate the 1699 certificates. The server should be able to authenticate the client's 1700 certificate either by using path-validation to a configured trust 1701 anchor or by matching the client-certificate to one previously 1702 configured. 1704 5.4. Support mapping authenticated NETCONF client certificates to 1705 usernames 1707 When a client certificate is used for TLS client authentication, the 1708 NETCONF server must be able to derive a username from the 1709 authenticated certificate. Thus the modules defined herein should 1710 enable this mapping to be configured. 1712 5.5. Support both listening for connections and call home 1714 The NETCONF protocols were originally defined as having the server 1715 opening a port to listen for client connections. More recently the 1716 NETCONF working group defined support for call-home ([RFC8071]), 1717 enabling the server to initiate the connection to the client. Thus 1718 the modules defined herein should enable configuration for both 1719 listening for connections and calling home. Because implementations 1720 may not support both listening for connections and calling home, YANG 1721 "feature" statements should be used so that implementation can 1722 accurately advertise the connection types it supports. 1724 5.6. For Call Home connections 1726 The following objectives only pertain to call home connections. 1728 5.6.1. Support more than one NETCONF client 1730 A NETCONF server may be managed by more than one NETCONF client. For 1731 instance, a deployment may have one client for provisioning and 1732 another for fault monitoring. Therefore, when it is desired for a 1733 server to initiate call home connections, it should be able to do so 1734 to more than one client. 1736 5.6.2. Support NETCONF clients having more than one endpoint 1738 A NETCONF client managing a NETCONF server may implement a high- 1739 availability strategy employing a multiplicity of active and/or 1740 passive endpoint. Therefore, when it is desired for a server to 1741 initiate call home connections, it should be able to connect to any 1742 of the client's endpoints. 1744 5.6.3. Support a reconnection strategy 1746 Assuming a NETCONF client has more than one endpoint, then it becomes 1747 necessary to configure how a NETCONF server should reconnect to the 1748 client should it lose its connection to one the client's endpoints. 1749 For instance, the NETCONF server may start with first endpoint 1750 defined in a user-ordered list of endpoints or with the last 1751 endpoints it was connected to. 1753 5.6.4. Support both persistent and periodic connections 1755 NETCONF clients may vary greatly on how frequently they need to 1756 interact with a NETCONF server, how responsive interactions need to 1757 be, and how many simultaneous connections they can support. Some 1758 clients may need a persistent connection to servers to optimize real- 1759 time interactions, while others prefer periodic interactions in order 1760 to minimize resource requirements. Therefore, when it is necessary 1761 for server to initiate connections, it should be configurable if the 1762 connection is persistent or periodic. 1764 5.6.5. Reconnection strategy for periodic connections 1766 The reconnection strategy should apply to both persistent and 1767 periodic connections. How it applies to periodic connections becomes 1768 clear when considering that a periodic "connection" is a logical 1769 connection to a single server. That is, the periods of 1770 unconnectedness are intentional as opposed to due to external 1771 reasons. A periodic "connection" should always reconnect to the same 1772 server until it is no longer able to, at which time the reconnection 1773 strategy guides how to connect to another server. 1775 5.6.6. Keep-alives for persistent connections 1777 If a persistent connection is desired, it is the responsibility of 1778 the connection initiator to actively test the "aliveness" of the 1779 connection. The connection initiator must immediately work to 1780 reestablish a persistent connection as soon as the connection is 1781 lost. How often the connection should be tested is driven by NETCONF 1782 client requirements, and therefore keep-alive settings should be 1783 configurable on a per-client basis. 1785 5.6.7. Customizations for periodic connections 1787 If a periodic connection is desired, it is necessary for the NETCONF 1788 server to know how often it should connect. This frequency 1789 determines the maximum amount of time a NETCONF client may have to 1790 wait to send data to a server. A server may connect to a client 1791 before this interval expires if desired (e.g., to send data to a 1792 client). 1794 6. Security Considerations 1796 The YANG module defined in this document uses groupings defined in 1797 [I-D.kwatsen-netconf-tcp-client-server], 1798 [I-D.ietf-netconf-ssh-client-server], and 1799 [I-D.ietf-netconf-tls-client-server]. Please see the Security 1800 Considerations section in those documents for concerns related those 1801 groupings. 1803 The YANG modules defined in this document are designed to be accessed 1804 via YANG based management protocols, such as NETCONF [RFC6241] and 1805 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1806 implement secure transport layers (e.g., SSH, TLS) with mutual 1807 authentication. 1809 The NETCONF access control model (NACM) [RFC8341] provides the means 1810 to restrict access for particular users to a pre-configured subset of 1811 all available protocol operations and content. 1813 There are a number of data nodes defined in the YANG modules that are 1814 writable/creatable/deletable (i.e., config true, which is the 1815 default). Some of these data nodes may be considered sensitive or 1816 vulnerable in some network environments. Write operations (e.g., 1817 edit-config) to these data nodes without proper protection can have a 1818 negative effect on network operations. These are the subtrees and 1819 data nodes and their sensitivity/vulnerability: 1821 None of the subtrees or data nodes in the modules defined in this 1822 document need to be protected from write operations. 1824 Some of the readable data nodes in the YANG modules may be considered 1825 sensitive or vulnerable in some network environments. It is thus 1826 important to control read access (e.g., via get, get-config, or 1827 notification) to these data nodes. These are the subtrees and data 1828 nodes and their sensitivity/vulnerability: 1830 None of the subtrees or data nodes in the modules defined in this 1831 document need to be protected from read operations. 1833 Some of the RPC operations in the YANG modules may be considered 1834 sensitive or vulnerable in some network environments. It is thus 1835 important to control access to these operations. These are the 1836 operations and their sensitivity/vulnerability: 1838 The modules defined in this document do not define any 'RPC' or 1839 'action' statements. 1841 7. IANA Considerations 1843 7.1. The IETF XML Registry 1845 This document registers two URIs in the "ns" subregistry of the IETF 1846 XML Registry [RFC3688]. Following the format in [RFC3688], the 1847 following registrations are requested: 1849 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-client 1850 Registrant Contact: The NETCONF WG of the IETF. 1851 XML: N/A, the requested URI is an XML namespace. 1853 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1854 Registrant Contact: The NETCONF WG of the IETF. 1855 XML: N/A, the requested URI is an XML namespace. 1857 7.2. The YANG Module Names Registry 1859 This document registers two YANG modules in the YANG Module Names 1860 registry [RFC6020]. Following the format in [RFC6020], the the 1861 following registrations are requested: 1863 name: ietf-netconf-client 1864 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-client 1865 prefix: ncc 1866 reference: RFC XXXX 1868 name: ietf-netconf-server 1869 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1870 prefix: ncs 1871 reference: RFC XXXX 1873 8. References 1875 8.1. Normative References 1877 [I-D.ietf-netconf-keystore] 1878 Watsen, K., "YANG Data Model for a Centralized Keystore 1879 Mechanism", draft-ietf-netconf-keystore-08 (work in 1880 progress), March 2019. 1882 [I-D.ietf-netconf-ssh-client-server] 1883 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for SSH 1884 Clients and SSH Servers", draft-ietf-netconf-ssh-client- 1885 server-11 (work in progress), March 2019. 1887 [I-D.ietf-netconf-tls-client-server] 1888 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for TLS 1889 Clients and TLS Servers", draft-ietf-netconf-tls-client- 1890 server-10 (work in progress), March 2019. 1892 [I-D.kwatsen-netconf-tcp-client-server] 1893 Watsen, K., "YANG Groupings for TCP Clients and TCP 1894 Servers", draft-kwatsen-netconf-tcp-client-server-00 (work 1895 in progress), March 2019. 1897 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1898 Requirement Levels", BCP 14, RFC 2119, 1899 DOI 10.17487/RFC2119, March 1997, 1900 . 1902 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1903 the Network Configuration Protocol (NETCONF)", RFC 6020, 1904 DOI 10.17487/RFC6020, October 2010, 1905 . 1907 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1908 and A. Bierman, Ed., "Network Configuration Protocol 1909 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1910 . 1912 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1913 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1914 . 1916 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1917 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1918 . 1920 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1921 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1922 December 2014, . 1924 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1925 NETCONF Protocol over Transport Layer Security (TLS) with 1926 Mutual X.509 Authentication", RFC 7589, 1927 DOI 10.17487/RFC7589, June 2015, 1928 . 1930 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1931 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1932 . 1934 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1935 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1936 May 2017, . 1938 8.2. Informative References 1940 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1941 DOI 10.17487/RFC3688, January 2004, 1942 . 1944 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1945 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1946 . 1948 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1949 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1950 . 1952 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1953 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1954 . 1956 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1957 Access Control Model", STD 91, RFC 8341, 1958 DOI 10.17487/RFC8341, March 2018, 1959 . 1961 Appendix A. Expanded Tree Diagrams 1963 A.1. Expanded Tree Diagram for 'ietf-netconf-client' 1965 The following tree diagram [RFC8340] provides an overview of the data 1966 model for the "ietf-netconf-client" module. 1968 This tree diagram shows all the nodes defined in this module, 1969 including those defined by "grouping" statements used by this module. 1971 Please see Section 3.1 for a tree diagram that illustrates what the 1972 module looks like without all the "grouping" statements expanded. 1974 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 1976 module: ietf-netconf-client 1977 +--rw netconf-client 1978 +--rw initiate! {initiate}? 1979 | +--rw netconf-server* [name] 1980 | +--rw name string 1981 | +--rw endpoints 1982 | | +--rw endpoint* [name] 1983 | | +--rw name string 1984 | | +--rw (transport) 1985 | | +--:(ssh) {ssh-initiate}? 1986 | | | +--rw ssh 1987 | | | +--rw tcp-client-parameters 1988 | | | | +--rw remote-address inet:host 1989 | | | | +--rw remote-port? inet:port-number 1990 | | | | +--rw local-address? inet:ip-address 1991 | | | | +--rw local-port? inet:port-number 1992 | | | | +--rw keepalives! 1993 | | | | {tcp-client-keepalives}? 1994 | | | | +--rw idle-time uint16 1995 | | | | +--rw max-probes? uint16 1996 | | | | +--rw probe-interval? uint16 1997 | | | +--rw ssh-client-parameters 1998 | | | +--rw client-identity 1999 | | | | +--rw username? string 2000 | | | | +--rw (auth-type) 2001 | | | | +--:(password) 2002 | | | | | +--rw password? string 2003 | | | | +--:(public-key) 2004 | | | | | +--rw public-key 2005 | | | | | +--rw (local-or-keystore) 2006 | | | | | +--:(local) 2007 | | | | | | {local-keys-sup\ 2008 ported}? 2009 | | | | | | +--rw local-definition 2010 | | | | | | +--rw algorithm? 2011 | | | | | | | asymmetric\ 2012 -key-algorithm-ref 2013 | | | | | | +--rw public-key? 2014 | | | | | | | binary 2015 | | | | | | +--rw private-key? 2016 | | | | | | | union 2017 | | | | | | +---x generate-hid\ 2018 den-key 2019 | | | | | | | +---w input 2020 | | | | | | | +---w algori\ 2021 thm 2022 | | | | | | | asym\ 2023 metric-key-algorithm-ref 2024 | | | | | | +---x install-hidd\ 2025 en-key 2026 | | | | | | +---w input 2027 | | | | | | +---w algori\ 2028 thm 2029 | | | | | | | asym\ 2030 metric-key-algorithm-ref 2031 | | | | | | +---w public\ 2032 -key? 2033 | | | | | | | bina\ 2034 ry 2035 | | | | | | +---w privat\ 2036 e-key? 2037 | | | | | | bina\ 2038 ry 2039 | | | | | +--:(keystore) 2040 | | | | | {keystore-suppo\ 2041 rted}? 2042 | | | | | +--rw keystore-refere\ 2043 nce? 2044 | | | | | ks:asymmetric\ 2045 -key-ref 2046 | | | | +--:(certificate) 2047 | | | | +--rw certificate 2048 | | | | {sshcmn:ssh-x509-certs\ 2049 }? 2050 | | | | +--rw (local-or-keystore) 2051 | | | | +--:(local) 2052 | | | | | {local-keys-sup\ 2053 ported}? 2054 | | | | | +--rw local-definition 2055 | | | | | +--rw algorithm? 2056 | | | | | | asymmetric\ 2058 -key-algorithm-ref 2059 | | | | | +--rw public-key? 2060 | | | | | | binary 2061 | | | | | +--rw private-key? 2062 | | | | | | union 2063 | | | | | +---x generate-hid\ 2064 den-key 2065 | | | | | | +---w input 2066 | | | | | | +---w algori\ 2067 thm 2068 | | | | | | asym\ 2069 metric-key-algorithm-ref 2070 | | | | | +---x install-hidd\ 2071 en-key 2072 | | | | | | +---w input 2073 | | | | | | +---w algori\ 2074 thm 2075 | | | | | | | asym\ 2076 metric-key-algorithm-ref 2077 | | | | | | +---w public\ 2078 -key? 2079 | | | | | | | bina\ 2080 ry 2081 | | | | | | +---w privat\ 2082 e-key? 2083 | | | | | | bina\ 2084 ry 2085 | | | | | +--rw cert? 2086 | | | | | | end-entity\ 2087 -cert-cms 2088 | | | | | +---n certificate-\ 2089 expiration 2090 | | | | | +-- expiration-\ 2091 date 2092 | | | | | yang:da\ 2093 te-and-time 2094 | | | | +--:(keystore) 2095 | | | | {keystore-suppo\ 2096 rted}? 2097 | | | | +--rw keystore-refere\ 2098 nce? 2099 | | | | ks:asymmetric\ 2100 -key-certificate-ref 2101 | | | +--rw server-authentication 2102 | | | | +--rw pinned-ssh-host-keys? 2103 | | | | | ta:pinned-host-keys-ref 2104 | | | | | {ta:ssh-host-keys}? 2105 | | | | +--rw pinned-ca-certs? 2106 | | | | | ta:pinned-certificates-ref 2107 | | | | | {sshcmn:ssh-x509-certs,ta:x5\ 2108 09-certificates}? 2109 | | | | +--rw pinned-server-certs? 2110 | | | | ta:pinned-certificates-ref 2111 | | | | {sshcmn:ssh-x509-certs,ta:x5\ 2112 09-certificates}? 2113 | | | +--rw transport-params 2114 | | | | {ssh-client-transport-params-co\ 2115 nfig}? 2116 | | | | +--rw host-key 2117 | | | | | +--rw host-key-alg* identityref 2118 | | | | +--rw key-exchange 2119 | | | | | +--rw key-exchange-alg* 2120 | | | | | identityref 2121 | | | | +--rw encryption 2122 | | | | | +--rw encryption-alg* 2123 | | | | | identityref 2124 | | | | +--rw mac 2125 | | | | +--rw mac-alg* identityref 2126 | | | +--rw keepalives! 2127 | | | {ssh-client-keepalives}? 2128 | | | +--rw max-wait? uint16 2129 | | | +--rw max-attempts? uint8 2130 | | +--:(tls) {tls-initiate}? 2131 | | +--rw tls 2132 | | +--rw tcp-client-parameters 2133 | | | +--rw remote-address inet:host 2134 | | | +--rw remote-port? inet:port-number 2135 | | | +--rw local-address? inet:ip-address 2136 | | | +--rw local-port? inet:port-number 2137 | | | +--rw keepalives! 2138 | | | {tcp-client-keepalives}? 2139 | | | +--rw idle-time uint16 2140 | | | +--rw max-probes? uint16 2141 | | | +--rw probe-interval? uint16 2142 | | +--rw tls-client-parameters 2143 | | +--rw client-identity 2144 | | | +--rw (auth-type) 2145 | | | +--:(certificate) 2146 | | | +--rw certificate 2147 | | | +--rw (local-or-keystore) 2148 | | | +--:(local) 2149 | | | | {local-keys-sup\ 2150 ported}? 2151 | | | | +--rw local-definition 2152 | | | | +--rw algorithm? 2153 | | | | | asymmetric\ 2155 -key-algorithm-ref 2156 | | | | +--rw public-key? 2157 | | | | | binary 2158 | | | | +--rw private-key? 2159 | | | | | union 2160 | | | | +---x generate-hid\ 2161 den-key 2162 | | | | | +---w input 2163 | | | | | +---w algori\ 2164 thm 2165 | | | | | asym\ 2166 metric-key-algorithm-ref 2167 | | | | +---x install-hidd\ 2168 en-key 2169 | | | | | +---w input 2170 | | | | | +---w algori\ 2171 thm 2172 | | | | | | asym\ 2173 metric-key-algorithm-ref 2174 | | | | | +---w public\ 2175 -key? 2176 | | | | | | bina\ 2177 ry 2178 | | | | | +---w privat\ 2179 e-key? 2180 | | | | | bina\ 2181 ry 2182 | | | | +--rw cert? 2183 | | | | | end-entity\ 2184 -cert-cms 2185 | | | | +---n certificate-\ 2186 expiration 2187 | | | | +-- expiration-\ 2188 date 2189 | | | | yang:da\ 2190 te-and-time 2191 | | | +--:(keystore) 2192 | | | {keystore-suppo\ 2193 rted}? 2194 | | | +--rw keystore-refere\ 2195 nce? 2196 | | | ks:asymmetric\ 2197 -key-certificate-ref 2198 | | +--rw server-authentication 2199 | | | +--rw pinned-ca-certs? 2200 | | | | ta:pinned-certificates-ref 2201 | | | | {ta:x509-certificates}? 2202 | | | +--rw pinned-server-certs? 2203 | | | ta:pinned-certificates-ref 2204 | | | {ta:x509-certificates}? 2205 | | +--rw hello-params 2206 | | | {tls-client-hello-params-config\ 2207 }? 2208 | | | +--rw tls-versions 2209 | | | | +--rw tls-version* identityref 2210 | | | +--rw cipher-suites 2211 | | | +--rw cipher-suite* identityref 2212 | | +--rw keepalives! 2213 | | {tls-client-keepalives}? 2214 | | +--rw max-wait? uint16 2215 | | +--rw max-attempts? uint8 2216 | +--rw connection-type 2217 | | +--rw (connection-type) 2218 | | +--:(persistent-connection) 2219 | | | +--rw persistent! 2220 | | +--:(periodic-connection) 2221 | | +--rw periodic! 2222 | | +--rw period? uint16 2223 | | +--rw anchor-time? yang:date-and-time 2224 | | +--rw idle-timeout? uint16 2225 | +--rw reconnect-strategy 2226 | +--rw start-with? enumeration 2227 | +--rw max-attempts? uint8 2228 +--rw listen! {listen}? 2229 +--rw idle-timeout? uint16 2230 +--rw endpoint* [name] 2231 +--rw name string 2232 +--rw (transport) 2233 +--:(ssh) {ssh-listen}? 2234 | +--rw ssh 2235 | +--rw tcp-server-parameters 2236 | | +--rw local-address inet:ip-address 2237 | | +--rw local-port? inet:port-number 2238 | | +--rw keepalives! {tcp-server-keepalives}? 2239 | | +--rw idle-time uint16 2240 | | +--rw max-probes? uint16 2241 | | +--rw probe-interval? uint16 2242 | +--rw ssh-client-parameters 2243 | +--rw client-identity 2244 | | +--rw username? string 2245 | | +--rw (auth-type) 2246 | | +--:(password) 2247 | | | +--rw password? string 2248 | | +--:(public-key) 2249 | | | +--rw public-key 2250 | | | +--rw (local-or-keystore) 2251 | | | +--:(local) 2252 | | | | {local-keys-supported\ 2253 }? 2254 | | | | +--rw local-definition 2255 | | | | +--rw algorithm? 2256 | | | | | asymmetric-key-a\ 2257 lgorithm-ref 2258 | | | | +--rw public-key? 2259 | | | | | binary 2260 | | | | +--rw private-key? 2261 | | | | | union 2262 | | | | +---x generate-hidden-key 2263 | | | | | +---w input 2264 | | | | | +---w algorithm 2265 | | | | | asymmetric\ 2266 -key-algorithm-ref 2267 | | | | +---x install-hidden-key 2268 | | | | +---w input 2269 | | | | +---w algorithm 2270 | | | | | asymmetric\ 2271 -key-algorithm-ref 2272 | | | | +---w public-key? 2273 | | | | | binary 2274 | | | | +---w private-key? 2275 | | | | binary 2276 | | | +--:(keystore) 2277 | | | {keystore-supported}? 2278 | | | +--rw keystore-reference? 2279 | | | ks:asymmetric-key-r\ 2280 ef 2281 | | +--:(certificate) 2282 | | +--rw certificate 2283 | | {sshcmn:ssh-x509-certs}? 2284 | | +--rw (local-or-keystore) 2285 | | +--:(local) 2286 | | | {local-keys-supported\ 2287 }? 2288 | | | +--rw local-definition 2289 | | | +--rw algorithm? 2290 | | | | asymmetric-key-a\ 2291 lgorithm-ref 2292 | | | +--rw public-key? 2293 | | | | binary 2294 | | | +--rw private-key? 2295 | | | | union 2296 | | | +---x generate-hidden-key 2297 | | | | +---w input 2298 | | | | +---w algorithm 2299 | | | | asymmetric\ 2300 -key-algorithm-ref 2301 | | | +---x install-hidden-key 2302 | | | | +---w input 2303 | | | | +---w algorithm 2304 | | | | | asymmetric\ 2305 -key-algorithm-ref 2306 | | | | +---w public-key? 2307 | | | | | binary 2308 | | | | +---w private-key? 2309 | | | | binary 2310 | | | +--rw cert? 2311 | | | | end-entity-cert-\ 2312 cms 2313 | | | +---n certificate-expira\ 2314 tion 2315 | | | +-- expiration-date 2316 | | | yang:date-and\ 2317 -time 2318 | | +--:(keystore) 2319 | | {keystore-supported}? 2320 | | +--rw keystore-reference? 2321 | | ks:asymmetric-key-c\ 2322 ertificate-ref 2323 | +--rw server-authentication 2324 | | +--rw pinned-ssh-host-keys? 2325 | | | ta:pinned-host-keys-ref 2326 | | | {ta:ssh-host-keys}? 2327 | | +--rw pinned-ca-certs? 2328 | | | ta:pinned-certificates-ref 2329 | | | {sshcmn:ssh-x509-certs,ta:x509-cer\ 2330 tificates}? 2331 | | +--rw pinned-server-certs? 2332 | | ta:pinned-certificates-ref 2333 | | {sshcmn:ssh-x509-certs,ta:x509-cer\ 2334 tificates}? 2335 | +--rw transport-params 2336 | | {ssh-client-transport-params-config}? 2337 | | +--rw host-key 2338 | | | +--rw host-key-alg* identityref 2339 | | +--rw key-exchange 2340 | | | +--rw key-exchange-alg* identityref 2341 | | +--rw encryption 2342 | | | +--rw encryption-alg* identityref 2343 | | +--rw mac 2344 | | +--rw mac-alg* identityref 2345 | +--rw keepalives! {ssh-client-keepalives}? 2346 | +--rw max-wait? uint16 2347 | +--rw max-attempts? uint8 2348 +--:(tls) {tls-listen}? 2349 +--rw tls 2350 +--rw tcp-server-parameters 2351 | +--rw local-address inet:ip-address 2352 | +--rw local-port? inet:port-number 2353 | +--rw keepalives! {tcp-server-keepalives}? 2354 | +--rw idle-time uint16 2355 | +--rw max-probes? uint16 2356 | +--rw probe-interval? uint16 2357 +--rw tls-client-parameters 2358 +--rw client-identity 2359 | +--rw (auth-type) 2360 | +--:(certificate) 2361 | +--rw certificate 2362 | +--rw (local-or-keystore) 2363 | +--:(local) 2364 | | {local-keys-supported\ 2365 }? 2366 | | +--rw local-definition 2367 | | +--rw algorithm? 2368 | | | asymmetric-key-a\ 2369 lgorithm-ref 2370 | | +--rw public-key? 2371 | | | binary 2372 | | +--rw private-key? 2373 | | | union 2374 | | +---x generate-hidden-key 2375 | | | +---w input 2376 | | | +---w algorithm 2377 | | | asymmetric\ 2378 -key-algorithm-ref 2379 | | +---x install-hidden-key 2380 | | | +---w input 2381 | | | +---w algorithm 2382 | | | | asymmetric\ 2383 -key-algorithm-ref 2384 | | | +---w public-key? 2385 | | | | binary 2386 | | | +---w private-key? 2387 | | | binary 2388 | | +--rw cert? 2389 | | | end-entity-cert-\ 2390 cms 2391 | | +---n certificate-expira\ 2392 tion 2393 | | +-- expiration-date 2394 | | yang:date-and\ 2396 -time 2397 | +--:(keystore) 2398 | {keystore-supported}? 2399 | +--rw keystore-reference? 2400 | ks:asymmetric-key-c\ 2401 ertificate-ref 2402 +--rw server-authentication 2403 | +--rw pinned-ca-certs? 2404 | | ta:pinned-certificates-ref 2405 | | {ta:x509-certificates}? 2406 | +--rw pinned-server-certs? 2407 | ta:pinned-certificates-ref 2408 | {ta:x509-certificates}? 2409 +--rw hello-params 2410 | {tls-client-hello-params-config}? 2411 | +--rw tls-versions 2412 | | +--rw tls-version* identityref 2413 | +--rw cipher-suites 2414 | +--rw cipher-suite* identityref 2415 +--rw keepalives! {tls-client-keepalives}? 2416 +--rw max-wait? uint16 2417 +--rw max-attempts? uint8 2419 A.2. Expanded Tree Diagram for 'ietf-netconf-server' 2421 The following tree diagram [RFC8340] provides an overview of the data 2422 model for the "ietf-netconf-server" module. 2424 This tree diagram shows all the nodes defined in this module, 2425 including those defined by "grouping" statements used by this module. 2427 Please see Section 4.1 for a tree diagram that illustrates what the 2428 module looks like without all the "grouping" statements expanded. 2430 =========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2432 module: ietf-netconf-server 2433 +--rw netconf-server 2434 +--rw listen! {listen}? 2435 | +--rw idle-timeout? uint16 2436 | +--rw endpoint* [name] 2437 | +--rw name string 2438 | +--rw (transport) 2439 | +--:(ssh) {ssh-listen}? 2440 | | +--rw ssh 2441 | | +--rw tcp-server-parameters 2442 | | | +--rw local-address inet:ip-address 2443 | | | +--rw local-port? inet:port-number 2444 | | | +--rw keepalives! {tcp-server-keepalives}? 2445 | | | +--rw idle-time uint16 2446 | | | +--rw max-probes? uint16 2447 | | | +--rw probe-interval? uint16 2448 | | +--rw ssh-server-parameters 2449 | | +--rw server-identity 2450 | | | +--rw host-key* [name] 2451 | | | +--rw name string 2452 | | | +--rw (host-key-type) 2453 | | | +--:(public-key) 2454 | | | | +--rw public-key 2455 | | | | +--rw (local-or-keystore) 2456 | | | | +--:(local) 2457 | | | | | {local-keys-suppor\ 2458 ted}? 2459 | | | | | +--rw local-definition 2460 | | | | | +--rw algorithm? 2461 | | | | | | asymmetric-ke\ 2462 y-algorithm-ref 2463 | | | | | +--rw public-key? 2464 | | | | | | binary 2465 | | | | | +--rw private-key? 2466 | | | | | | union 2467 | | | | | +---x generate-hidden\ 2468 -key 2469 | | | | | | +---w input 2470 | | | | | | +---w algorithm 2471 | | | | | | asymmet\ 2472 ric-key-algorithm-ref 2473 | | | | | +---x install-hidden-\ 2474 key 2475 | | | | | +---w input 2476 | | | | | +---w algorithm 2477 | | | | | | asymmet\ 2478 ric-key-algorithm-ref 2479 | | | | | +---w public-ke\ 2480 y? 2481 | | | | | | binary 2482 | | | | | +---w private-k\ 2483 ey? 2484 | | | | | binary 2485 | | | | +--:(keystore) 2486 | | | | {keystore-supporte\ 2487 d}? 2488 | | | | +--rw keystore-reference? 2489 | | | | ks:asymmetric-ke\ 2490 y-ref 2491 | | | +--:(certificate) 2492 | | | +--rw certificate 2493 | | | {sshcmn:ssh-x509-certs}? 2494 | | | +--rw (local-or-keystore) 2495 | | | +--:(local) 2496 | | | | {local-keys-suppor\ 2497 ted}? 2498 | | | | +--rw local-definition 2499 | | | | +--rw algorithm? 2500 | | | | | asymmetric-ke\ 2501 y-algorithm-ref 2502 | | | | +--rw public-key? 2503 | | | | | binary 2504 | | | | +--rw private-key? 2505 | | | | | union 2506 | | | | +---x generate-hidden\ 2507 -key 2508 | | | | | +---w input 2509 | | | | | +---w algorithm 2510 | | | | | asymmet\ 2511 ric-key-algorithm-ref 2512 | | | | +---x install-hidden-\ 2513 key 2514 | | | | | +---w input 2515 | | | | | +---w algorithm 2516 | | | | | | asymmet\ 2517 ric-key-algorithm-ref 2518 | | | | | +---w public-ke\ 2519 y? 2520 | | | | | | binary 2521 | | | | | +---w private-k\ 2522 ey? 2523 | | | | | binary 2524 | | | | +--rw cert? 2525 | | | | | end-entity-ce\ 2526 rt-cms 2527 | | | | +---n certificate-exp\ 2528 iration 2529 | | | | +-- expiration-date 2530 | | | | yang:date-\ 2531 and-time 2532 | | | +--:(keystore) 2533 | | | {keystore-supporte\ 2534 d}? 2535 | | | +--rw keystore-reference? 2536 | | | ks:asymmetric-ke\ 2537 y-certificate-ref 2538 | | +--rw client-cert-auth 2539 | | | {sshcmn:ssh-x509-certs}? 2540 | | | +--rw pinned-ca-certs? 2541 | | | | ta:pinned-certificates-ref 2542 | | | | {ta:x509-certificates}? 2543 | | | +--rw pinned-client-certs? 2544 | | | ta:pinned-certificates-ref 2545 | | | {ta:x509-certificates}? 2546 | | +--rw transport-params 2547 | | | {ssh-server-transport-params-config}? 2548 | | | +--rw host-key 2549 | | | | +--rw host-key-alg* identityref 2550 | | | +--rw key-exchange 2551 | | | | +--rw key-exchange-alg* identityref 2552 | | | +--rw encryption 2553 | | | | +--rw encryption-alg* identityref 2554 | | | +--rw mac 2555 | | | +--rw mac-alg* identityref 2556 | | +--rw keepalives! {ssh-server-keepalives}? 2557 | | +--rw max-wait? uint16 2558 | | +--rw max-attempts? uint8 2559 | +--:(tls) {tls-listen}? 2560 | +--rw tls 2561 | +--rw tcp-server-parameters 2562 | | +--rw local-address inet:ip-address 2563 | | +--rw local-port? inet:port-number 2564 | | +--rw keepalives! {tcp-server-keepalives}? 2565 | | +--rw idle-time uint16 2566 | | +--rw max-probes? uint16 2567 | | +--rw probe-interval? uint16 2568 | +--rw tls-server-parameters 2569 | +--rw server-identity 2570 | | +--rw (local-or-keystore) 2571 | | +--:(local) {local-keys-supported}? 2572 | | | +--rw local-definition 2573 | | | +--rw algorithm? 2574 | | | | asymmetric-key-algorithm-\ 2575 ref 2576 | | | +--rw public-key? 2577 | | | | binary 2578 | | | +--rw private-key? 2579 | | | | union 2580 | | | +---x generate-hidden-key 2581 | | | | +---w input 2582 | | | | +---w algorithm 2583 | | | | asymmetric-key-algo\ 2584 rithm-ref 2585 | | | +---x install-hidden-key 2586 | | | | +---w input 2587 | | | | +---w algorithm 2588 | | | | | asymmetric-key-algo\ 2589 rithm-ref 2590 | | | | +---w public-key? binary 2591 | | | | +---w private-key? binary 2592 | | | +--rw cert? 2593 | | | | end-entity-cert-cms 2594 | | | +---n certificate-expiration 2595 | | | +-- expiration-date 2596 | | | yang:date-and-time 2597 | | +--:(keystore) {keystore-supported}? 2598 | | +--rw keystore-reference? 2599 | | ks:asymmetric-key-certificat\ 2600 e-ref 2601 | +--rw client-authentication 2602 | | +--rw pinned-ca-certs? 2603 | | | ta:pinned-certificates-ref 2604 | | | {ta:x509-certificates}? 2605 | | +--rw pinned-client-certs? 2606 | | | ta:pinned-certificates-ref 2607 | | | {ta:x509-certificates}? 2608 | | +--rw cert-maps 2609 | | +--rw cert-to-name* [id] 2610 | | +--rw id uint32 2611 | | +--rw fingerprint 2612 | | | x509c2n:tls-fingerprint 2613 | | +--rw map-type identityref 2614 | | +--rw name string 2615 | +--rw hello-params 2616 | | {tls-server-hello-params-config}? 2617 | | +--rw tls-versions 2618 | | | +--rw tls-version* identityref 2619 | | +--rw cipher-suites 2620 | | +--rw cipher-suite* identityref 2621 | +--rw keepalives! {tls-server-keepalives}? 2622 | +--rw max-wait? uint16 2623 | +--rw max-attempts? uint8 2624 +--rw call-home! {call-home}? 2625 +--rw netconf-client* [name] 2626 +--rw name string 2627 +--rw endpoints 2628 | +--rw endpoint* [name] 2629 | +--rw name string 2630 | +--rw (transport) 2631 | +--:(ssh) {ssh-call-home}? 2632 | | +--rw ssh 2633 | | +--rw tcp-client-parameters 2634 | | | +--rw remote-address inet:host 2635 | | | +--rw remote-port? inet:port-number 2636 | | | +--rw local-address? inet:ip-address 2637 | | | +--rw local-port? inet:port-number 2638 | | | +--rw keepalives! 2639 | | | {tcp-client-keepalives}? 2640 | | | +--rw idle-time uint16 2641 | | | +--rw max-probes? uint16 2642 | | | +--rw probe-interval? uint16 2643 | | +--rw ssh-server-parameters 2644 | | +--rw server-identity 2645 | | | +--rw host-key* [name] 2646 | | | +--rw name string 2647 | | | +--rw (host-key-type) 2648 | | | +--:(public-key) 2649 | | | | +--rw public-key 2650 | | | | +--rw (local-or-keystore) 2651 | | | | +--:(local) 2652 | | | | | {local-keys-\ 2653 supported}? 2654 | | | | | +--rw local-defini\ 2655 tion 2656 | | | | | +--rw algorithm? 2657 | | | | | | asymmet\ 2658 ric-key-algorithm-ref 2659 | | | | | +--rw public-ke\ 2660 y? 2661 | | | | | | binary 2662 | | | | | +--rw private-k\ 2663 ey? 2664 | | | | | | union 2665 | | | | | +---x generate-\ 2666 hidden-key 2667 | | | | | | +---w input 2668 | | | | | | +---w alg\ 2669 orithm 2670 | | | | | | a\ 2671 symmetric-key-algorithm-ref 2672 | | | | | +---x install-h\ 2673 idden-key 2674 | | | | | +---w input 2675 | | | | | +---w alg\ 2676 orithm 2677 | | | | | | a\ 2678 symmetric-key-algorithm-ref 2679 | | | | | +---w pub\ 2680 lic-key? 2681 | | | | | | b\ 2682 inary 2683 | | | | | +---w pri\ 2685 vate-key? 2686 | | | | | b\ 2687 inary 2688 | | | | +--:(keystore) 2689 | | | | {keystore-su\ 2690 pported}? 2691 | | | | +--rw keystore-ref\ 2692 erence? 2693 | | | | ks:asymmet\ 2694 ric-key-ref 2695 | | | +--:(certificate) 2696 | | | +--rw certificate 2697 | | | {sshcmn:ssh-x509-ce\ 2698 rts}? 2699 | | | +--rw (local-or-keystore) 2700 | | | +--:(local) 2701 | | | | {local-keys-\ 2702 supported}? 2703 | | | | +--rw local-defini\ 2704 tion 2705 | | | | +--rw algorithm? 2706 | | | | | asymmet\ 2707 ric-key-algorithm-ref 2708 | | | | +--rw public-ke\ 2709 y? 2710 | | | | | binary 2711 | | | | +--rw private-k\ 2712 ey? 2713 | | | | | union 2714 | | | | +---x generate-\ 2715 hidden-key 2716 | | | | | +---w input 2717 | | | | | +---w alg\ 2718 orithm 2719 | | | | | a\ 2720 symmetric-key-algorithm-ref 2721 | | | | +---x install-h\ 2722 idden-key 2723 | | | | | +---w input 2724 | | | | | +---w alg\ 2725 orithm 2726 | | | | | | a\ 2727 symmetric-key-algorithm-ref 2728 | | | | | +---w pub\ 2729 lic-key? 2730 | | | | | | b\ 2731 inary 2732 | | | | | +---w pri\ 2734 vate-key? 2735 | | | | | b\ 2736 inary 2737 | | | | +--rw cert? 2738 | | | | | end-ent\ 2739 ity-cert-cms 2740 | | | | +---n certifica\ 2741 te-expiration 2742 | | | | +-- expirati\ 2743 on-date 2744 | | | | yang\ 2745 :date-and-time 2746 | | | +--:(keystore) 2747 | | | {keystore-su\ 2748 pported}? 2749 | | | +--rw keystore-ref\ 2750 erence? 2751 | | | ks:asymmet\ 2752 ric-key-certificate-ref 2753 | | +--rw client-cert-auth 2754 | | | {sshcmn:ssh-x509-certs}? 2755 | | | +--rw pinned-ca-certs? 2756 | | | | ta:pinned-certificates-ref 2757 | | | | {ta:x509-certificates}? 2758 | | | +--rw pinned-client-certs? 2759 | | | ta:pinned-certificates-ref 2760 | | | {ta:x509-certificates}? 2761 | | +--rw transport-params 2762 | | | {ssh-server-transport-params-co\ 2763 nfig}? 2764 | | | +--rw host-key 2765 | | | | +--rw host-key-alg* identityref 2766 | | | +--rw key-exchange 2767 | | | | +--rw key-exchange-alg* 2768 | | | | identityref 2769 | | | +--rw encryption 2770 | | | | +--rw encryption-alg* 2771 | | | | identityref 2772 | | | +--rw mac 2773 | | | +--rw mac-alg* identityref 2774 | | +--rw keepalives! 2775 | | {ssh-server-keepalives}? 2776 | | +--rw max-wait? uint16 2777 | | +--rw max-attempts? uint8 2778 | +--:(tls) {tls-call-home}? 2779 | +--rw tls 2780 | +--rw tcp-client-parameters 2781 | | +--rw remote-address inet:host 2782 | | +--rw remote-port? inet:port-number 2783 | | +--rw local-address? inet:ip-address 2784 | | +--rw local-port? inet:port-number 2785 | | +--rw keepalives! 2786 | | {tcp-client-keepalives}? 2787 | | +--rw idle-time uint16 2788 | | +--rw max-probes? uint16 2789 | | +--rw probe-interval? uint16 2790 | +--rw tls-server-parameters 2791 | +--rw server-identity 2792 | | +--rw (local-or-keystore) 2793 | | +--:(local) 2794 | | | {local-keys-supported}? 2795 | | | +--rw local-definition 2796 | | | +--rw algorithm? 2797 | | | | asymmetric-key-algo\ 2798 rithm-ref 2799 | | | +--rw public-key? 2800 | | | | binary 2801 | | | +--rw private-key? 2802 | | | | union 2803 | | | +---x generate-hidden-key 2804 | | | | +---w input 2805 | | | | +---w algorithm 2806 | | | | asymmetric-ke\ 2807 y-algorithm-ref 2808 | | | +---x install-hidden-key 2809 | | | | +---w input 2810 | | | | +---w algorithm 2811 | | | | | asymmetric-ke\ 2812 y-algorithm-ref 2813 | | | | +---w public-key? 2814 | | | | | binary 2815 | | | | +---w private-key? 2816 | | | | binary 2817 | | | +--rw cert? 2818 | | | | end-entity-cert-cms 2819 | | | +---n certificate-expiration 2820 | | | +-- expiration-date 2821 | | | yang:date-and-ti\ 2822 me 2823 | | +--:(keystore) 2824 | | {keystore-supported}? 2825 | | +--rw keystore-reference? 2826 | | ks:asymmetric-key-cert\ 2827 ificate-ref 2828 | +--rw client-authentication 2829 | | +--rw pinned-ca-certs? 2830 | | | ta:pinned-certificates-ref 2831 | | | {ta:x509-certificates}? 2832 | | +--rw pinned-client-certs? 2833 | | | ta:pinned-certificates-ref 2834 | | | {ta:x509-certificates}? 2835 | | +--rw cert-maps 2836 | | +--rw cert-to-name* [id] 2837 | | +--rw id uint32 2838 | | +--rw fingerprint 2839 | | | x509c2n:tls-fingerprint 2840 | | +--rw map-type 2841 | | | identityref 2842 | | +--rw name string 2843 | +--rw hello-params 2844 | | {tls-server-hello-params-config\ 2845 }? 2846 | | +--rw tls-versions 2847 | | | +--rw tls-version* identityref 2848 | | +--rw cipher-suites 2849 | | +--rw cipher-suite* identityref 2850 | +--rw keepalives! 2851 | {tls-server-keepalives}? 2852 | +--rw max-wait? uint16 2853 | +--rw max-attempts? uint8 2854 +--rw connection-type 2855 | +--rw (connection-type) 2856 | +--:(persistent-connection) 2857 | | +--rw persistent! 2858 | +--:(periodic-connection) 2859 | +--rw periodic! 2860 | +--rw period? uint16 2861 | +--rw anchor-time? yang:date-and-time 2862 | +--rw idle-timeout? uint16 2863 +--rw reconnect-strategy 2864 +--rw start-with? enumeration 2865 +--rw max-attempts? uint8 2867 Appendix B. Change Log 2869 B.1. 00 to 01 2871 o Renamed "keychain" to "keystore". 2873 B.2. 01 to 02 2875 o Added to ietf-netconf-client ability to connected to a cluster of 2876 endpoints, including a reconnection-strategy. 2878 o Added to ietf-netconf-client the ability to configure connection- 2879 type and also keep-alive strategy. 2881 o Updated both modules to accommodate new groupings in the ssh/tls 2882 drafts. 2884 B.3. 02 to 03 2886 o Refined use of tls-client-grouping to add a must statement 2887 indicating that the TLS client must specify a client-certificate. 2889 o Changed 'netconf-client' to be a grouping (not a container). 2891 B.4. 03 to 04 2893 o Added RFC 8174 to Requirements Language Section. 2895 o Replaced refine statement in ietf-netconf-client to add a 2896 mandatory true. 2898 o Added refine statement in ietf-netconf-server to add a must 2899 statement. 2901 o Now there are containers and groupings, for both the client and 2902 server models. 2904 B.5. 04 to 05 2906 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2908 o Updated examples to inline key and certificates (no longer a 2909 leafref to keystore) 2911 B.6. 05 to 06 2913 o Fixed change log missing section issue. 2915 o Updated examples to match latest updates to the crypto-types, 2916 trust-anchors, and keystore drafts. 2918 o Reduced line length of the YANG modules to fit within 69 columns. 2920 B.7. 06 to 07 2922 o Removed "idle-timeout" from "persistent" connection config. 2924 o Added "random-selection" for reconnection-strategy's "starts-with" 2925 enum. 2927 o Replaced "connection-type" choice default (persistent) with 2928 "mandatory true". 2930 o Reduced the periodic-connection's "idle-timeout" from 5 to 2 2931 minutes. 2933 o Replaced reconnect-timeout with period/anchor-time combo. 2935 B.8. 07 to 08 2937 o Modified examples to be compatible with new crypto-types algs 2939 B.9. 08 to 09 2941 o Corrected use of "mandatory true" for "address" leafs. 2943 o Updated examples to reflect update to groupings defined in the 2944 keystore draft. 2946 o Updated to use groupings defined in new TCP and HTTP drafts. 2948 o Updated copyright date, boilerplate template, affiliation, and 2949 folding algorithm. 2951 B.10. 09 to 10 2953 o Reformatted YANG modules. 2955 B.11. 10 to 11 2957 o Adjusted for the top-level "demux container" added to groupings 2958 imported from other modules. 2960 o Added "must" expressions to ensure that keepalives are not 2961 configured for "periodic" connections. 2963 o Updated the boilerplate text in module-level "description" 2964 statement to match copyeditor convention. 2966 o Moved "expanded" tree diagrams to the Appendix. 2968 Acknowledgements 2970 The authors would like to thank for following for lively discussions 2971 on list and in the halls (ordered by last name): Andy Bierman, Martin 2972 Bjorklund, Benoit Claise, Ramkumar Dhanapal, Mehmet Ersue, Balazs 2973 Kovacs, David Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, 2974 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert 2975 Wijnen. 2977 Author's Address 2979 Kent Watsen 2980 Watsen Networks 2982 EMail: kent+ietf@watsen.net