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