idnits 2.17.1 draft-ietf-netconf-netconf-client-server-03.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 : ---------------------------------------------------------------------------- ** There are 16 instances of too long lines in the document, the longest one being 17 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 207 has weird spacing: '...address ine...' == Line 244 has weird spacing: '...address ine...' == Line 336 has weird spacing: '...address ine...' == Line 899 has weird spacing: '...rw name str...' == Line 936 has weird spacing: '...rw name lea...' == (5 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 13, 2017) is 2509 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-01 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-02 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-02 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 11 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track G. Wu 5 Expires: December 15, 2017 Cisco Networks 6 J. Schoenwaelder 7 Jacobs University Bremen 8 June 13, 2017 10 NETCONF Client and Server Models 11 draft-ietf-netconf-netconf-client-server-03 13 Abstract 15 This document defines two YANG modules, one module to configure a 16 NETCONF client and the other module to configure a NETCONF server. 17 Both modules support both the SSH and TLS transport protocols, and 18 support both standard NETCONF and NETCONF Call Home connections. 20 Editorial Note (To be removed by RFC Editor) 22 This draft contains many placeholder values that need to be replaced 23 with finalized values at the time of publication. This note 24 summarizes all of the substitutions that are needed. No other RFC 25 Editor instructions are specified elsewhere in this document. 27 This document contains references to other drafts in progress, both 28 in the Normative References section, as well as in body text 29 throughout. Please update the following references to reflect their 30 final RFC assignments: 32 o I-D.ietf-netconf-keystore 34 o I-D.ietf-netconf-ssh-client-server 36 o I-D.ietf-netconf-tls-client-server 38 Artwork in this document contains shorthand references to drafts in 39 progress. Please apply the following replacements: 41 o "XXXX" --> the assigned RFC value for this draft 43 o "YYYY" --> the assigned RFC value for I-D.ietf-netconf-ssh-client- 44 server 46 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-tls-client- 47 server 49 Artwork in this document contains placeholder values for the date of 50 publication of this draft. Please apply the following replacement: 52 o "2017-06-13" --> the publication date of this draft 54 The following Appendix section is to be removed prior to publication: 56 o Appendix A. Change Log 58 Status of This Memo 60 This Internet-Draft is submitted in full conformance with the 61 provisions of BCP 78 and BCP 79. 63 Internet-Drafts are working documents of the Internet Engineering 64 Task Force (IETF). Note that other groups may also distribute 65 working documents as Internet-Drafts. The list of current Internet- 66 Drafts is at http://datatracker.ietf.org/drafts/current/. 68 Internet-Drafts are draft documents valid for a maximum of six months 69 and may be updated, replaced, or obsoleted by other documents at any 70 time. It is inappropriate to use Internet-Drafts as reference 71 material or to cite them other than as "work in progress." 73 This Internet-Draft will expire on December 15, 2017. 75 Copyright Notice 77 Copyright (c) 2017 IETF Trust and the persons identified as the 78 document authors. All rights reserved. 80 This document is subject to BCP 78 and the IETF Trust's Legal 81 Provisions Relating to IETF Documents 82 (http://trustee.ietf.org/license-info) in effect on the date of 83 publication of this document. Please review these documents 84 carefully, as they describe your rights and restrictions with respect 85 to this document. Code Components extracted from this document must 86 include Simplified BSD License text as described in Section 4.e of 87 the Trust Legal Provisions and are provided without warranty as 88 described in the Simplified BSD License. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 93 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 94 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4 95 2. The NETCONF Client Model . . . . . . . . . . . . . . . . . . 4 96 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 5 97 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 98 2.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 10 99 3. The NETCONF Server Model . . . . . . . . . . . . . . . . . . 19 100 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 20 101 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 23 102 3.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 26 103 4. Design Considerations . . . . . . . . . . . . . . . . . . . . 37 104 4.1. Support all NETCONF transports . . . . . . . . . . . . . 37 105 4.2. Enable each transport to select which keys to use . . . . 37 106 4.3. Support authenticating NETCONF clients certificates . . . 38 107 4.4. Support mapping authenticated NETCONF client certificates 108 to usernames . . . . . . . . . . . . . . . . . . . . . . 38 109 4.5. Support both listening for connections and call home . . 38 110 4.6. For Call Home connections . . . . . . . . . . . . . . . . 38 111 4.6.1. Support more than one NETCONF client . . . . . . . . 38 112 4.6.2. Support NETCONF clients having more than one endpoint 38 113 4.6.3. Support a reconnection strategy . . . . . . . . . . . 39 114 4.6.4. Support both persistent and periodic connections . . 39 115 4.6.5. Reconnection strategy for periodic connections . . . 39 116 4.6.6. Keep-alives for persistent connections . . . . . . . 39 117 4.6.7. Customizations for periodic connections . . . . . . . 39 118 5. Security Considerations . . . . . . . . . . . . . . . . . . . 40 119 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 120 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 41 121 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 41 122 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 123 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 124 8.1. Normative References . . . . . . . . . . . . . . . . . . 42 125 8.2. Informative References . . . . . . . . . . . . . . . . . 43 126 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 44 127 A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 44 128 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 44 129 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 44 130 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 44 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 133 1. Introduction 135 This document defines two YANG [RFC7950] modules, one module to 136 configure a NETCONF client and the other module to configure a 137 NETCONF server. Both modules support both the SSH and TLS transport 138 protocols, and support both standard NETCONF and NETCONF Call Home 139 connections. 141 NETCONF is defined by [RFC6241]. SSH is defined by [RFC4252], 142 [RFC4253], and [RFC4254]. TLS is defined by [RFC5246]. NETCONF Call 143 Home is defined by [RFC8071]). 145 1.1. Terminology 147 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in RFC 2119 [RFC2119]. 151 1.2. Tree Diagrams 153 A simplified graphical representation of the data models is used in 154 this document. The meaning of the symbols in these diagrams is as 155 follows: 157 o Brackets "[" and "]" enclose list keys. 159 o Braces "{" and "}" enclose feature names, and indicate that the 160 named feature must be present for the subtree to be present. 162 o Abbreviations before data node names: "rw" means configuration 163 (read-write) and "ro" state data (read-only). 165 o Symbols after data node names: "?" means an optional node, "!" 166 means a presence container, and "*" denotes a list and leaf-list. 168 o Parentheses enclose choice and case nodes, and case nodes are also 169 marked with a colon (":"). 171 o Ellipsis ("...") stands for contents of subtrees that are not 172 shown. 174 2. The NETCONF Client Model 176 The NETCONF client model presented in this section supports both 177 clients initiating connections to servers, as well as clients 178 listening for connections from servers calling home. 180 This model supports both the SSH and TLS transport protocols, using 181 the SSH client and TLS client groupings defined in 182 [I-D.ietf-netconf-ssh-client-server] and 183 [I-D.ietf-netconf-tls-client-server] respectively. 185 All private keys and trusted certificates are held in the keystore 186 model defined in [I-D.ietf-netconf-keystore]. 188 YANG feature statements are used to enable implementations to 189 advertise which parts of the model the NETCONF client supports. 191 2.1. Tree Diagram 193 Note: all lines are folded at column 71 with no '\' character. 195 module: ietf-netconf-client 196 groupings: 197 netconf-client 198 +---- initiate {initiate}? 199 | +---- netconf-server* [name] 200 | +---- name? string 201 | +---- (transport) 202 | | +--:(ssh) {ssh-initiate}? 203 | | | +---- ssh 204 | | | +---- endpoints 205 | | | | +---- endpoint* [name] 206 | | | | +---- name? string 207 | | | | +---- address inet:host 208 | | | | +---- port? inet:port-number 209 | | | +---- server-auth 210 | | | | +---- trusted-ssh-host-keys? 211 | | | | | -> /ks:keystore/trusted-host-keys/name 212 | | | | +---- trusted-ca-certs? leafref 213 | | | | | {sshcom:ssh-x509-certs}? 214 | | | | +---- trusted-server-certs? leafref 215 | | | | {sshcom:ssh-x509-certs}? 216 | | | +---- client-auth 217 | | | | +---- username? string 218 | | | | +---- (auth-type)? 219 | | | | +--:(certificate) 220 | | | | | +---- certificate? leafref 221 | | | | | {sshcom:ssh-x509-certs}? 222 | | | | +--:(public-key) 223 | | | | | +---- public-key? 224 | | | | | -> /ks:keystore/keys/key/name 225 | | | | +--:(password) 226 | | | | +---- password? string 227 | | | +---- transport-params 228 | | | {ssh-client-transport-params-config}? 229 | | | +---- host-key 230 | | | | +---- host-key-alg* identityref 231 | | | +---- key-exchange 232 | | | | +---- key-exchange-alg* identityref 233 | | | +---- encryption 234 | | | | +---- encryption-alg* identityref 235 | | | +---- mac 236 | | | | +---- mac-alg* identityref 237 | | | +---- compression 238 | | | +---- compression-alg* identityref 239 | | +--:(tls) {tls-initiate}? 240 | | +---- tls 241 | | +---- endpoints 242 | | | +---- endpoint* [name] 243 | | | +---- name? string 244 | | | +---- address inet:host 245 | | | +---- port? inet:port-number 246 | | +---- server-auth 247 | | | +---- trusted-ca-certs? leafref 248 | | | +---- trusted-server-certs? leafref 249 | | +---- client-auth 250 | | | +---- (auth-type)? 251 | | | +--:(certificate) 252 | | | +---- certificate? leafref 253 | | +---- hello-params 254 | | {tls-client-hello-params-config}? 255 | | +---- tls-versions 256 | | | +---- tls-version* identityref 257 | | +---- cipher-suites 258 | | +---- cipher-suite* identityref 259 | +---- connection-type 260 | | +---- (connection-type)? 261 | | +--:(persistent-connection) 262 | | | +---- persistent! 263 | | | +---- idle-timeout? uint32 264 | | | +---- keep-alives 265 | | | +---- max-wait? uint16 266 | | | +---- max-attempts? uint8 267 | | +--:(periodic-connection) 268 | | +---- periodic! 269 | | +---- idle-timeout? uint16 270 | | +---- reconnect-timeout? uint16 271 | +---- reconnect-strategy 272 | +---- start-with? enumeration 273 | +---- max-attempts? uint8 274 +---- listen {listen}? 275 +---- max-sessions? uint16 276 +---- idle-timeout? uint16 277 +---- endpoint* [name] 278 +---- name? string 279 +---- (transport) 280 +--:(ssh) {ssh-listen}? 281 | +---- ssh 282 | +---- address? inet:ip-address 283 | +---- port? inet:port-number 284 | +---- server-auth 285 | | +---- trusted-ssh-host-keys? 286 | | | -> /ks:keystore/trusted-host-keys/name 287 | | +---- trusted-ca-certs? leafref 288 | | | {sshcom:ssh-x509-certs}? 289 | | +---- trusted-server-certs? leafref 290 | | {sshcom:ssh-x509-certs}? 291 | +---- client-auth 292 | | +---- username? string 293 | | +---- (auth-type)? 294 | | +--:(certificate) 295 | | | +---- certificate? leafref 296 | | | {sshcom:ssh-x509-certs}? 297 | | +--:(public-key) 298 | | | +---- public-key? 299 | | | -> /ks:keystore/keys/key/name 300 | | +--:(password) 301 | | +---- password? string 302 | +---- transport-params 303 | {ssh-client-transport-params-config}? 304 | +---- host-key 305 | | +---- host-key-alg* identityref 306 | +---- key-exchange 307 | | +---- key-exchange-alg* identityref 308 | +---- encryption 309 | | +---- encryption-alg* identityref 310 | +---- mac 311 | | +---- mac-alg* identityref 312 | +---- compression 313 | +---- compression-alg* identityref 314 +--:(tls) {tls-listen}? 315 +---- tls 316 +---- address? inet:ip-address 317 +---- port? inet:port-number 318 +---- server-auth 319 | +---- trusted-ca-certs? leafref 320 | +---- trusted-server-certs? leafref 321 +---- client-auth 322 | +---- (auth-type)? 323 | +--:(certificate) 324 | +---- certificate? leafref 325 +---- hello-params 326 {tls-client-hello-params-config}? 327 +---- tls-versions 328 | +---- tls-version* identityref 329 +---- cipher-suites 330 +---- cipher-suite* identityref 332 endpoints-container 333 +---- endpoints 334 +---- endpoint* [name] 335 +---- name? string 336 +---- address inet:host 337 +---- port? inet:port-number 339 2.2. Example Usage 341 The following example illustrates configuring a NETCONF client to 342 initiate connections, using both the SSH and TLS transport protocols, 343 as well as listening for call-home connections, again using both the 344 SSH and TLS transport protocols. 346 This example is consistent with the examples presented in Section 2.2 347 of [I-D.ietf-netconf-keystore]. 349 352 353 354 355 corp-fw1 356 357 358 359 corp-fw1.example.com 360
corp-fw1.example.com
361 362 363 corp-fw2.example.com 364
corp-fw2.example.com
365 366 367 368 deployment-specific-ca-certs 369 370 371 foobar 372 ex-rsa-key 373 374 375 376 378 379 380 381 Intranet-facing listener 382 383
11.22.33.44
384 385 deployment-specific-ca-certs 386 explicitly-trusted-server-certs 387 explicitly-trusted-ssh-host-keys 388 389 390 foobar 391 ex-rsa-key 392 393 394 395 396 397 2.3. YANG Model 399 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 401 file "ietf-netconf-client@2017-06-13.yang" 403 module ietf-netconf-client { 404 yang-version 1.1; 406 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-client"; 407 prefix "ncc"; 409 import ietf-inet-types { 410 prefix inet; 411 reference 412 "RFC 6991: Common YANG Data Types"; 413 } 415 import ietf-ssh-client { 416 prefix ss; 417 revision-date 2017-06-13; // stable grouping definitions 418 reference 419 "RFC YYYY: SSH Client and Server Models"; 420 } 422 import ietf-tls-client { 423 prefix ts; 424 revision-date 2017-06-13; // stable grouping definitions 425 reference 426 "RFC ZZZZ: TLS Client and Server Models"; 427 } 429 organization 430 "IETF NETCONF (Network Configuration) Working Group"; 432 contact 433 "WG Web: 434 WG List: 436 Author: Kent Watsen 437 439 Author: Gary Wu 440 "; 442 description 443 "This module contains a collection of YANG definitions for 444 configuring NETCONF clients. 446 Copyright (c) 2014 IETF Trust and the persons identified as 447 authors of the code. All rights reserved. 449 Redistribution and use in source and binary forms, with or 450 without modification, is permitted pursuant to, and subject 451 to the license terms contained in, the Simplified BSD 452 License set forth in Section 4.c of the IETF Trust's 453 Legal Provisions Relating to IETF Documents 454 (http://trustee.ietf.org/license-info). 456 This version of this YANG module is part of RFC XXXX; see 457 the RFC itself for full legal notices."; 459 revision "2017-06-13" { 460 description 461 "Initial version"; 462 reference 463 "RFC XXXX: NETCONF Client and Server Models"; 464 } 466 // Features 468 feature initiate { 469 description 470 "The 'initiate' feature indicates that the NETCONF client 471 supports initiating NETCONF connections to NETCONF servers 472 using at least one transport (e.g., SSH, TLS, etc.)."; 473 } 475 feature ssh-initiate { 476 description 477 "The 'ssh-initiate' feature indicates that the NETCONF client 478 supports initiating SSH connections to NETCONF servers."; 479 reference 480 "RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)"; 481 } 483 feature tls-initiate { 484 description 485 "The 'tls-initiate' feature indicates that the NETCONF client 486 supports initiating TLS connections to NETCONF servers."; 487 reference 488 "RFC 7589: Using the NETCONF Protocol over Transport 489 Layer Security (TLS) with Mutual X.509 490 Authentication"; 492 } 494 feature listen { 495 description 496 "The 'listen' feature indicates that the NETCONF client 497 supports opening a port to accept NETCONF server call 498 home connections using at least one transport (e.g., 499 SSH, TLS, etc.)."; 500 } 502 feature ssh-listen { 503 description 504 "The 'ssh-listen' feature indicates that the NETCONF client 505 supports opening a port to listen for incoming NETCONF 506 server call-home SSH connections."; 507 reference 508 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 509 } 511 feature tls-listen { 512 description 513 "The 'tls-listen' feature indicates that the NETCONF client 514 supports opening a port to listen for incoming NETCONF 515 server call-home TLS connections."; 516 reference 517 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 518 } 520 grouping netconf-client { 521 description 522 "Top-level grouping for NETCONF client configuration."; 524 container initiate { 525 if-feature initiate; 526 description 527 "Configures client initiating underlying TCP connections."; 528 list netconf-server { 529 key name; 530 description 531 "List of NETCONF servers the NETCONF client is to initiate 532 connections to."; 533 leaf name { 534 type string; 535 description 536 "An arbitrary name for the NETCONF server."; 537 } 538 choice transport { 539 mandatory true; 540 description 541 "Selects between available transports."; 543 case ssh { 544 if-feature ssh-initiate; 545 container ssh { 546 description 547 "Specifies SSH-specific transport configuration."; 548 uses endpoints-container { 549 refine endpoints/endpoint/port { 550 default 830; 551 } 552 } 553 uses ss:ssh-client-grouping; 554 } 555 } // end ssh 557 case tls { 558 if-feature tls-initiate; 559 container tls { 560 description 561 "Specifies TLS-specific transport configuration."; 562 uses endpoints-container { 563 refine endpoints/endpoint/port { 564 default 6513; 565 } 566 } 567 uses ts:tls-client-grouping { 568 refine "client-auth" { 569 must 'certificate'; 570 description 571 "NETCONF/TLS clients MUST pass a client certiticate."; 572 } 573 } 574 } 575 } // end tls 577 } // end transport 579 container connection-type { 580 description 581 "Indicates the kind of connection to use."; 582 choice connection-type { 583 description 584 "Selects between available connection types."; 585 case persistent-connection { 586 container persistent { 587 presence true; 588 description 589 "Maintain a persistent connection to the NETCONF 590 server. If the connection goes down, immediately 591 start trying to reconnect to it, using the 592 reconnection strategy. 594 This connection type minimizes any NETCONF server 595 to NETCONF client data-transfer delay, albeit at 596 the expense of holding resources longer."; 597 leaf idle-timeout { 598 type uint32; 599 units "seconds"; 600 default 86400; // one day; 601 description 602 "Specifies the maximum number of seconds that a 603 a NETCONF session may remain idle. A NETCONF 604 session will be dropped if it is idle for an 605 interval longer than this number of seconds. 606 If set to zero, then the client will never drop 607 a session because it is idle. Sessions that 608 have a notification subscription active are 609 never dropped."; 610 } 611 container keep-alives { 612 description 613 "Configures the keep-alive policy, to proactively 614 test the aliveness of the SSH/TLS server. An 615 unresponsive SSH/TLS server will be dropped after 616 approximately max-attempts * max-wait seconds."; 617 reference 618 "RFC 8071: NETCONF Call Home and RESTCONF Call 619 Home, Section 3.1, item S6"; 620 leaf max-wait { 621 type uint16 { 622 range "1..max"; 623 } 624 units seconds; 625 default 30; 626 description 627 "Sets the amount of time in seconds after which 628 if no data has been received from the SSH/TLS 629 server, a SSH/TLS-level message will be sent 630 to test the aliveness of the SSH/TLS server."; 631 } 632 leaf max-attempts { 633 type uint8; 634 default 3; 635 description 636 "Sets the maximum number of sequential keep-alive 637 messages that can fail to obtain a response from 638 the SSH/TLS server before assuming the SSH/TLS 639 server is no longer alive."; 640 } 641 } 642 } 643 } 644 case periodic-connection { 645 container periodic { 646 presence true; 647 description 648 "Periodically connect to the NETCONF server, so that 649 the NETCONF server may deliver messages pending for 650 the NETCONF client. The NETCONF server must close 651 the connection when it is ready to release it. Once 652 the connection has been closed, the NETCONF client 653 will restart its timer until the next connection."; 654 leaf idle-timeout { 655 type uint16; 656 units "seconds"; 657 default 300; // five minutes 658 description 659 "Specifies the maximum number of seconds that a 660 a NETCONF session may remain idle. A NETCONF 661 session will be dropped if it is idle for an 662 interval longer than this number of seconds. 663 If set to zero, then the server will never drop 664 a session because it is idle. Sessions that 665 have a notification subscription active are 666 never dropped."; 667 } 668 leaf reconnect-timeout { 669 type uint16 { 670 range "1..max"; 671 } 672 units minutes; 673 default 60; 674 description 675 "Sets the maximum amount of unconnected time the 676 NETCONF client will wait before re-establishing 677 a connection to the NETCONF server. The NETCONF 678 client may initiate a connection before this 679 time if desired (e.g., to set configuration)."; 680 } 681 } 682 } 683 } 685 } 686 container reconnect-strategy { 687 description 688 "The reconnection strategy directs how a NETCONF client 689 reconnects to a NETCONF server, after discovering its 690 connection to the server has dropped, even if due to a 691 reboot. The NETCONF client starts with the specified 692 endpoint and tries to connect to it max-attempts times 693 before trying the next endpoint in the list (round 694 robin)."; 695 leaf start-with { 696 type enumeration { 697 enum first-listed { 698 description 699 "Indicates that reconnections should start with 700 the first endpoint listed."; 701 } 702 enum last-connected { 703 description 704 "Indicates that reconnections should start with 705 the endpoint last connected to. If no previous 706 connection has ever been established, then the 707 first endpoint configured is used. NETCONF 708 clients SHOULD be able to remember the last 709 endpoint connected to across reboots."; 710 } 711 } 712 default first-listed; 713 description 714 "Specifies which of the NETCONF server's endpoints the 715 NETCONF client should start with when trying to connect 716 to the NETCONF server."; 717 } 718 leaf max-attempts { 719 type uint8 { 720 range "1..max"; 721 } 722 default 3; 723 description 724 "Specifies the number times the NETCONF client tries to 725 connect to a specific endpoint before moving on to the 726 next endpoint in the list (round robin)."; 727 } 728 } 729 } // end netconf-server 730 } // end initiate 732 container listen { 733 if-feature listen; 734 description 735 "Configures client accepting call-home TCP connections."; 737 leaf max-sessions { 738 type uint16; 739 default 0; 740 description 741 "Specifies the maximum number of concurrent sessions 742 that can be active at one time. The value 0 indicates 743 that no artificial session limit should be used."; 744 } 746 leaf idle-timeout { 747 type uint16; 748 units "seconds"; 749 default 3600; // one hour 750 description 751 "Specifies the maximum number of seconds that a NETCONF 752 session may remain idle. A NETCONF session will be dropped 753 if it is idle for an interval longer than this number of 754 seconds. If set to zero, then the server will never drop 755 a session because it is idle. Sessions that have a 756 notification subscription active are never dropped."; 757 } 759 list endpoint { 760 key name; 761 description 762 "List of endpoints to listen for NETCONF connections."; 763 leaf name { 764 type string; 765 description 766 "An arbitrary name for the NETCONF listen endpoint."; 767 } 768 choice transport { 769 mandatory true; 770 description 771 "Selects between available transports."; 772 case ssh { 773 if-feature ssh-listen; 774 container ssh { 775 description 776 "SSH-specific listening configuration for inbound 777 connections."; 778 leaf address { 779 type inet:ip-address; 780 description 781 "The IP address to listen for call-home connections."; 782 } 783 leaf port { 784 type inet:port-number; 785 default 4334; 786 description 787 "The port number to listen for call-home connections."; 788 } 789 uses ss:ssh-client-grouping; 790 } 791 } 792 case tls { 793 if-feature tls-listen; 794 container tls { 795 description 796 "TLS-specific listening configuration for inbound 797 connections."; 798 leaf address { 799 type inet:ip-address; 800 description 801 "The IP address to listen for call-home connections."; 802 } 803 leaf port { 804 type inet:port-number; 805 default 4335; 806 description 807 "The port number to listen for call-home connections."; 808 } 809 uses ts:tls-client-grouping { 810 refine "client-auth" { 811 must 'certificate'; 812 description 813 "NETCONF/TLS clients MUST pass a client certiticate."; 814 } 815 } 816 } 817 } 818 } // end transport 819 } // end endpoint 820 } // end listen 822 } // end netconf-client 824 grouping endpoints-container { 825 description 826 "This grouping is used to configure a set of NETCONF servers 827 a NETCONF client may initiate connections to."; 829 container endpoints { 830 description 831 "Container for the list of endpoints."; 832 list endpoint { 833 key name; 834 unique "address port"; 835 min-elements 1; 836 ordered-by user; 837 description 838 "A non-empty user-ordered list of endpoints for this NETCONF 839 client to try to connect to. Defining more than one enables 840 high-availability."; 841 leaf name { 842 type string; 843 description 844 "An arbitrary name for this endpoint."; 845 } 846 leaf address { 847 type inet:host; 848 mandatory true; 849 description 850 "The IP address or hostname of the endpoint. If a 851 hostname is configured and the DNS resolution results 852 in more than one IP address, the NETCONF client 853 will process the IP addresses as if they had been 854 explicitly configured in place of the hostname."; 855 } 856 leaf port { 857 type inet:port-number; 858 description 859 "The IP port for this endpoint. The NETCONF client will 860 use the IANA-assigned well-known port (set via a refine 861 statement when uses) if no value is specified."; 862 } 863 } 864 } 865 } 866 } 868 870 3. The NETCONF Server Model 872 The NETCONF server model presented in this section supports servers 873 both listening for connections as well as initiating call-home 874 connections. 876 This model supports both the SSH and TLS transport protocols, using 877 the SSH server and TLS server groupings defined in 878 [I-D.ietf-netconf-ssh-client-server] and 879 [I-D.ietf-netconf-tls-client-server] respectively. 881 All private keys and trusted certificates are held in the keystore 882 model defined in [I-D.ietf-netconf-keystore]. 884 YANG feature statements are used to enable implementations to 885 advertise which parts of the model the NETCONF server supports. 887 3.1. Tree Diagram 889 Note: all lines are folded at column 71 with no '\' character. 891 module: ietf-netconf-server 892 +--rw netconf-server 893 +--rw session-options 894 | +--rw hello-timeout? uint16 895 +--rw listen {listen}? 896 | +--rw max-sessions? uint16 897 | +--rw idle-timeout? uint16 898 | +--rw endpoint* [name] 899 | +--rw name string 900 | +--rw (transport) 901 | +--:(ssh) {ssh-listen}? 902 | | +--rw ssh 903 | | +--rw address? inet:ip-address 904 | | +--rw port? inet:port-number 905 | | +--rw host-keys 906 | | | +--rw host-key* [name] 907 | | | +--rw name string 908 | | | +--rw (host-key-type) 909 | | | +--:(public-key) 910 | | | | +--rw public-key? 911 | | | | -> /ks:keystore/keys/key/name 912 | | | +--:(certificate) 913 | | | +--rw certificate? leafref 914 | | | {sshcom:ssh-x509-certs}? 915 | | +--rw client-cert-auth {sshcom:ssh-x509-certs}? 916 | | | +--rw trusted-ca-certs? leafref 917 | | | +--rw trusted-client-certs? leafref 918 | | +--rw transport-params 919 | | {ssh-server-transport-params-config}? 920 | | +--rw host-key 921 | | | +--rw host-key-alg* identityref 922 | | +--rw key-exchange 923 | | | +--rw key-exchange-alg* identityref 924 | | +--rw encryption 925 | | | +--rw encryption-alg* identityref 926 | | +--rw mac 927 | | | +--rw mac-alg* identityref 928 | | +--rw compression 929 | | +--rw compression-alg* identityref 930 | +--:(tls) {tls-listen}? 931 | +--rw tls 932 | +--rw address? inet:ip-address 933 | +--rw port? inet:port-number 934 | +--rw certificates 935 | | +--rw certificate* [name] 936 | | +--rw name leafref 937 | +--rw client-auth 938 | | +--rw trusted-ca-certs? leafref 939 | | +--rw trusted-client-certs? leafref 940 | | +--rw cert-maps 941 | | +--rw cert-to-name* [id] 942 | | +--rw id uint32 943 | | +--rw fingerprint x509c2n:tls-fingerprint 944 | | +--rw map-type identityref 945 | | +--rw name string 946 | +--rw hello-params 947 | {tls-server-hello-params-config}? 948 | +--rw tls-versions 949 | | +--rw tls-version* identityref 950 | +--rw cipher-suites 951 | +--rw cipher-suite* identityref 952 +--rw call-home {call-home}? 953 +--rw netconf-client* [name] 954 +--rw name string 955 +--rw (transport) 956 | +--:(ssh) {ssh-call-home}? 957 | | +--rw ssh 958 | | +--rw endpoints 959 | | | +--rw endpoint* [name] 960 | | | +--rw name string 961 | | | +--rw address inet:host 962 | | | +--rw port? inet:port-number 963 | | +--rw host-keys 964 | | | +--rw host-key* [name] 965 | | | +--rw name string 966 | | | +--rw (host-key-type) 967 | | | +--:(public-key) 968 | | | | +--rw public-key? 969 | | | | -> /ks:keystore/keys/key/name 970 | | | +--:(certificate) 971 | | | +--rw certificate? leafref 972 | | | {sshcom:ssh-x509-certs}? 973 | | +--rw client-cert-auth {sshcom:ssh-x509-certs}? 974 | | | +--rw trusted-ca-certs? leafref 975 | | | +--rw trusted-client-certs? leafref 976 | | +--rw transport-params 977 | | {ssh-server-transport-params-config}? 978 | | +--rw host-key 979 | | | +--rw host-key-alg* identityref 980 | | +--rw key-exchange 981 | | | +--rw key-exchange-alg* identityref 982 | | +--rw encryption 983 | | | +--rw encryption-alg* identityref 984 | | +--rw mac 985 | | | +--rw mac-alg* identityref 986 | | +--rw compression 987 | | +--rw compression-alg* identityref 988 | +--:(tls) {tls-call-home}? 989 | +--rw tls 990 | +--rw endpoints 991 | | +--rw endpoint* [name] 992 | | +--rw name string 993 | | +--rw address inet:host 994 | | +--rw port? inet:port-number 995 | +--rw certificates 996 | | +--rw certificate* [name] 997 | | +--rw name leafref 998 | +--rw client-auth 999 | | +--rw trusted-ca-certs? leafref 1000 | | +--rw trusted-client-certs? leafref 1001 | | +--rw cert-maps 1002 | | +--rw cert-to-name* [id] 1003 | | +--rw id uint32 1004 | | +--rw fingerprint x509c2n:tls-fingerprint 1005 | | +--rw map-type identityref 1006 | | +--rw name string 1007 | +--rw hello-params 1008 | {tls-server-hello-params-config}? 1009 | +--rw tls-versions 1010 | | +--rw tls-version* identityref 1011 | +--rw cipher-suites 1012 | +--rw cipher-suite* identityref 1013 +--rw connection-type 1014 | +--rw (connection-type)? 1015 | +--:(persistent-connection) 1016 | | +--rw persistent! 1017 | | +--rw idle-timeout? uint32 1018 | | +--rw keep-alives 1019 | | +--rw max-wait? uint16 1020 | | +--rw max-attempts? uint8 1021 | +--:(periodic-connection) 1022 | +--rw periodic! 1023 | +--rw idle-timeout? uint16 1024 | +--rw reconnect-timeout? uint16 1025 +--rw reconnect-strategy 1026 +--rw start-with? enumeration 1027 +--rw max-attempts? uint8 1029 3.2. Example Usage 1031 The following example illustrates configuring a NETCONF server to 1032 listen for NETCONF client connections using both the SSH and TLS 1033 transport protocols, as well as configuring call-home to two NETCONF 1034 clients, one using SSH and the other using TLS. 1036 This example is consistent with the examples presented in Section 2.2 1037 of [I-D.ietf-netconf-keystore]. 1039 1043 1044 1045 1046 netconf/ssh 1047 1048
11.22.33.44
1049 1050 1051 public-key 1052 ex-rsa-key 1053 1054 1055 certificate 1056 builtin-idevid-cert 1057 1058 1059 1060 deployment-specific-ca-certs 1061 explicitly-trusted-client-certs 1062 1063 1064 1065 1066 netconf/tls 1067 1068
11.22.33.44
1069 1070 1071 tls-ec-cert 1072 1073 1074 1075 deployment-specific-ca-certs 1076 explicitly-trusted-client-certs 1077 1078 1079 1 1080 11:0A:05:11:00 1081 x509c2n:san-any 1082 1083 1084 2 1085 B3:4F:A1:8C:54 1086 x509c2n:specified 1087 scooby-doo 1088 1089 1090 1091 1092 1093 1095 1096 1097 1098 config-mgr 1099 1100 1101 1102 east-data-center 1103
11.22.33.44
1104 1105 1106 west-data-center 1107
55.66.77.88
1108 1109 1110 1111 1112 certificate 1113 builtin-idevid-cert 1114 1115 1116 1117 deployment-specific-ca-certs 1118 explicitly-trusted-client-certs 1119 1120 1121 1122 1123 300 1124 60 1125 1126 1127 1128 last-connected 1129 3 1130 1131 1132 1133 event-correlator 1134 1135 1136 1137 east-data-center 1138
22.33.44.55
1139 1140 1141 west-data-center 1142
33.44.55.66
1143 1144 1145 1146 1147 tls-ec-cert 1148 1149 1150 1151 deployment-specific-ca-certs 1152 explicitly-trusted-client-certs 1153 1154 1155 1 1156 11:0A:05:11:00 1157 x509c2n:san-any 1158 1159 1160 2 1161 B3:4F:A1:8C:54 1162 x509c2n:specified 1163 scooby-doo 1165 1166 1167 1168 1169 1170 1171 300 1172 1173 30 1174 3 1175 1176 1177 1178 1179 first-listed 1180 3 1181 1182 1183 1184 1186 3.3. YANG Model 1188 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 1190 file "ietf-netconf-server@2017-06-13.yang" 1192 module ietf-netconf-server { 1193 yang-version 1.1; 1195 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server"; 1196 prefix "ncs"; 1198 import ietf-inet-types { 1199 prefix inet; 1200 reference 1201 "RFC 6991: Common YANG Data Types"; 1202 } 1204 import ietf-x509-cert-to-name { 1205 prefix x509c2n; 1206 reference 1207 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1208 } 1210 import ietf-ssh-server { 1211 prefix ss; 1212 revision-date 2017-06-13; // stable grouping definitions 1213 reference 1214 "RFC YYYY: SSH Client and Server Models"; 1215 } 1217 import ietf-tls-server { 1218 prefix ts; 1219 revision-date 2017-06-13; // stable grouping definitions 1220 reference 1221 "RFC ZZZZ: TLS Client and Server Models"; 1222 } 1224 organization 1225 "IETF NETCONF (Network Configuration) Working Group"; 1227 contact 1228 "WG Web: 1229 WG List: 1231 Author: Kent Watsen 1232 "; 1234 description 1235 "This module contains a collection of YANG definitions for 1236 configuring NETCONF servers. 1238 Copyright (c) 2014 IETF Trust and the persons identified as 1239 authors of the code. All rights reserved. 1241 Redistribution and use in source and binary forms, with or 1242 without modification, is permitted pursuant to, and subject 1243 to the license terms contained in, the Simplified BSD 1244 License set forth in Section 4.c of the IETF Trust's 1245 Legal Provisions Relating to IETF Documents 1246 (http://trustee.ietf.org/license-info). 1248 This version of this YANG module is part of RFC XXXX; see 1249 the RFC itself for full legal notices."; 1251 revision "2017-06-13" { 1252 description 1253 "Initial version"; 1254 reference 1255 "RFC XXXX: NETCONF Client and Server Models"; 1256 } 1257 // Features 1259 feature listen { 1260 description 1261 "The 'listen' feature indicates that the NETCONF server 1262 supports opening a port to accept NETCONF client connections 1263 using at least one transport (e.g., SSH, TLS, etc.)."; 1264 } 1266 feature ssh-listen { 1267 description 1268 "The 'ssh-listen' feature indicates that the NETCONF server 1269 supports opening a port to accept NETCONF over SSH 1270 client connections."; 1271 reference 1272 "RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)"; 1273 } 1275 feature tls-listen { 1276 description 1277 "The 'tls-listen' feature indicates that the NETCONF server 1278 supports opening a port to accept NETCONF over TLS 1279 client connections."; 1280 reference 1281 "RFC 7589: Using the NETCONF Protocol over Transport 1282 Layer Security (TLS) with Mutual X.509 1283 Authentication"; 1284 } 1286 feature call-home { 1287 description 1288 "The 'call-home' feature indicates that the NETCONF server 1289 supports initiating NETCONF call home connections to NETCONF 1290 clients using at least one transport (e.g., SSH, TLS, etc.)."; 1291 reference 1292 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1293 } 1295 feature ssh-call-home { 1296 description 1297 "The 'ssh-call-home' feature indicates that the NETCONF 1298 server supports initiating a NETCONF over SSH call 1299 home connection to NETCONF clients."; 1300 reference 1301 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1302 } 1304 feature tls-call-home { 1305 description 1306 "The 'tls-call-home' feature indicates that the NETCONF 1307 server supports initiating a NETCONF over TLS call 1308 home connection to NETCONF clients."; 1309 reference 1310 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1311 } 1313 // top-level container (groupings below) 1314 container netconf-server { 1315 description 1316 "Top-level container for NETCONF server configuration."; 1318 container session-options { // SHOULD WE REMOVE THIS ALTOGETHER? 1319 description 1320 "NETCONF session options, independent of transport 1321 or connection strategy."; 1322 leaf hello-timeout { 1323 type uint16; 1324 units "seconds"; 1325 default 600; 1326 description 1327 "Specifies the maximum number of seconds that a SSH/TLS 1328 connection may wait for a hello message to be received. 1329 A connection will be dropped if no hello message is 1330 received before this number of seconds elapses. If set 1331 to zero, then the server will wait forever for a hello 1332 message."; 1333 } 1334 } 1336 container listen { 1337 if-feature listen; 1338 description 1339 "Configures listen behavior"; 1340 leaf max-sessions { 1341 type uint16; 1342 default 0; 1343 description 1344 "Specifies the maximum number of concurrent sessions 1345 that can be active at one time. The value 0 indicates 1346 that no artificial session limit should be used."; 1347 } 1348 leaf idle-timeout { 1349 type uint16; 1350 units "seconds"; 1351 default 3600; // one hour 1352 description 1353 "Specifies the maximum number of seconds that a NETCONF 1354 session may remain idle. A NETCONF session will be dropped 1355 if it is idle for an interval longer than this number of 1356 seconds. If set to zero, then the server will never drop 1357 a session because it is idle. Sessions that have a 1358 notification subscription active are never dropped."; 1359 } 1360 list endpoint { 1361 key name; 1362 description 1363 "List of endpoints to listen for NETCONF connections."; 1364 leaf name { 1365 type string; 1366 description 1367 "An arbitrary name for the NETCONF listen endpoint."; 1368 } 1370 choice transport { 1371 mandatory true; 1372 description 1373 "Selects between available transports."; 1374 case ssh { 1375 if-feature ssh-listen; 1376 container ssh { 1377 description 1378 "SSH-specific listening configuration for inbound 1379 connections."; 1380 leaf address { 1381 type inet:ip-address; 1382 description 1383 "The IP address of the interface to listen on. The 1384 SSH server will listen on all interfaces if no value 1385 is specified. Please note that some addresses have 1386 special meanings (e.g., '0.0.0.0' and '::')."; 1387 } 1388 leaf port { 1389 type inet:port-number; 1390 default 830; 1391 description 1392 "The local port number on this interface the SSH server 1393 listens on."; 1394 } 1395 uses ss:ssh-server-grouping; 1396 } 1397 } 1398 case tls { 1399 if-feature tls-listen; 1400 container tls { 1401 description 1402 "TLS-specific listening configuration for inbound 1403 connections."; 1404 leaf address { 1405 type inet:ip-address; 1406 description 1407 "The IP address of the interface to listen on. The 1408 TLS server will listen on all interfaces if no value 1409 is specified. Please note that some addresses have 1410 special meanings (e.g., '0.0.0.0' and '::')."; 1411 } 1412 leaf port { 1413 type inet:port-number; 1414 default 6513; 1415 description 1416 "The local port number on this interface the TLS server 1417 listens on."; 1418 } 1419 uses ts:tls-server-grouping { 1420 augment "client-auth" { 1421 description 1422 "Augments in the cert-to-name structure."; 1423 uses cert-maps-grouping; 1424 } 1425 } 1426 } 1427 } 1428 } 1429 } 1430 } 1432 container call-home { 1433 if-feature call-home; 1434 description 1435 "Configures call-home behavior"; 1436 list netconf-client { 1437 key name; 1438 description 1439 "List of NETCONF clients the NETCONF server is to initiate 1440 call-home connections to."; 1441 leaf name { 1442 type string; 1443 description 1444 "An arbitrary name for the remote NETCONF client."; 1445 } 1446 choice transport { 1447 mandatory true; 1448 description 1449 "Selects between available transports."; 1450 case ssh { 1451 if-feature ssh-call-home; 1452 container ssh { 1453 description 1454 "Specifies SSH-specific call-home transport 1455 configuration."; 1456 uses endpoints-container { 1457 refine endpoints/endpoint/port { 1458 default 4334; 1459 } 1460 } 1461 uses ss:ssh-server-grouping; 1462 } 1463 } 1464 case tls { 1465 if-feature tls-call-home; 1466 container tls { 1467 description 1468 "Specifies TLS-specific call-home transport 1469 configuration."; 1470 uses endpoints-container { 1471 refine endpoints/endpoint/port { 1472 default 4335; 1473 } 1474 } 1475 uses ts:tls-server-grouping { 1476 augment "client-auth" { 1477 description 1478 "Augments in the cert-to-name structure."; 1479 uses cert-maps-grouping; 1480 } 1481 } 1482 } 1483 } 1484 } 1485 container connection-type { 1486 description 1487 "Indicates the kind of connection to use."; 1488 choice connection-type { 1489 description 1490 "Selects between available connection types."; 1491 case persistent-connection { 1492 container persistent { 1493 presence true; 1494 description 1495 "Maintain a persistent connection to the NETCONF 1496 client. If the connection goes down, immediately 1497 start trying to reconnect to it, using the 1498 reconnection strategy. 1500 This connection type minimizes any NETCONF client 1501 to NETCONF server data-transfer delay, albeit at 1502 the expense of holding resources longer."; 1503 leaf idle-timeout { 1504 type uint32; 1505 units "seconds"; 1506 default 86400; // one day; 1507 description 1508 "Specifies the maximum number of seconds that a 1509 a NETCONF session may remain idle. A NETCONF 1510 session will be dropped if it is idle for an 1511 interval longer than this number of seconds. 1512 If set to zero, then the server will never drop 1513 a session because it is idle. Sessions that 1514 have a notification subscription active are 1515 never dropped."; 1516 } 1517 container keep-alives { 1518 description 1519 "Configures the keep-alive policy, to proactively 1520 test the aliveness of the SSH/TLS client. An 1521 unresponsive SSH/TLS client will be dropped after 1522 approximately max-attempts * max-wait seconds."; 1523 reference 1524 "RFC 8071: NETCONF Call Home and RESTCONF Call 1525 Home, Section 3.1, item S6"; 1526 leaf max-wait { 1527 type uint16 { 1528 range "1..max"; 1529 } 1530 units seconds; 1531 default 30; 1532 description 1533 "Sets the amount of time in seconds after which 1534 if no data has been received from the SSH/TLS 1535 client, a SSH/TLS-level message will be sent 1536 to test the aliveness of the SSH/TLS client."; 1537 } 1538 leaf max-attempts { 1539 type uint8; 1540 default 3; 1541 description 1542 "Sets the maximum number of sequential keep-alive 1543 messages that can fail to obtain a response from 1544 the SSH/TLS client before assuming the SSH/TLS 1545 client is no longer alive."; 1546 } 1547 } 1548 } 1549 } 1550 case periodic-connection { 1551 container periodic { 1552 presence true; 1553 description 1554 "Periodically connect to the NETCONF client, so that 1555 the NETCONF client may deliver messages pending for 1556 the NETCONF server. The NETCONF client must close 1557 the connection when it is ready to release it. Once 1558 the connection has been closed, the NETCONF server 1559 will restart its timer until the next connection."; 1560 leaf idle-timeout { 1561 type uint16; 1562 units "seconds"; 1563 default 300; // five minutes 1564 description 1565 "Specifies the maximum number of seconds that a 1566 a NETCONF session may remain idle. A NETCONF 1567 session will be dropped if it is idle for an 1568 interval longer than this number of seconds. 1569 If set to zero, then the server will never drop 1570 a session because it is idle. Sessions that 1571 have a notification subscription active are 1572 never dropped."; 1573 } 1574 leaf reconnect-timeout { 1575 type uint16 { 1576 range "1..max"; 1577 } 1578 units minutes; 1579 default 60; 1580 description 1581 "Sets the maximum amount of unconnected time the 1582 NETCONF server will wait before re-establishing 1583 a connection to the NETCONF client. The NETCONF 1584 server may initiate a connection before this 1585 time if desired (e.g., to deliver an event 1586 notification message)."; 1587 } 1588 } 1589 } 1590 } 1591 } 1592 container reconnect-strategy { 1593 description 1594 "The reconnection strategy directs how a NETCONF server 1595 reconnects to a NETCONF client, after discovering its 1596 connection to the client has dropped, even if due to a 1597 reboot. The NETCONF server starts with the specified 1598 endpoint and tries to connect to it max-attempts times 1599 before trying the next endpoint in the list (round 1600 robin)."; 1601 leaf start-with { 1602 type enumeration { 1603 enum first-listed { 1604 description 1605 "Indicates that reconnections should start with 1606 the first endpoint listed."; 1607 } 1608 enum last-connected { 1609 description 1610 "Indicates that reconnections should start with 1611 the endpoint last connected to. If no previous 1612 connection has ever been established, then the 1613 first endpoint configured is used. NETCONF 1614 servers SHOULD be able to remember the last 1615 endpoint connected to across reboots."; 1616 } 1617 } 1618 default first-listed; 1619 description 1620 "Specifies which of the NETCONF client's endpoints the 1621 NETCONF server should start with when trying to connect 1622 to the NETCONF client."; 1623 } 1624 leaf max-attempts { 1625 type uint8 { 1626 range "1..max"; 1627 } 1628 default 3; 1629 description 1630 "Specifies the number times the NETCONF server tries to 1631 connect to a specific endpoint before moving on to the 1632 next endpoint in the list (round robin)."; 1633 } 1634 } 1635 } 1636 } 1637 } 1638 grouping cert-maps-grouping { 1639 description 1640 "A grouping that defines a container around the 1641 cert-to-name structure defined in RFC 7407."; 1642 container cert-maps { 1643 uses x509c2n:cert-to-name; 1644 description 1645 "The cert-maps container is used by a TLS-based NETCONF 1646 server to map the NETCONF client's presented X.509 1647 certificate to a NETCONF username. If no matching and 1648 valid cert-to-name list entry can be found, then the 1649 NETCONF server MUST close the connection, and MUST NOT 1650 accept NETCONF messages over it."; 1651 reference 1652 "RFC WWWW: NETCONF over TLS, Section 7"; 1653 } 1654 } 1656 grouping endpoints-container { 1657 description 1658 "This grouping is used to configure a set of NETCONF clients 1659 a NETCONF server may initiate call-home connections to."; 1660 container endpoints { 1661 description 1662 "Container for the list of endpoints."; 1663 list endpoint { 1664 key name; 1665 unique "address port"; 1666 min-elements 1; 1667 ordered-by user; 1668 description 1669 "A non-empty user-ordered list of endpoints for this NETCONF 1670 server to try to connect to. Defining more than one enables 1671 high-availability."; 1672 leaf name { 1673 type string; 1674 description 1675 "An arbitrary name for this endpoint."; 1676 } 1677 leaf address { 1678 type inet:host; 1679 mandatory true; 1680 description 1681 "The IP address or hostname of the endpoint. If a 1682 hostname is configured and the DNS resolution results 1683 in more than one IP address, the NETCONF server 1684 will process the IP addresses as if they had been 1685 explicitly configured in place of the hostname."; 1686 } 1687 leaf port { 1688 type inet:port-number; 1689 description 1690 "The IP port for this endpoint. The NETCONF server will 1691 use the IANA-assigned well-known port (set via a refine 1692 statement when uses) if no value is specified."; 1693 } 1694 } 1695 } 1696 } 1698 } 1700 1702 4. Design Considerations 1704 Editorial: this section is a hold over from before, previously called 1705 "Objectives". It was only written two support the "server" (not the 1706 "client"). The question is if it's better to add the missing 1707 "client" parts, or remove this section altogether. 1709 The primary purpose of the YANG modules defined herein is to enable 1710 the configuration of the NETCONF client and servers. This scope 1711 includes the following objectives: 1713 4.1. Support all NETCONF transports 1715 The YANG module should support all current NETCONF transports, namely 1716 NETCONF over SSH [RFC6242], NETCONF over TLS [RFC7589], and to be 1717 extensible to support future transports as necessary. 1719 Because implementations may not support all transports, the modules 1720 should use YANG "feature" statements so that implementations can 1721 accurately advertise which transports are supported. 1723 4.2. Enable each transport to select which keys to use 1725 Servers may have a multiplicity of host-keys or server-certificates 1726 from which subsets may be selected for specific uses. For instance, 1727 a NETCONF server may want to use one set of SSH host-keys when 1728 listening on port 830, and a different set of SSH host-keys when 1729 calling home. The data models provided herein should enable 1730 configuration of which keys to use on a per-use basis. 1732 4.3. Support authenticating NETCONF clients certificates 1734 When a certificate is used to authenticate a NETCONF client, there is 1735 a need to configure the server to know how to authenticate the 1736 certificates. The server should be able to authenticate the client's 1737 certificate either by using path-validation to a configured trust 1738 anchor or by matching the client-certificate to one previously 1739 configured. 1741 4.4. Support mapping authenticated NETCONF client certificates to 1742 usernames 1744 When a client certificate is used for TLS client authentication, the 1745 NETCONF server must be able to derive a username from the 1746 authenticated certificate. Thus the modules defined herein should 1747 enable this mapping to be configured. 1749 4.5. Support both listening for connections and call home 1751 The NETCONF protocols were originally defined as having the server 1752 opening a port to listen for client connections. More recently the 1753 NETCONF working group defined support for call-home ([RFC8071]), 1754 enabling the server to initiate the connection to the client. Thus 1755 the modules defined herein should enable configuration for both 1756 listening for connections and calling home. Because implementations 1757 may not support both listening for connections and calling home, YANG 1758 "feature" statements should be used so that implementation can 1759 accurately advertise the connection types it supports. 1761 4.6. For Call Home connections 1763 The following objectives only pertain to call home connections. 1765 4.6.1. Support more than one NETCONF client 1767 A NETCONF server may be managed by more than one NETCONF client. For 1768 instance, a deployment may have one client for provisioning and 1769 another for fault monitoring. Therefore, when it is desired for a 1770 server to initiate call home connections, it should be able to do so 1771 to more than one client. 1773 4.6.2. Support NETCONF clients having more than one endpoint 1775 A NETCONF client managing a NETCONF server may implement a high- 1776 availability strategy employing a multiplicity of active and/or 1777 passive endpoint. Therefore, when it is desired for a server to 1778 initiate call home connections, it should be able to connect to any 1779 of the client's endpoints. 1781 4.6.3. Support a reconnection strategy 1783 Assuming a NETCONF client has more than one endpoint, then it becomes 1784 necessary to configure how a NETCONF server should reconnect to the 1785 client should it lose its connection to one the client's endpoints. 1786 For instance, the NETCONF server may start with first endpoint 1787 defined in a user-ordered list of endpoints or with the last 1788 endpoints it was connected to. 1790 4.6.4. Support both persistent and periodic connections 1792 NETCONF clients may vary greatly on how frequently they need to 1793 interact with a NETCONF server, how responsive interactions need to 1794 be, and how many simultaneous connections they can support. Some 1795 clients may need a persistent connection to servers to optimize real- 1796 time interactions, while others prefer periodic interactions in order 1797 to minimize resource requirements. Therefore, when it is necessary 1798 for server to initiate connections, it should be configurable if the 1799 connection is persistent or periodic. 1801 4.6.5. Reconnection strategy for periodic connections 1803 The reconnection strategy should apply to both persistent and 1804 periodic connections. How it applies to periodic connections becomes 1805 clear when considering that a periodic "connection" is a logical 1806 connection to a single server. That is, the periods of 1807 unconnectedness are intentional as opposed to due to external 1808 reasons. A periodic "connection" should always reconnect to the same 1809 server until it is no longer able to, at which time the reconnection 1810 strategy guides how to connect to another server. 1812 4.6.6. Keep-alives for persistent connections 1814 If a persistent connection is desired, it is the responsibility of 1815 the connection initiator to actively test the "aliveness" of the 1816 connection. The connection initiator must immediately work to 1817 reestablish a persistent connection as soon as the connection is 1818 lost. How often the connection should be tested is driven by NETCONF 1819 client requirements, and therefore keep-alive settings should be 1820 configurable on a per-client basis. 1822 4.6.7. Customizations for periodic connections 1824 If a periodic connection is desired, it is necessary for the NETCONF 1825 server to know how often it should connect. This frequency 1826 determines the maximum amount of time a NETCONF client may have to 1827 wait to send data to a server. A server may connect to a client 1828 before this interval expires if desired (e.g., to send data to a 1829 client). 1831 5. Security Considerations 1833 A denial of service (DoS) attack MAY occur if the NETCONF server 1834 limits the maximum number of NETCONF sessions it will accept (i.e. 1835 the 'max-sessions' field in the ietf-netconf-server module is not 1836 zero) and either the "hello-timeout" or "idle-timeout" fields in 1837 ietf-netconf-server module have been set to indicate the NETCONF 1838 server should wait forever (i.e. set to zero). 1840 The YANG module defined in this document uses groupings defined in 1841 [I-D.ietf-netconf-ssh-client-server] and 1842 [I-D.ietf-netconf-tls-client-server]. Please see the Security 1843 Considerations section in those documents for concerns related those 1844 groupings. 1846 The YANG module defined in this document is designed to be accessed 1847 via YANG based management protocols, such as NETCONF [RFC6241] and 1848 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1849 implement secure transport layers (e.g., SSH, TLS) with mutual 1850 authentication. 1852 The NETCONF access control model (NACM) [RFC6536] provides the means 1853 to restrict access for particular users to a pre-configured subset of 1854 all available protocol operations and content. 1856 There are a number of data nodes defined in this YANG module that are 1857 writable/creatable/deletable (i.e., config true, which is the 1858 default). These data nodes may be considered sensitive or vulnerable 1859 in some network environments. Write operations (e.g., edit-config) 1860 to these data nodes without proper protection can have a negative 1861 effect on network operations. These are the subtrees and data nodes 1862 and their sensitivity/vulnerability: 1864 NONE 1866 Some of the readable data nodes in this YANG module may be considered 1867 sensitive or vulnerable in some network environments. It is thus 1868 important to control read access (e.g., via get, get-config, or 1869 notification) to these data nodes. These are the subtrees and data 1870 nodes and their sensitivity/vulnerability: 1872 NONE 1874 Some of the RPC operations in this YANG module may be considered 1875 sensitive or vulnerable in some network environments. It is thus 1876 important to control access to these operations. These are the 1877 operations and their sensitivity/vulnerability: 1879 NONE 1881 6. IANA Considerations 1883 6.1. The IETF XML Registry 1885 This document registers two URIs in the IETF XML registry [RFC3688]. 1886 Following the format in [RFC3688], the following registrations are 1887 requested: 1889 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-client 1890 Registrant Contact: The NETCONF WG of the IETF. 1891 XML: N/A, the requested URI is an XML namespace. 1893 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1894 Registrant Contact: The NETCONF WG of the IETF. 1895 XML: N/A, the requested URI is an XML namespace. 1897 6.2. The YANG Module Names Registry 1899 This document registers two YANG modules in the YANG Module Names 1900 registry [RFC7950]. Following the format in [RFC7950], the the 1901 following registrations are requested: 1903 name: ietf-netconf-client 1904 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-client 1905 prefix: ncc 1906 reference: RFC XXXX 1908 name: ietf-netconf-server 1909 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1910 prefix: ncs 1911 reference: RFC XXXX 1913 7. Acknowledgements 1915 The authors would like to thank for following for lively discussions 1916 on list and in the halls (ordered by last name): Andy Bierman, Martin 1917 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1918 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1919 Phil Shafer, Sean Turner, and Bert Wijnen. 1921 Juergen Schoenwaelder and was partly funded by Flamingo, a Network of 1922 Excellence project (ICT-318488) supported by the European Commission 1923 under its Seventh Framework Programme. 1925 8. References 1927 8.1. Normative References 1929 [I-D.ietf-netconf-keystore] 1930 Watsen, K., "Keystore Model", draft-ietf-netconf- 1931 keystore-01 (work in progress), March 2017. 1933 [I-D.ietf-netconf-ssh-client-server] 1934 Watsen, K. and G. Wu, "SSH Client and Server Models", 1935 draft-ietf-netconf-ssh-client-server-02 (work in 1936 progress), March 2017. 1938 [I-D.ietf-netconf-tls-client-server] 1939 Watsen, K. and G. Wu, "TLS Client and Server Models", 1940 draft-ietf-netconf-tls-client-server-02 (work in 1941 progress), March 2017. 1943 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1944 Requirement Levels", BCP 14, RFC 2119, 1945 DOI 10.17487/RFC2119, March 1997, 1946 . 1948 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1949 and A. Bierman, Ed., "Network Configuration Protocol 1950 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1951 . 1953 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1954 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1955 . 1957 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1958 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1959 . 1961 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1962 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1963 December 2014, . 1965 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1966 NETCONF Protocol over Transport Layer Security (TLS) with 1967 Mutual X.509 Authentication", RFC 7589, 1968 DOI 10.17487/RFC7589, June 2015, 1969 . 1971 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1972 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1973 . 1975 8.2. Informative References 1977 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1978 DOI 10.17487/RFC3688, January 2004, 1979 . 1981 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1982 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1983 January 2006, . 1985 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1986 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1987 January 2006, . 1989 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1990 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1991 January 2006, . 1993 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1994 (TLS) Protocol Version 1.2", RFC 5246, 1995 DOI 10.17487/RFC5246, August 2008, 1996 . 1998 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1999 Protocol (NETCONF) Access Control Model", RFC 6536, 2000 DOI 10.17487/RFC6536, March 2012, 2001 . 2003 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2004 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2005 . 2007 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2008 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2009 . 2011 Appendix A. Change Log 2013 A.1. server-model-09 to 00 2015 o This draft was split out from draft-ietf-netconf-server-model-09. 2017 o Added in previously missing ietf-netconf-client module. 2019 o Added in new features 'listen' and 'call-home' so future 2020 transports can be augmented in. 2022 A.2. 00 to 01 2024 o Renamed "keychain" to "keystore". 2026 A.3. 01 to 02 2028 o Added to ietf-netconf-client ability to connected to a cluster of 2029 endpoints, including a reconnection-strategy. 2031 o Added to ietf-netconf-client the ability to configure connection- 2032 type and also keep-alive strategy. 2034 o Updated both modules to accomodate new groupings in the ssh/tls 2035 drafts. 2037 A.4. 02 to 03 2039 o Refined use of tls-client-grouping to add a must statement 2040 indicating that the TLS client must specify a client-certificate. 2042 o Changed 'netconf-client' to be a grouping (not a container). 2044 Authors' Addresses 2046 Kent Watsen 2047 Juniper Networks 2049 EMail: kwatsen@juniper.net 2051 Gary Wu 2052 Cisco Networks 2054 EMail: garywu@cisco.com 2055 Juergen Schoenwaelder 2056 Jacobs University Bremen 2058 EMail: j.schoenwaelder@jacobs-university.de