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