idnits 2.17.1 draft-ietf-netconf-server-model-06.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 6 instances of too long lines in the document, the longest one being 2 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 408 has weird spacing: '...address ine...' == Line 417 has weird spacing: '...address ine...' == Line 484 has weird spacing: '...erprint x50...' == Line 1188 has weird spacing: '...address ine...' == Line 1235 has weird spacing: '...erprint x50...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 2, 2015) is 3370 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC6187' is defined on line 1909, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 2 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 J. Schoenwaelder 5 Expires: August 6, 2015 Jacobs University Bremen 6 February 2, 2015 8 NETCONF Server and RESTCONF Server Configuration Models 9 draft-ietf-netconf-server-model-06 11 Abstract 13 This draft defines a NETCONF server configuration data model and a 14 RESTCONF server configuration data model. These data models enable 15 configuration of the NETCONF and RESTCONF services themselves, 16 including which transports are supported, what ports the servers 17 listens on, whether call-home is supported, and associated 18 parameters. 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. Please note 25 that no other RFC Editor instructions are specified anywhere else in 26 this document. 28 This document contains references to other drafts in progress, both 29 in the Normative References section, as well as in body text 30 throughout. Please update the following references to reflect their 31 final RFC assignments: 33 o draft-ietf-netconf-rfc5539bis 35 o draft-ietf-netconf-restconf 37 o draft-ietf-netconf-call-home 39 Artwork in this document contains shorthand references to drafts in 40 progress. Please apply the following replacements: 42 o "VVVV" --> the assigned RFC value for this draft 44 o "WWWW" --> the assigned RFC value for draft-ietf-netconf- 45 rfc5539bis 47 o "XXXX" --> the assigned RFC value for draft-ietf-netconf-restconf 48 o "YYYY" --> the assigned RFC value for draft-ietf-netconf-call-home 50 o "ZZZZ" --> the assigned RFC value for draft-thomson-httpbis-cant 52 Artwork in this document contains placeholder values for ports 53 pending IANA assignment from "draft-ietf-netconf-call-home". Please 54 apply the following replacements: 56 o "7777" --> the assigned port value for "netconf-ch-ssh" 58 o "8888" --> the assigned port value for "netconf-ch-tls" 60 o "9999" --> the assigned port value for "restconf-ch-tls" 62 Artwork in this document contains placeholder values for the date of 63 publication of this draft. Please apply the following replacement: 65 o "2015-02-02" --> the publication date of this draft 67 The following two Appendix sections are to be removed prior to 68 publication: 70 o Appendix B. Change Log 72 o Appendix C. Open Issues 74 Status of This Memo 76 This Internet-Draft is submitted in full conformance with the 77 provisions of BCP 78 and BCP 79. 79 Internet-Drafts are working documents of the Internet Engineering 80 Task Force (IETF). Note that other groups may also distribute 81 working documents as Internet-Drafts. The list of current Internet- 82 Drafts is at http://datatracker.ietf.org/drafts/current/. 84 Internet-Drafts are draft documents valid for a maximum of six months 85 and may be updated, replaced, or obsoleted by other documents at any 86 time. It is inappropriate to use Internet-Drafts as reference 87 material or to cite them other than as "work in progress." 89 This Internet-Draft will expire on August 6, 2015. 91 Copyright Notice 93 Copyright (c) 2015 IETF Trust and the persons identified as the 94 document authors. All rights reserved. 96 This document is subject to BCP 78 and the IETF Trust's Legal 97 Provisions Relating to IETF Documents 98 (http://trustee.ietf.org/license-info) in effect on the date of 99 publication of this document. Please review these documents 100 carefully, as they describe your rights and restrictions with respect 101 to this document. Code Components extracted from this document must 102 include Simplified BSD License text as described in Section 4.e of 103 the Trust Legal Provisions and are provided without warranty as 104 described in the Simplified BSD License. 106 Table of Contents 108 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 109 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 110 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4 111 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 112 2.1. Support all NETCONF and RESTCONF transports . . . . . . . 5 113 2.2. Enable each transport to select which keys to use . . . . 5 114 2.3. Support authenticating NETCONF/RESTCONF clients 115 certificates . . . . . . . . . . . . . . . . . . . . . . 5 116 2.4. Support mapping authenticated NETCONF/RESTCONF client 117 certificates to usernames . . . . . . . . . . . . . . . . 6 118 2.5. Support both Listening for connections and Call Home . . 6 119 2.6. For Call Home connections . . . . . . . . . . . . . . . . 6 120 2.6.1. Support more than one northbound application . . . . 6 121 2.6.2. Support applications having more than one server . . 6 122 2.6.3. Support a reconnection strategy . . . . . . . . . . . 6 123 2.6.4. Support both persistent and periodic connections . . 7 124 2.6.5. Reconnection strategy for periodic connections . . . 7 125 2.6.6. Keep-alives for persistent connections . . . . . . . 7 126 2.6.7. Customizations for periodic connections . . . . . . . 7 127 3. The NETCONF Server Configuration Model . . . . . . . . . . . 8 128 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 129 3.1.1. The "session-options" subtree . . . . . . . . . . . . 8 130 3.1.2. The "listen" subtree . . . . . . . . . . . . . . . . 8 131 3.1.3. The "call-home" subtree . . . . . . . . . . . . . . . 9 132 3.1.4. The "ssh" subtree . . . . . . . . . . . . . . . . . . 11 133 3.1.5. The "tls" subtree . . . . . . . . . . . . . . . . . . 11 134 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12 135 4. The RESTCONF Server Configuration Model . . . . . . . . . . . 25 136 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 25 137 4.1.1. The "listen" subtree . . . . . . . . . . . . . . . . 25 138 4.1.2. The "call-home" subtree . . . . . . . . . . . . . . . 26 139 4.1.3. The "client-cert-auth" subtree . . . . . . . . . . . 28 140 4.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 28 141 5. Implementation strategy for keep-alives . . . . . . . . . . . 39 142 5.1. Keep-alives for SSH . . . . . . . . . . . . . . . . . . . 39 143 5.2. Keep-alives for TLS . . . . . . . . . . . . . . . . . . . 40 145 6. Security Considerations . . . . . . . . . . . . . . . . . . . 40 146 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 147 8. Other Considerations . . . . . . . . . . . . . . . . . . . . 41 148 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 42 149 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 150 10.1. Normative References . . . . . . . . . . . . . . . . . . 42 151 10.2. Informative References . . . . . . . . . . . . . . . . . 43 152 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 44 153 A.1. NETCONF Configuration using SSH Transport . . . . . . . . 44 154 A.2. NETCONF Configuration using TLS Transport . . . . . . . . 45 155 A.3. RESTCONF Configuration using TLS Transport . . . . . . . 47 156 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 47 157 B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 47 158 B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 48 159 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 48 160 B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 48 161 B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 48 162 B.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 49 163 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 49 165 1. Introduction 167 This draft defines a NETCONF [RFC6241] server configuration data 168 model and a RESTCONF [draft-ietf-netconf-restconf] server 169 configuration data model. These data models enable configuration of 170 the NETCONF and RESTCONF services themselves, including which 171 transports are supported, what ports the servers listens on, whether 172 call-home is supported, and associated parameters. 174 1.1. Terminology 176 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in RFC 2119 [RFC2119]. 180 1.2. Tree Diagrams 182 A simplified graphical representation of the data models is used in 183 this document. The meaning of the symbols in these diagrams is as 184 follows: 186 o Brackets "[" and "]" enclose list keys. 188 o Braces "{" and "}" enclose feature names, and indicate that the 189 named feature must be present for the subtree to be present. 191 o Abbreviations before data node names: "rw" means configuration 192 (read-write) and "ro" state data (read-only). 194 o Symbols after data node names: "?" means an optional node, "!" 195 means a presence container, and "*" denotes a list and leaf-list. 197 o Parentheses enclose choice and case nodes, and case nodes are also 198 marked with a colon (":"). 200 o Ellipsis ("...") stands for contents of subtrees that are not 201 shown. 203 2. Objectives 205 The primary purpose of the YANG modules defined herein is to enable 206 the configuration of the NETCONF and RESTCONF services on a network 207 element. This scope includes the following objectives: 209 2.1. Support all NETCONF and RESTCONF transports 211 The YANG module should support all current NETCONF and RESTCONF 212 transports, namely NETCONF over SSH [RFC6242], NETCONF over TLS 213 [draft-ietf-netconf-rfc5539bis], and RESTCONF over TLS 214 [draft-ietf-netconf-restconf], and to be extensible to support future 215 transports as necessary. 217 Because implementations may not support all transports, the module 218 should use YANG "feature" statements so that implementations can 219 accurately advertise which transports are supported. 221 2.2. Enable each transport to select which keys to use 223 Servers may have a multiplicity of host-keys or server-certificates 224 from which subsets may be selected for specific uses. For instance, 225 a NETCONF server may want to use one set of SSH host-keys when 226 listening on port 830, and a different set of SSH host-keys when 227 calling home. The data models provided herein should enable 228 configuration of which keys to use on a per-use basis. 230 2.3. Support authenticating NETCONF/RESTCONF clients certificates 232 When a certificate is used to authenticate a NETCONF or RESTCONF 233 client, there is a need to configure the server to know how to 234 authenticate the certificates. The server should be able to 235 authenticate the client's certificate either by using path-validation 236 to a configured trust anchor or by matching the client-certificate to 237 one previously configured. 239 2.4. Support mapping authenticated NETCONF/RESTCONF client certificates 240 to usernames 242 When a client certifcate is used for TLS transport-level 243 authentication, the NETCONF/RESTCONF server must be able to derive a 244 username from the authenticated certifcate. Thus the modules defined 245 herein should enable this mapping to be configured. 247 2.5. Support both Listening for connections and Call Home 249 The NETCONF and RESTCONF protocols were originally defined as having 250 the server opening a port to listen for client connections. More 251 recently the NETCONF working group defined support for call-home 252 ([draft-ietf-netconf-call-home]), enabling the server to initiate the 253 connection to the client, for both the NETCONF and RESTCONF 254 protocols. Thus the modules defined herein should enable 255 configuration for both listening for connections and calling home. 256 Because implementations may not support both listening for 257 connections and calling home, YANG "feature" statements should be 258 used so that implementation can accurately advertise the connection 259 types it supports. 261 2.6. For Call Home connections 263 The following objectives only pertain to call home connections. 265 2.6.1. Support more than one northbound application 267 A device may be managed by more than one northbound application. For 268 instance, a deployment may have one application for provisioning and 269 another for fault monitoring. Therefore, when it is desired for a 270 device to initiate call home connections, it should be able to do so 271 to more than one application. 273 2.6.2. Support applications having more than one server 275 An application managing a device may implement a high-availability 276 strategy employing a multiplicity of active and/or passive servers. 277 Therefore, when it is desired for a device to initiate call home 278 connections, it should be able to connect to any of the application's 279 servers. 281 2.6.3. Support a reconnection strategy 283 Assuming an application has more than one server, then it becomes 284 necessary to configure how a device should reconnect to the 285 application should it lose its connection to the application's 286 servers. Of primary interest is if the device should start with 287 first server defined in a user-ordered list of servers or with the 288 last server it was connected to. Secondary settings might specify 289 the frequency of attempts and number of attempts per server. 290 Therefore, a reconnection strategy should be configurable. 292 2.6.4. Support both persistent and periodic connections 294 Applications may vary greatly on how frequently they need to interact 295 with a device, how responsive interactions with devices need to be, 296 and how many simultaneous connections they can support. Some 297 applications may need a persistent connection to devices to optimize 298 real-time interactions, while others prefer periodic interactions in 299 order to minimize resource requirements. Therefore, when it is 300 necessary for devices to initiate connections, the type of connection 301 desired should be configurable. 303 2.6.5. Reconnection strategy for periodic connections 305 The reconnection strategy should apply to both persistent and 306 periodic connections. How it applies to periodic connections becomes 307 clear when considering that a periodic "connection" is a logical 308 connection to a single server. That is, the periods of 309 unconnectedness are intentional as opposed to due to external 310 reasons. A periodic "connection" should always reconnect to the same 311 server until it is no longer able to, at which time the reconnection 312 strategy guides how to connect to another server. 314 2.6.6. Keep-alives for persistent connections 316 If a persistent connection is desired, it is the responsibility of 317 the connection initiator to actively test the "aliveness" of the 318 connection. The connection initiator must immediately work to 319 reestablish a persistent connection as soon as the connection is 320 lost. How often the connection should be tested is driven by 321 application requirements, and therefore keep-alive settings should be 322 configurable on a per-application basis. 324 2.6.7. Customizations for periodic connections 326 If a periodic connection is desired, it is necessary for the device 327 to know how often it should connect. This delay essentially 328 determines how long the application might have to wait to send data 329 to the device. This setting does not constrain how often the device 330 must wait to send data to the application, as the device should 331 immediately connect to the application whenever it has data to send 332 to it. 334 A common communication pattern is that one data transmission is many 335 times closely followed by another. For instance, if the device needs 336 to send a notification message, there's a high probability that it 337 will send another shortly thereafter. Likewise, the application may 338 have a sequence of pending messages to send. Thus, it should be 339 possible for a device to hold a connection open until some amount of 340 time of no data being transmitted as transpired. 342 3. The NETCONF Server Configuration Model 344 3.1. Overview 346 3.1.1. The "session-options" subtree 348 module: ietf-netconf-server 349 +--rw netconf-server 350 +--rw session-options 351 +--rw hello-timeout? uint32 352 +--rw idle-timeout? uint32 354 The above subtree illustrates how the ietf-netconf-server YANG module 355 enables configuration of NETCONF session options, independent of any 356 transport or connection strategy. Please see the YANG module 357 (Section 3.2) for a complete description of these configuration 358 knobs. 360 3.1.2. The "listen" subtree 361 module: ietf-netconf-server 362 +--rw netconf-server 363 +--rw listen {listen}? 364 +--rw max-sessions? uint16 365 +--rw endpoint* [name] 366 +--rw name string 367 +--rw (transport) 368 | +--:(ssh) {ssh}? 369 | | +--rw ssh 370 | | +--rw address? inet:ip-address 371 | | +--rw port? inet:port-number 372 | | +--rw host-keys 373 | | +--rw host-key* string 374 | +--:(tls) {tls}? 375 | +--rw tls 376 | +--rw address? inet:ip-address 377 | +--rw port? inet:port-number 378 | +--rw certificates 379 | +--rw certificate* string 380 +--rw keep-alives 381 +--rw interval-secs? uint8 382 +--rw count-max? uint8 384 The above subtree illustrates how the ietf-netconf-server YANG module 385 enables configuration for listening for remote connections, as 386 described in [RFC6242]. Feature statements are used to limit both if 387 listening is supported at all as well as for which transports. If 388 listening for connections is supported, then the model enables 389 configuring a list of listening endpoints, each configured with a 390 user-specified name (the key field), the transport to use (i.e. SSH, 391 TLS), and the IP address and port to listen on. The port field is 392 optional, defaulting to the transport-specific port when not 393 configured. Please see the YANG module (Section 3.2) for a complete 394 description of these configuration knobs. 396 3.1.3. The "call-home" subtree 397 module: ietf-netconf-server 398 +--rw netconf-server 399 +--rw call-home {call-home}? 400 +--rw application* [name] 401 +--rw name string 402 +--rw (transport) 403 | +--:(ssh) {ssh}? 404 | | +--rw ssh 405 | | +--rw endpoints 406 | | | +--rw endpoint* [name] 407 | | | +--rw name string 408 | | | +--rw address inet:host 409 | | | +--rw port? inet:port-number 410 | | +--rw host-keys 411 | | +--rw host-key* string 412 | +--:(tls) {tls}? 413 | +--rw tls 414 | +--rw endpoints 415 | | +--rw endpoint* [name] 416 | | +--rw name string 417 | | +--rw address inet:host 418 | | +--rw port? inet:port-number 419 | +--rw certificates 420 | +--rw certificate* string 421 +--rw connection-type 422 | +--rw (connection-type)? 423 | +--:(persistent-connection) 424 | | +--rw persistent 425 | | +--rw keep-alives 426 | | +--rw interval-secs? uint8 427 | | +--rw count-max? uint8 428 | +--:(periodic-connection) 429 | +--rw periodic 430 | +--rw timeout-mins? uint8 431 | +--rw linger-secs? uint8 432 +--rw reconnect-strategy 433 +--rw start-with? enumeration 434 +--rw interval-secs? uint8 435 +--rw count-max? uint8 437 The above subtree illustrates how the ietf-netconf-server YANG module 438 enables configuration for call home, as described in 439 [draft-ietf-netconf-call-home]. Feature statements are used to limit 440 both if call-home is supported at all as well as for which 441 transports, if it is. If call-home is supported, then the model 442 supports configuring a list of applications to connect to. Each 443 application is configured with a user-specified name (the key field), 444 the transport to be used (i.e. SSH, TLS), and a list of remote 445 endpoints, each having a name, an IP address, and an optional port. 446 Additionally, the configuration for each remote application indicates 447 the connection-type (persistent vs. periodic) and associated 448 parameters, as well as the reconnection strategy to use. Please see 449 the YANG module (Section 3.2) for a complete description of these 450 configuration knobs. 452 3.1.4. The "ssh" subtree 454 module: ietf-netconf-server 455 +--rw netconf-server 456 +--rw ssh {ssh}? 457 +--rw x509 {ssh-x509-certs}? 458 +--rw trusted-ca-certs 459 | +--rw trusted-ca-cert* binary 460 +--rw trusted-client-certs 461 +--rw trusted-client-cert* binary 463 The above subtree illustrates how the ietf-netconf-server YANG module 464 enables some SSH configuration independent of if the NETCONF server 465 is listening or calling home. Specifically, when RFC 6187 is 466 supported, this data model provides an ability to configure how 467 client-certificates are authenticated. Please see the YANG module 468 (Section 3.2) for a complete description of these configuration 469 knobs. 471 3.1.5. The "tls" subtree 473 module: ietf-netconf-server 474 +--rw netconf-server 475 +--rw tls {tls}? 476 +--rw client-auth 477 +--rw trusted-ca-certs 478 | +--rw trusted-ca-cert* binary 479 +--rw trusted-client-certs 480 | +--rw trusted-client-cert* binary 481 +--rw cert-maps 482 +--rw cert-to-name* [id] 483 +--rw id uint32 484 +--rw fingerprint x509c2n:tls-fingerprint 485 +--rw map-type identityref 486 +--rw name string 488 The above subtree illustrates how the ietf-netconf-server YANG module 489 enables TLS configuration independent of if the NETCONF server is 490 listening or calling home. Specifically, this data-model provides 1) 491 an ability to configure how client-certificates are authenticated and 492 2) how authenticated client-certificates are mapped to NETCONF user 493 names. Please see the YANG module (Section 3.2) for a complete 494 description of these configuration knobs. 496 3.2. YANG Module 498 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 500 file "ietf-netconf-server@2015-02-02.yang" 502 module ietf-netconf-server { 504 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server"; 505 prefix "ncserver"; 507 import ietf-netconf-acm { 508 prefix nacm; // RFC 6536 509 revision-date 2012-02-22; 510 } 511 import ietf-inet-types { // RFC 6991 512 prefix inet; 513 revision-date 2013-07-15; 514 } 515 import ietf-x509-cert-to-name { // RFC 7407 516 prefix x509c2n; 517 revision-date 2014-12-10; 518 } 520 organization 521 "IETF NETCONF (Network Configuration) Working Group"; 523 contact 524 "WG Web: 525 WG List: 527 WG Chair: Mehmet Ersue 528 530 WG Chair: Mahesh Jethanandani 531 533 Editor: Kent Watsen 534 "; 536 description 537 "This module contains a collection of YANG definitions for 538 configuring NETCONF servers. 540 Copyright (c) 2014 IETF Trust and the persons identified as 541 authors of the code. All rights reserved. 543 Redistribution and use in source and binary forms, with or 544 without modification, is permitted pursuant to, and subject 545 to the license terms contained in, the Simplified BSD 546 License set forth in Section 4.c of the IETF Trust's 547 Legal Provisions Relating to IETF Documents 548 (http://trustee.ietf.org/license-info). 550 This version of this YANG module is part of RFC VVVV; see 551 the RFC itself for full legal notices."; 553 revision "2015-02-02" { 554 description 555 "Initial version"; 556 reference 557 "RFC VVVV: NETCONF Server and RESTCONF Server Configuration Models"; 558 } 560 // Features 562 feature ssh { 563 description 564 "The ssh feature indicates that the server supports the 565 SSH transport protocol."; 566 reference 567 "RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)"; 568 } 570 feature tls { 571 description 572 "The tls feature indicates that the server supports the 573 TLS transport protocol."; 574 reference 575 "RFC 5539: NETCONF over Transport Layer Security (TLS)"; 576 } 578 feature listen { 579 description 580 "The listen feature indicates that the server supports 581 opening a port to listen for incoming client connections."; 582 reference 583 "RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH) 584 RFC 5539: NETCONF over Transport Layer Security (TLS)"; 585 } 586 feature call-home { 587 description 588 "The call-home feature indicates that the server supports 589 connecting to the client"; 590 reference 591 "RFC YYYY: NETCONF Call Home and RESTCONF Call Home"; 592 } 594 feature ssh-x509-certs { 595 description 596 "The ssh-x509-certs feature indicates that the NETCONF server 597 supports RFC 6187"; 598 reference 599 "RFC 6187: X.509v3 Certificates for Secure Shell Authentication"; 600 } 602 // top-level container (groupings below) 603 container netconf-server { 604 description 605 "Top-level container for NETCONF server configuration."; 607 uses session-options-container; 608 uses listen-container; 609 uses call-home-container; 610 uses ssh-container; 611 uses tls-container; 613 } 615 grouping session-options-container { 616 description 617 "This grouping is used only to help improve readability 618 of the YANG module."; 619 container session-options { 620 description 621 "NETCONF session options, independent of transport 622 or connection strategy."; 623 leaf hello-timeout { 624 type uint32 { 625 range "0 | 10 .. 3600"; 626 } 627 units "seconds"; 628 default '600'; 629 description 630 "Specifies the number of seconds that a session may exist 631 before the hello PDU is received. A session will be 632 dropped if no hello PDU is received before this number 633 of seconds elapses. 635 If this parameter is set to zero, then the server will 636 wait forever for a hello message, and not drop any 637 sessions stuck in 'hello-wait' state. 639 Setting this parameter to zero may permit denial of 640 service attacks, since only a limited number of 641 concurrent sessions may be supported by the server."; 642 } 643 leaf idle-timeout { 644 type uint32 { 645 range "0 | 10 .. 360000"; 646 } 647 units "seconds"; 648 default '3600'; 649 description 650 "Specifies the number of seconds that a NETCONF session may 651 remain idle without issuing any RPC requests. A session 652 will be dropped if it is idle for an interval longer than 653 this number of seconds. If this parameter is set to zero, 654 then the server will never drop a session because it is 655 idle. Sessions that have a notification subscription 656 active are never dropped. 658 This mechanism is independent of keep-alives, as it regards 659 activity occurring at the NETCONF protocol layer, whereas 660 the keep-alive mechanism regards transport-level activity."; 661 } 662 } 663 } 665 grouping listen-container { 666 description 667 "This grouping is used only to help improve readability 668 of the YANG module."; 669 container listen { 670 description 671 "Configures listen behavior"; 672 if-feature listen; 673 leaf max-sessions { 674 type uint16 { 675 range "0 .. 1024"; 676 } 677 default '0'; 678 description 679 "Specifies the maximum number of concurrent sessions 680 that can be active at one time. The value 0 indicates 681 that no artificial session limit should be used."; 682 } 683 list endpoint { 684 key name; 685 description 686 "List of endpoints to listen for NETCONF connections on."; 687 leaf name { 688 type string; 689 description 690 "An arbitrary name for the NETCONF listen endpoint."; 691 } 692 choice transport { 693 mandatory true; 694 description 695 "Selects between SSH and TLS transports."; 696 case ssh { 697 if-feature ssh; 698 container ssh { 699 description 700 "SSH-specific listening configuration for inbound 701 connections."; 702 uses address-and-port-grouping { 703 refine port { 704 default 830; 705 } 706 } 707 uses host-keys-container; 708 } 709 } 710 case tls { 711 if-feature tls; 712 container tls { 713 description 714 "TLS-specific listening configuration for inbound 715 connections."; 716 uses address-and-port-grouping { 717 refine port { 718 default 6513; 719 } 720 } 721 uses certificates-container; 722 } 723 } 724 } 725 uses keep-alives-container { 726 refine keep-alives/interval-secs { 727 default 0; // disabled by default for listen connections 728 } 729 } 730 } 731 } 732 } 734 grouping call-home-container { 735 description 736 "This grouping is used only to help improve readability 737 of the YANG module."; 738 container call-home { 739 if-feature call-home; 740 description 741 "Configures call-home behavior"; 742 list application { 743 key name; 744 description 745 "List of NETCONF clients the NETCONF server is to initiate 746 call-home connections to."; 747 leaf name { 748 type string; 749 description 750 "An arbitrary name for the remote NETCONF client."; 751 } 752 choice transport { 753 mandatory true; 754 description 755 "Selects between available transports."; 756 case ssh { 757 if-feature ssh; 758 container ssh { 759 description 760 "Specifies SSH-specific call-home transport 761 configuration."; 762 uses endpoints-container { 763 refine endpoints/endpoint/port { 764 default 7777; 765 } 766 } 767 uses host-keys-container; 768 } 769 } 770 case tls { 771 if-feature tls; 772 container tls { 773 description 774 "Specifies TLS-specific call-home transport 775 configuration."; 776 uses endpoints-container { 777 refine endpoints/endpoint/port { 778 default 8888; 779 } 780 } 781 uses certificates-container; 782 } 783 } 784 } 785 container connection-type { 786 description 787 "Indicates the kind of connection to use."; 788 choice connection-type { 789 default persistent-connection; 790 description 791 "Selects between persistent and periodic connections."; 792 case persistent-connection { 793 container persistent { 794 description 795 "Maintain a persistent connection to the NETCONF 796 client. If the connection goes down, immediately 797 start trying to reconnect to it, using the 798 reconnection strategy. 800 This connection type minimizes any NETCONF client 801 to NETCONF server data-transfer delay, albeit at 802 the expense of holding resources longer."; 803 uses keep-alives-container { 804 refine keep-alives/interval-secs { 805 default 15; // 15 seconds for call-home sessions 806 } 807 } 808 } 809 } 810 case periodic-connection { 811 container periodic { 812 description 813 "Periodically connect to NETCONF client, using the 814 reconnection strategy, so the NETCONF client can 815 deliver pending messages to the NETCONF server. 817 For messages the NETCONF server wants to send to 818 to the NETCONF client, the NETCONF server should 819 proactively connect to the NETCONF client, if 820 not already, to send the messages immediately."; 821 leaf timeout-mins { 822 type uint8; 823 units minutes; 824 default 5; 825 description 826 "The maximum amount of unconnected time the NETCONF 827 server will wait until establishing a connection to 828 the NETCONF client again. The NETCONF server MAY 829 establish a connection before this time if it has 830 data it needs to send to the NETCONF client. Note: 831 this value differs from the reconnection strategy's 832 interval-secs value."; 833 } 834 leaf linger-secs { 835 type uint8; 836 units seconds; 837 default 30; 838 description 839 "The amount of time the NETCONF server should wait 840 after last receiving data from or sending data to 841 the NETCONF client's endpoint before closing its 842 connection to it. This is an optimization to 843 prevent unnecessary connections."; 844 } 845 } 846 } 847 } 848 } 849 container reconnect-strategy { 850 description 851 "The reconnection strategy guides how a NETCONF server 852 reconnects to an NETCONF client, after losing a connection 853 to it, even if due to a reboot. The NETCONF server starts 854 with the specified endpoint and tries to connect to it 855 count-max times, waiting interval-secs between each 856 connection attempt, before trying the next endpoint in 857 the list (round robin)."; 858 leaf start-with { 859 type enumeration { 860 enum first-listed { 861 description 862 "Indicates that reconnections should start with 863 the first endpoint listed."; 864 } 865 enum last-connected { 866 description 867 "Indicates that reconnections should start with 868 the endpoint last connected to. NETCONF servers 869 SHOULD support this flag across reboots."; 870 } 872 } 873 default first-listed; 874 description 875 "Specifies which of the NETCONF client's endpoints the 876 NETCONF server should start with when trying to connect 877 to the NETCONF client. If no previous connection has 878 ever been established, last-connected defaults to 879 the first endpoint listed."; 880 } 881 leaf interval-secs { 882 type uint8; 883 units seconds; 884 default 5; 885 description 886 "Specifies the time delay between connection attempts 887 to the same endpoint. Note: this value differs from 888 the periodic-connection's timeout-mins value."; 889 } 890 leaf count-max { 891 type uint8; 892 default 3; 893 description 894 "Specifies the number times the NETCONF server tries to 895 connect to a specific endpoint before moving on to the 896 next endpoint in the list (round robin)."; 897 } 898 } 899 } 900 } 901 } 903 grouping ssh-container { 904 description 905 "This grouping is used only to help improve readability 906 of the YANG module."; 907 container ssh { 908 description 909 "Configures SSH properties not specific to the listen 910 or call-home use-cases"; 911 if-feature ssh; 912 container x509 { 913 if-feature ssh-x509-certs; 914 uses trusted-certs-grouping; 915 } 916 } 917 } 918 grouping tls-container { 919 description 920 "This grouping is used only to help improve readability 921 of the YANG module."; 922 container tls { 923 description 924 "Configures TLS properties for authenticating clients."; 925 if-feature tls; 926 container client-auth { 927 description 928 "Container for TLS client authentication configuration."; 929 uses trusted-certs-grouping; 930 container cert-maps { 931 uses x509c2n:cert-to-name; 932 description 933 "The cert-maps container is used by a NETCONF server to 934 map the NETCONF client's presented X.509 certificate to a 935 NETCONF username. If no matching and valid cert-to-name 936 list entry can be found, then the NETCONF server MUST 937 close the connection, and MUST NOT accept NETCONF 938 messages over it."; 939 } 940 } 941 } 942 } 944 grouping trusted-certs-grouping { 945 description 946 "This grouping is used by both the ssh and tls containers."; 947 container trusted-ca-certs { 948 description 949 "A list of Certificate Authority (CA) certificates that 950 a NETCONF server can use to authenticate NETCONF client 951 certificates. A client's certificate is authenticated 952 if there is a chain of trust to a configured trusted CA 953 certificate. The client certificate MAY be accompanied 954 with additional certificates forming a chain of trust. 955 The client's certificate is authenticated if there is 956 path-validation from any of the certificates it presents 957 to a configured trust anchor."; 958 leaf-list trusted-ca-cert { 959 type binary; 960 ordered-by system; 961 nacm:default-deny-write; 962 description 963 "The binary certificate structure as specified by RFC 964 5246, Section 7.4.6, i.e.,: opaque ASN.1Cert<1..2^24>; 965 "; 967 reference 968 "RFC 5246: The Transport Layer Security (TLS) 969 Protocol Version 1.2"; 970 } 971 } 972 container trusted-client-certs { 973 description 974 "A list of client certificates that a NETCONF server can 975 use to authenticate a NETCONF client's certificate. A 976 client's certificate is authenticated if it is an exact 977 match to a configured trusted client certificates."; 978 leaf-list trusted-client-cert { 979 type binary; 980 ordered-by system; 981 nacm:default-deny-write; 982 description 983 "The binary certificate structure, as 984 specified by RFC 5246, Section 7.4.6, i.e.,: 986 opaque ASN.1Cert<1..2^24>; 988 "; 989 reference 990 "RFC 5246: The Transport Layer Security (TLS) 991 Protocol Version 1.2"; 992 } 993 } 994 } 996 grouping host-keys-container { 997 description 998 "This grouping is used by both the listen and 999 call-home containers"; 1000 container host-keys { 1001 description 1002 "Parent container for the list of host-keys."; 1003 leaf-list host-key { 1004 type string; 1005 min-elements 1; 1006 ordered-by user; 1007 description 1008 "A user-ordered list of host-keys the SSH server 1009 considers when composing the list of server host 1010 key algorithms it will send to the client in its 1011 SSH_MSG_KEXINIT message. The value of the string 1012 is the unique identifier for a host-key configured 1013 on the system. How valid values are discovered is 1014 outside the scope of this module, but they are 1015 envisioned to be the keys for a list of host-keys 1016 provided by another YANG module"; 1017 reference 1018 "RFC 4253: The SSH Transport Layer Protocol, Section 7"; 1019 } 1020 } 1021 } 1023 grouping certificates-container { 1024 description 1025 "This grouping is used by both the listen and 1026 call-home containers"; 1027 container certificates { 1028 description 1029 "Parent container for the list of certificates."; 1030 leaf-list certificate { 1031 type string; 1032 min-elements 1; 1033 description 1034 "An unordered list of certificates the TLS server can pick 1035 from when sending its Server Certificate message. The value 1036 of the string is the unique identifier for a certificate 1037 configured on the system. How valid values are discovered 1038 is outside the scope of this module, but they are envisioned 1039 to be the keys for a list of certificates provided 1040 by another YANG module"; 1041 reference 1042 "RFC 5246: The TLS Protocol, Section 7.4.2"; 1043 } 1044 } 1045 } 1047 grouping address-and-port-grouping { 1048 description 1049 "This grouping is usd by both the ssh and tls containers 1050 for listen configuration."; 1051 leaf address { 1052 type inet:ip-address; 1053 description 1054 "The IP address of the interface to listen on."; 1055 } 1056 leaf port { 1057 type inet:port-number; 1058 description 1059 "The local port number on this interface the NETCONF server 1060 listens on."; 1061 } 1062 } 1063 grouping endpoints-container { 1064 description 1065 "This grouping is used by both the ssh and tls containers 1066 for call-home configurations."; 1067 container endpoints { 1068 description 1069 "Container for the list of endpoints."; 1070 list endpoint { 1071 key name; 1072 min-elements 1; 1073 ordered-by user; 1074 description 1075 "User-ordered list of endpoints for this NETCONF client. 1076 Defining more than one enables high-availability."; 1077 leaf name { 1078 type string; 1079 description 1080 "An arbitrary name for the endpoint to connect to."; 1081 } 1082 leaf address { 1083 type inet:host; 1084 mandatory true; 1085 description 1086 "The hostname or IP address or hostname of the endpoint. 1087 If a hostname is provided and DNS resolves to more than 1088 one IP address, the NETCONF server SHOULD try all of 1089 the ones it can based on how its networking stack is 1090 configured (e.g. v4, v6, dual-stack)."; 1091 } 1092 leaf port { 1093 type inet:port-number; 1094 description 1095 "The IP port for this endpoint. The NETCONF server will 1096 use the IANA-assigned well-known port if not specified."; 1097 } 1098 } 1099 } 1100 } 1102 grouping keep-alives-container { 1103 description 1104 "This grouping is use by both listen and call-home configurations."; 1105 container keep-alives { 1106 description 1107 "Configures the keep-alive policy, to proactively test the 1108 aliveness of the NETCONF client."; 1109 reference 1110 "RFC VVVV: NETCONF Server and RESTCONF Server Configuration 1111 Models, Section 4"; 1112 leaf interval-secs { 1113 type uint8; 1114 units seconds; 1115 description 1116 "Sets a timeout interval in seconds after which if no data 1117 has been received from the NETCONF client, a message will 1118 be sent to request a response from the NETCONF client. A 1119 value of '0' indicates that no keep-alive messages should 1120 be sent."; 1121 } 1122 leaf count-max { 1123 type uint8; 1124 default 3; 1125 description 1126 "Sets the number of keep-alive messages that may be sent 1127 without receiving any data from the NETCONF client before 1128 assuming the NETCONF client is no longer alive. If this 1129 threshold is reached, the transport-level connection will 1130 be disconnected, which will trigger the reconnection 1131 strategy). The interval timer is reset after each 1132 transmission, thus an unresponsive NETCONF client will 1133 be dropped after approximately (count-max * interval-secs) 1134 seconds."; 1135 } 1136 } 1137 } 1138 } 1140 1142 4. The RESTCONF Server Configuration Model 1144 4.1. Overview 1146 4.1.1. The "listen" subtree 1147 module: ietf-restconf-server 1148 +--rw restconf-server 1149 +--rw listen {listen}? 1150 +--rw max-sessions? uint16 1151 +--rw endpoint* [name] 1152 +--rw name string 1153 +--rw (transport) 1154 | +--:(tls) 1155 | +--rw tls 1156 | +--rw address? inet:ip-address 1157 | +--rw port? inet:port-number 1158 | +--rw certificates 1159 | +--rw certificate* string 1160 +--rw keep-alives 1161 +--rw interval-secs? uint8 1162 +--rw count-max? uint8 1164 The above subtree illustrates how the ietf-restconf-server YANG 1165 module enables configuration for listening for remote connections, as 1166 described in [draft-ietf-netconf-restconf]. Feature statements are 1167 used to limit both if listening is supported at all as well as for 1168 which transports. If listening for connections is supported, then 1169 the model enables configuring a list of listening endpoints, each 1170 configured with a user-specified name (the key field), the transport 1171 to use (i.e. TLS), and the IP address and port to listen on. The 1172 port field is optional, defaulting to the transport-specific port 1173 when not configured. Please see the YANG module (Section 4.2) for a 1174 complete description of these configuration knobs. 1176 4.1.2. The "call-home" subtree 1177 module: ietf-restconf-server 1178 +--rw restconf-server 1179 +--rw call-home {call-home}? 1180 +--rw application* [name] 1181 +--rw name string 1182 +--rw (transport) 1183 | +--:(tls) {tls}? 1184 | +--rw tls 1185 | +--rw endpoints 1186 | | +--rw endpoint* [name] 1187 | | +--rw name string 1188 | | +--rw address inet:host 1189 | | +--rw port? inet:port-number 1190 | +--rw certificates 1191 | +--rw certificate* string 1192 +--rw connection-type 1193 | +--rw (connection-type)? 1194 | +--:(persistent-connection) 1195 | | +--rw persistent 1196 | | +--rw keep-alives 1197 | | +--rw interval-secs? uint8 1198 | | +--rw count-max? uint8 1199 | +--:(periodic-connection) 1200 | +--rw periodic 1201 | +--rw timeout-mins? uint8 1202 | +--rw linger-secs? uint8 1203 +--rw reconnect-strategy 1204 +--rw start-with? enumeration 1205 +--rw interval-secs? uint8 1206 +--rw count-max? uint8 1208 The above subtree illustrates how the ietf-restconf-server YANG 1209 module enables configuration for call home, as described in 1210 [draft-ietf-netconf-call-home]. Feature statements are used to limit 1211 both if call-home is supported at all as well as for which 1212 transports, if it is. If call-home is supported, then the model 1213 supports configuring a list of applications to connect to. Each 1214 application is configured with a user-specified name (the key field), 1215 the transport to be used (i.e. TLS), and a list of remote endpoints, 1216 each having a name, an IP address, and an optional port. 1217 Additionally, the configuration for each remote application indicates 1218 the connection-type (persistent vs. periodic) and associated 1219 parameters, as well as the reconnection strategy to use. Please see 1220 the YANG module (Section 4.2) for a complete description of these 1221 configuration knobs. 1223 4.1.3. The "client-cert-auth" subtree 1225 module: ietf-restconf-server 1226 +--rw restconf-server 1227 +--rw client-cert-auth {client-cert-auth}? 1228 +--rw trusted-ca-certs 1229 | +--rw trusted-ca-cert* binary 1230 +--rw trusted-client-certs 1231 | +--rw trusted-client-cert* binary 1232 +--rw cert-maps 1233 +--rw cert-to-name* [id] 1234 +--rw id uint32 1235 +--rw fingerprint x509c2n:tls-fingerprint 1236 +--rw map-type identityref 1237 +--rw name string 1239 The above subtree illustrates how the ietf-restconf-server YANG 1240 module enables configuration of client-certificate authentication. 1241 Specifically, this data-model provides 1) an ability to configure how 1242 client-certificates are authenticated and 2) how authenticated 1243 client-certificates are mapped to RESTCONF user names. Please see 1244 the YANG module (Section 4.2) for a complete description of these 1245 configuration knobs. 1247 4.2. YANG Module 1249 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 1251 file "ietf-restconf-server@2015-02-02.yang" 1253 module ietf-restconf-server { 1255 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1256 prefix "rcserver"; 1258 import ietf-netconf-acm { 1259 prefix nacm; // RFC 6536 1260 revision-date 2012-02-22; 1261 } 1262 import ietf-inet-types { // RFC 6991 1263 prefix inet; 1264 revision-date 2013-07-15; 1265 } 1266 import ietf-x509-cert-to-name { // RFC 7407 1267 prefix x509c2n; 1268 revision-date 2014-12-10; 1269 } 1270 organization 1271 "IETF NETCONF (Network Configuration) Working Group"; 1273 contact 1274 "WG Web: 1275 WG List: 1277 WG Chair: Mehmet Ersue 1278 1280 WG Chair: Mahesh Jethanandani 1281 1283 Editor: Kent Watsen 1284 "; 1286 description 1287 "This module contains a collection of YANG definitions for 1288 configuring RESTCONF servers. 1290 Copyright (c) 2014 IETF Trust and the persons identified as 1291 authors of the code. All rights reserved. 1293 Redistribution and use in source and binary forms, with or 1294 without modification, is permitted pursuant to, and subject 1295 to the license terms contained in, the Simplified BSD 1296 License set forth in Section 4.c of the IETF Trust's 1297 Legal Provisions Relating to IETF Documents 1298 (http://trustee.ietf.org/license-info). 1300 This version of this YANG module is part of RFC VVVV; see 1301 the RFC itself for full legal notices."; 1303 revision "2015-02-02" { 1304 description 1305 "Initial version"; 1306 reference 1307 "RFC VVVV: NETCONF Server and RESTCONF Server Configuration Models"; 1308 } 1310 // Features 1312 feature tls { 1313 description 1314 "The tls feature indicates that the server supports RESTCONF 1315 over the TLS transport protocol."; 1317 reference 1318 "RFC XXXX: RESTCONF Protocol"; 1319 } 1321 feature listen { 1322 description 1323 "The listen feature indicates that the server supports 1324 opening a port to listen for incoming client connections."; 1325 reference 1326 "RFC XXXX: RESTCONF Protocol"; 1327 } 1329 feature call-home { 1330 description 1331 "The call-home feature indicates that the server supports 1332 connecting to the client."; 1333 reference 1334 "RFC YYYY: NETCONF Call Home and RESTCONF Call Home"; 1335 } 1337 feature client-cert-auth { 1338 description 1339 "The client-cert-auth feature indicatres that the server 1340 supports the ClientCertificate authentication scheme."; 1341 reference 1342 "RFC ZZZZ: Client Authentication over New TLS Connection"; 1343 } 1345 // top-level container (groupings below) 1346 container restconf-server { 1347 description 1348 "Top-level container for RESTCONF server configuration."; 1350 uses listen-container; 1351 uses call-home-container; 1352 uses client-cert-auth-container; 1353 } 1355 grouping listen-container { 1356 description 1357 "This grouping is used only to help improve readability 1358 of the YANG module."; 1359 container listen { 1360 description 1361 "Configures listen behavior"; 1362 if-feature listen; 1363 leaf max-sessions { 1364 type uint16 { 1365 range "0 .. 1024"; 1366 } 1367 default '0'; 1368 description 1369 "Specifies the maximum number of concurrent sessions 1370 that can be active at one time. The value 0 indicates 1371 that no artificial session limit should be used."; 1372 } 1373 list endpoint { 1374 key name; 1375 description 1376 "List of endpoints to listen for RESTCONF connections on."; 1377 leaf name { 1378 type string; 1379 description 1380 "An arbitrary name for the RESTCONF listen endpoint."; 1381 } 1382 choice transport { 1383 mandatory true; 1384 description 1385 "Selects between available transports."; 1386 case tls { 1387 container tls { 1388 description 1389 "TLS-specific listening configuration for inbound 1390 connections."; 1391 uses address-and-port-grouping { 1392 refine port { 1393 default 443; 1394 } 1395 } 1396 uses certificates-container; 1397 } 1398 } 1399 } 1400 uses keep-alives-container { 1401 refine keep-alives/interval-secs { 1402 default 0; // disabled by default for listen connections 1403 } 1404 } 1405 } 1406 } 1407 } 1409 grouping call-home-container { 1410 description 1411 "This grouping is used only to help improve readability 1412 of the YANG module."; 1413 container call-home { 1414 if-feature call-home; 1415 description 1416 "Configures call-home behavior"; 1417 list application { 1418 key name; 1419 description 1420 "List of RESTCONF clients the RESTCONF server is to initiate 1421 call-home connections to."; 1422 leaf name { 1423 type string; 1424 description 1425 "An arbitrary name for the remote RESTCONF client."; 1426 } 1427 choice transport { 1428 mandatory true; 1429 description 1430 "Selects between TLS and any future transports augmented in."; 1431 case tls { 1432 if-feature tls; 1433 container tls { 1434 description 1435 "Specifies TLS-specific call-home transport 1436 configuration."; 1437 uses endpoints-container { 1438 refine endpoints/endpoint/port { 1439 default 9999; 1440 } 1441 } 1442 uses certificates-container; 1443 } 1444 } 1445 } 1446 container connection-type { 1447 description 1448 "Indicates the RESTCONF client's preference for how the 1449 RESTCONF server's connection is maintained."; 1450 choice connection-type { 1451 default persistent-connection; 1452 description 1453 "Selects between persistent and periodic connections."; 1454 case persistent-connection { 1455 container persistent { 1456 description 1457 "Maintain a persistent connection to the RESTCONF 1458 client. If the connection goes down, immediately 1459 start trying to reconnect to it, using the 1460 reconnection strategy. 1462 This connection type minimizes any RESTCONF client 1463 to RESTCONF server data-transfer delay, albeit at 1464 the expense of holding resources longer."; 1465 uses keep-alives-container { 1466 refine keep-alives/interval-secs { 1467 default 15; // 15 seconds for call-home sessions 1468 } 1469 } 1470 } 1471 } 1472 case periodic-connection { 1473 container periodic { 1474 description 1475 "Periodically connect to RESTCONF client, using the 1476 reconnection strategy, so the RESTCONF client can 1477 deliver pending messages to the RESTCONF server. 1479 For messages the RESTCONF server wants to send to 1480 to the RESTCONF client, the RESTCONF server should 1481 proactively connect to the RESTCONF client, if 1482 not already, to send the messages immediately."; 1483 leaf timeout-mins { 1484 type uint8; 1485 units minutes; 1486 default 5; 1487 description 1488 "The maximum amount of unconnected time the RESTCONF 1489 server will wait until establishing a connection to 1490 the RESTCONF client again. The RESTCONF server MAY 1491 establish a connection before this time if it has 1492 data it needs to send to the RESTCONF client. Note: 1493 this value differs from the reconnection strategy's 1494 interval-secs value."; 1495 } 1496 leaf linger-secs { 1497 type uint8; 1498 units seconds; 1499 default 30; 1500 description 1501 "The amount of time the RESTCONF server should wait 1502 after last receiving data from or sending data to 1503 the RESTCONF client's endpoint before closing its 1504 connection to it. This is an optimization to 1505 prevent unnecessary connections."; 1506 } 1508 } 1509 } 1510 } 1511 } 1512 container reconnect-strategy { 1513 description 1514 "The reconnection strategy guides how a RESTCONF server 1515 reconnects to an RESTCONF client, after losing a connection 1516 to it, even if due to a reboot. The RESTCONF server starts 1517 with the specified endpoint and tries to connect to it 1518 count-max times, waiting interval-secs between each 1519 connection attempt, before trying the next endpoint in 1520 the list (round robin)."; 1521 leaf start-with { 1522 type enumeration { 1523 enum first-listed { 1524 description 1525 "Indicates that reconnections should start with 1526 the first endpoint listed."; 1527 } 1528 enum last-connected { 1529 description 1530 "Indicates that reconnections should start with 1531 the endpoint last connected to. RESTCONF servers 1532 SHOULD support this flag across reboots."; 1533 } 1534 } 1535 default first-listed; 1536 description 1537 "Specifies which of the RESTCONF client's endpoints the 1538 RESTCONF server should start with when trying to connect 1539 to the RESTCONF client. If no previous connection has 1540 ever been established, last-connected defaults to 1541 the first endpoint listed."; 1542 } 1543 leaf interval-secs { 1544 type uint8; 1545 units seconds; 1546 default 5; 1547 description 1548 "Specifies the time delay between connection attempts 1549 to the same endpoint. Note: this value differs from 1550 the periodic-connection's timeout-mins value."; 1551 } 1552 leaf count-max { 1553 type uint8; 1554 default 3; 1555 description 1556 "Specifies the number times the RESTCONF server tries to 1557 connect to a specific endpoint before moving on to the 1558 next endpoint in the list (round robin)."; 1559 } 1560 } 1561 } 1562 } 1563 } 1565 grouping client-cert-auth-container { 1566 description 1567 "This grouping is used only to help improve readability 1568 of the YANG module."; 1569 container client-cert-auth { 1570 if-feature client-cert-auth; 1571 description 1572 "Container for TLS client certificate authentication 1573 configuration."; 1574 container trusted-ca-certs { 1575 description 1576 "A list of Certificate Authority (CA) certificates that 1577 a NETCONF server can use to authenticate NETCONF client 1578 certificates. A client's certificate is authenticated 1579 if there is a chain of trust to a configured trusted CA 1580 certificate. The client certificate MAY be accompanied 1581 with additional certificates forming a chain of trust. 1582 The client's certificate is authenticated if there is 1583 path-validation from any of the certificates it presents 1584 to a configured trust anchor."; 1585 leaf-list trusted-ca-cert { 1586 type binary; 1587 ordered-by system; 1588 nacm:default-deny-write; 1589 description 1590 "The binary certificate structure as specified by RFC 1591 5246, Section 7.4.6, i.e.,: opaque ASN.1Cert<1..2^24>; 1592 "; 1593 reference 1594 "RFC 5246: The Transport Layer Security (TLS) 1595 Protocol Version 1.2"; 1596 } 1597 } 1598 container trusted-client-certs { 1599 description 1600 "A list of client certificates that a NETCONF server can 1601 use to authenticate a NETCONF client's certificate. A 1602 client's certificate is authenticated if it is an exact 1603 match to a configured trusted client certificates."; 1604 leaf-list trusted-client-cert { 1605 type binary; 1606 ordered-by system; 1607 nacm:default-deny-write; 1608 description 1609 "The binary certificate structure, as 1610 specified by RFC 5246, Section 7.4.6, i.e.,: 1612 opaque ASN.1Cert<1..2^24>; 1614 "; 1615 reference 1616 "RFC 5246: The Transport Layer Security (TLS) 1617 Protocol Version 1.2"; 1618 } 1619 } 1620 container cert-maps { 1621 uses x509c2n:cert-to-name; 1622 description 1623 "The cert-maps container is used by a NETCONF server to 1624 map the NETCONF client's presented X.509 certificate to a 1625 NETCONF username. If no matching and valid cert-to-name 1626 list entry can be found, then the NETCONF server MUST 1627 close the connection, and MUST NOT accept NETCONF 1628 messages over it."; 1629 } 1630 } 1631 } 1633 grouping certificates-container { 1634 description 1635 "This grouping is used by both the listen and 1636 call-home containers"; 1637 container certificates { 1638 description 1639 "Parent container for the list of certificates."; 1640 leaf-list certificate { 1641 type string; 1642 min-elements 1; 1643 description 1644 "An unordered list of certificates the TLS server can pick 1645 from when sending its Server Certificate message. The value 1646 of the string is the unique identifier for a certificate 1647 configured on the system. How valid values are discovered 1648 is outside the scope of this module, but they are envisioned 1649 to be the keys for a list of certificates provided 1650 by another YANG module"; 1651 reference 1652 "RFC 5246: The TLS Protocol, Section 7.4.2"; 1653 } 1654 } 1655 } 1657 grouping address-and-port-grouping { 1658 description 1659 "This grouping is usd by both the ssh and tls containers 1660 for listen configuration."; 1661 leaf address { 1662 type inet:ip-address; 1663 description 1664 "The IP address of the interface to listen on."; 1665 } 1666 leaf port { 1667 type inet:port-number; 1668 description 1669 "The local port number on this interface the RESTCONF server 1670 listens on."; 1671 } 1672 } 1674 grouping endpoints-container { 1675 description 1676 "This grouping is used by both the ssh and tls containers 1677 for call-home configurations."; 1678 container endpoints { 1679 description 1680 "Container for the list of endpoints."; 1681 list endpoint { 1682 key name; 1683 min-elements 1; 1684 ordered-by user; 1685 description 1686 "User-ordered list of endpoints for this RESTCONF client. 1687 Defining more than one enables high-availability."; 1688 leaf name { 1689 type string; 1690 description 1691 "An arbitrary name for the endpoint to connect to."; 1692 } 1693 leaf address { 1694 type inet:host; 1695 mandatory true; 1696 description 1697 "The hostname or IP address or hostname of the endpoint. 1698 If a hostname is provided and DNS resolves to more than 1699 one IP address, the RESTCONF server SHOULD try all of 1700 the ones it can based on how its networking stack is 1701 configured (e.g. v4, v6, dual-stack)."; 1702 } 1703 leaf port { 1704 type inet:port-number; 1705 description 1706 "The IP port for this endpoint. The RESTCONF server will 1707 use the IANA-assigned well-known port if not specified."; 1708 } 1709 } 1710 } 1711 } 1713 grouping keep-alives-container { 1714 description 1715 "This grouping is use by both listen and call-home configurations."; 1716 container keep-alives { 1717 description 1718 "Configures the keep-alive policy, to proactively test the 1719 aliveness of the RESTCONF client."; 1720 reference 1721 "RFC VVVV: NETCONF Server and RESTCONF Server Configuration 1722 Models, Section 4"; 1723 leaf interval-secs { 1724 type uint8; 1725 units seconds; 1726 description 1727 "Sets a timeout interval in seconds after which if no data 1728 has been received from the RESTCONF client, a message will 1729 be sent to request a response from the RESTCONF client. A 1730 value of '0' indicates that no keep-alive messages should 1731 be sent."; 1732 } 1733 leaf count-max { 1734 type uint8; 1735 default 3; 1736 description 1737 "Sets the number of keep-alive messages that may be sent 1738 without receiving any data from the RESTCONF client before 1739 assuming the RESTCONF client is no longer alive. If this 1740 threshold is reached, the transport-level connection will 1741 be disconnected, which will trigger the reconnection 1742 strategy). The interval timer is reset after each 1743 transmission, thus an unresponsive RESTCONF client will 1744 be dropped after approximately (count-max * interval-secs) 1745 seconds."; 1746 } 1747 } 1748 } 1749 } 1751 1753 5. Implementation strategy for keep-alives 1755 One of the objectives listed above, Keep-alives for persistent 1756 connections Section 2.6.6, indicates a need for a "keep-alive" 1757 mechanism. This section specifies how the keep-alive mechanism is to 1758 be implemented for both the SSH and TLS transports. 1760 Both SSH and TLS have the ability to support keep-alives securely. 1761 Using the strategies listed below, the keep-alive messages are sent 1762 inside the encrypted tunnel and thus immune to attack. 1764 5.1. Keep-alives for SSH 1766 The SSH keep-alive solution that is expected to be used is ubiquitous 1767 in practice, though never being explicitly defined in an RFC. The 1768 strategy used is to purposely send a malformed request message with a 1769 flag set to ensure a response. More specifically, per section 4 of 1770 [RFC4253], either SSH peer can send a SSH_MSG_GLOBAL_REQUEST message 1771 with "want reply" set to '1' and that, if there is an error, will get 1772 back a SSH_MSG_REQUEST_FAILURE response. Similarly, section 5 of 1773 [RFC4253] says that either SSH peer can send a 1774 SSH_MSG_CHANNEL_REQUEST message with "want reply" set to '1' and 1775 that, if there is an error, will get back a SSH_MSG_CHANNEL_FAILURE 1776 response. 1778 To ensure that the request will fail, current implementations of this 1779 keep-alive strategy (e.g. OpenSSH's `sshd` server) send an invalid 1780 "request name" or "request type", respectively. Abiding to the 1781 extensibility guidelines specified in Section 6 of [RFC4251], these 1782 implementations use the "name@domain". For instance, when configured 1783 to send keep-alives, OpenSSH sends the string 1784 "keepalive@openssh.com". In order to remain compatible with existing 1785 implementations, this draft does not require a specific "request 1786 name" or "request type" string be used, implementations are free to 1787 pick values of their choosing. 1789 5.2. Keep-alives for TLS 1791 The TLS keep-alive solution that is expected to be used is defined in 1792 [RFC6520]. This solution allows both peers to advertise if they can 1793 receive heartbeat request messages from its peer. For standard TLS 1794 connections, devices SHOULD advertise "peer_allowed_to_send", as per 1795 [RFC6520]. This advertisement is not a "MUST" in order to 1796 grandfather existing NETCONF/RESTCONF over TLS implementations. For 1797 NETCONF Call Home or RESTCONF Call Home, the network management 1798 system MUST advertise "peer_allowed_to_send" per [RFC6520]. This is 1799 a "MUST" so as to ensure devices can depend on it always being there 1800 for call home connections, which is when keep-alives are needed the 1801 most. 1803 6. Security Considerations 1805 The YANG modules defined in this memo are designed to be accessed via 1806 the NETCONF protocol [RFC6241]. Authorization for access to specific 1807 portions of conceptual data and operations within this module is 1808 provided by the NETCONF access control model (NACM) [RFC6536]. 1810 There are a number of data nodes defined in the "ietf-netconf-server" 1811 YANG module which are readable and/or writable that may be considered 1812 sensitive or vulnerable in some network environments. Write and read 1813 operations to these data nodes can have a negative effect on network 1814 operations. It is thus important to control write and read access to 1815 these data nodes. Below are the data nodes and their sensitivity/ 1816 vulnerability. 1818 netconf-server/tls/client-auth/trusted-ca-certs: 1820 o This container contains certificates that a NETCONF server is to 1821 use as trust anchors for authenticating X.509-based client 1822 certificates. Write access to this node is protected using an 1823 nacm:default-deny-write statement. 1825 netconf-server/tls/client-auth/trusted-client-certs: 1827 o This container contains certificates that a NETCONF server is to 1828 trust directly when authenticating X.509-based client 1829 certificates. Write access to this node is protected using an 1830 nacm:default-deny-write statement. 1832 restconf-server/tls/client-auth/trusted-ca-certs: 1834 o This container contains certificates that a RESTCONF server is to 1835 use as trust anchors for authenticating X.509-based client 1836 certificates. Write access to this node is protected using an 1837 nacm:default-deny-write statement. 1839 restconf-server/tls/client-auth/trusted-client-certs: 1841 o This container contains certificates that a RESTCONF server is to 1842 trust directly when authenticating X.509-based client 1843 certificates. Write access to this node is protected using an 1844 nacm:default-deny-write statement. 1846 7. IANA Considerations 1848 This document registers two URIs in the IETF XML registry [RFC2119]. 1849 Following the format in [RFC3688], the following registrations are 1850 requested: 1852 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1853 Registrant Contact: The NETCONF WG of the IETF. 1854 XML: N/A, the requested URI is an XML namespace. 1856 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1857 Registrant Contact: The NETCONF WG of the IETF. 1858 XML: N/A, the requested URI is an XML namespace. 1860 This document registers two YANG modules in the YANG Module Names 1861 registry [RFC6020]. Following the format in [RFC6020], the the 1862 following registrations are requested: 1864 name: ietf-netconf-server 1865 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server 1866 prefix: ncserver 1867 reference: RFC VVVV 1869 name: ietf-restconf-server 1870 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1871 prefix: rcserver 1872 reference: RFC VVVV 1874 8. Other Considerations 1876 The YANG modules define herein do not themselves support virtual 1877 routing and forwarding (VRF). It is expected that external modules 1878 will augment in VRF designations when needed. 1880 9. Acknowledgements 1882 The authors would like to thank for following for lively discussions 1883 on list and in the halls (ordered by last name): Andy Bierman, Martin 1884 Bjorklund, Benoit Claise, Mehmet Ersue, David Lamparter, Alan Luchuk, 1885 Ladislav Lhotka, Radek Krejci, Tom Petch, Phil Shafer, and Bert 1886 Wijnen. 1888 Juergen Schoenwaelder and was partly funded by Flamingo, a Network of 1889 Excellence project (ICT-318488) supported by the European Commission 1890 under its Seventh Framework Programme. 1892 10. References 1894 10.1. Normative References 1896 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1897 Requirement Levels", BCP 14, RFC 2119, March 1997. 1899 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1900 Protocol Architecture", RFC 4251, January 2006. 1902 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1903 Transport Layer Protocol", RFC 4253, January 2006. 1905 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1906 Network Configuration Protocol (NETCONF)", RFC 6020, 1907 October 2010. 1909 [RFC6187] Igoe, K. and D. Stebila, "X.509v3 Certificates for Secure 1910 Shell Authentication", RFC 6187, March 2011. 1912 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1913 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1914 6241, June 2011. 1916 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1917 Shell (SSH)", RFC 6242, June 2011. 1919 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1920 Layer Security (TLS) and Datagram Transport Layer Security 1921 (DTLS) Heartbeat Extension", RFC 6520, February 2012. 1923 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1924 Protocol (NETCONF) Access Control Model", RFC 6536, March 1925 2012. 1927 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1928 July 2013. 1930 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1931 SNMP Configuration", RFC 7407, December 2014. 1933 [draft-ietf-netconf-call-home] 1934 Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1935 draft-ieft-netconf-call-home-02 (work in progress), 2014. 1937 [draft-ietf-netconf-restconf] 1938 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1939 Protocol", draft-ieft-netconf-restconf-04 (work in 1940 progress), 2014. 1942 [draft-ietf-netconf-rfc5539bis] 1943 Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1944 NETCONF Protocol over Transport Layer Security (TLS)", 1945 draft-ietf-netconf-rfc5539bis-06 (work in progress), 2014. 1947 10.2. Informative References 1949 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1950 January 2004. 1952 Appendix A. Examples 1954 A.1. NETCONF Configuration using SSH Transport 1956 The following example illustrates the response from a NETCONF 1957 server that only supports SSH, both listening for incoming 1958 connections as well as calling home to a single application having 1959 two endpoints. 1961 1962 1963 600 1964 3600 1965 1966 1967 1968 foo bar 1969 1970
11.22.33.44
1971 1972 my-rsa-key 1973 my-dss-key 1974 1975 1976 1977 1978 1979 1980 config-mgr 1981 1982 1983 1984 east-data-center 1985
11.22.33.44
1986 1987 1988 west-data-center 1989
55.66.77.88
1990 1991 1992 1993 my-call-home-x509-key 1994 1995 1996 1997 1998 1999 2000 2001 2002 QW4gRWFzdGVyIGVnZywgZm9yIHRob3NlIHdobyBtaWdodCBsb29rICA6KQo= 2003 2004 2005 2006 2007 SSBhbSB0aGUgZWdnIG1hbiwgdGhleSBhcmUgdGhlIGVnZyBtZW4uCg== 2008 2009 2010 SSBhbSB0aGUgd2FscnVzLCBnb28gZ29vIGcnam9vYi4K 2011 2012 2013 2014 2015 2017 A.2. NETCONF Configuration using TLS Transport 2019 The following example illustrates the response from a NETCONF 2020 server that only supports TLS, both listening for incoming 2021 connections as well as calling home to a single application having 2022 two endpoints. Please note also the configurations for 2023 authenticating client certificates and mappings authenticated 2024 certificates to NETCONF user names. 2026 2027 2028 600 2029 3600 2030 2031 2032 2033 primary-netconf-endpoint 2034 2035
11.22.33.44
2036 2037 fw1.east.example.com 2038 2039 2040 2041 2042 2043 2044 config-mgr 2045 2046 2047 2048 east-data-center 2049
11.22.33.44
2050 2051 2052 west-data-center 2053
55.66.77.88
2054 2055 2056 2057 fw1.east.example.com 2058 2059 2060 2061 2062 2063 2064 2065 2066 QW4gRWFzdGVyIGVnZywgZm9yIHRob3NlIHdobyBtaWdodCBsb29rICA6KQo= 2067 2068 2069 2070 2071 SSBhbSB0aGUgZWdnIG1hbiwgdGhleSBhcmUgdGhlIGVnZyBtZW4uCg== 2072 2073 2074 SSBhbSB0aGUgd2FscnVzLCBnb28gZ29vIGcnam9vYi4K 2075 2076 2077 2078 2079 1 2080 11:0A:05:11:00 2081 x509c2n:san-any 2082 2083 2084 2 2085 11:0A:05:11:00 2086 x509c2n:specified 2087 Joe Cool 2088 2089 2090 2091 2092 2093 A.3. RESTCONF Configuration using TLS Transport 2095 The following example illustrates the response from a RESTCONF 2096 server that only supports TLS, both listening for incoming 2097 connections as well as calling home to a single application having 2098 two endpoints. 2100 2101 2102 2103 primary-restconf-endpoint 2104 2105
11.22.33.44
2106 2107 fw1.east.example.com 2108 2109 2110 2111 2112 2113 2114 config-mgr 2115 2116 2117 2118 east-data-center 2119
11.22.33.44
2120 2121 2122 west-data-center 2123
55.66.77.88
2124 2125 2126 2127 fw1.east.example.com 2128 2129 2130 2131 2132 2134 Appendix B. Change Log 2136 B.1. 00 to 01 2138 o Restructured document so it flows better 2139 o Added trusted-ca-certs and trusted-client-certs objects into the 2140 ietf-system-tls-auth module 2142 B.2. 01 to 02 2144 o removed the "one-to-many" construct 2146 o removed "address" as a key field 2148 o removed "network-manager" terminology 2150 o moved open issues to github issues 2152 o brought TLS client auth back into model 2154 B.3. 02 to 03 2156 o fixed tree diagrams and surrounding text 2158 B.4. 03 to 04 2160 o reduced the number of grouping statements 2162 o removed psk-maps and associated feature statements 2164 o added ability for listen/call-home instances to specify which 2165 host-keys/certificates (of all listed) to use 2167 o clarified that last-connected should span reboots 2169 o added missing "objectives" for selecting which keys to use, 2170 authenticating client-certificates, and mapping authenticated 2171 client-certificates to usernames 2173 o clarified indirect client certificate authentication 2175 o added keep-alive configuration for listen connections 2177 o added global-level NETCONF session parameters 2179 B.5. 04 to 05 2181 o Removed all refs to the old ietf-system-tls-auth module 2183 o Removed YANG 1.1 style if-feature statements (loss some 2184 expressiveness) 2186 o Removed the read-only (config false) lists of SSH host-keys and 2187 TLS certs 2189 o Added an if-feature around session-options container 2191 o Added ability to configure trust-anchors for SSH X.509 client 2192 certs 2194 o Now imports by revision, per best practice 2196 o Added support for RESTCONF server 2198 o Added RFC Editor instructions 2200 B.6. 05 to 06 2202 o Removed feature statement on the session-options container (issue 2203 #21). 2205 o Added NACM statements to YANG modules for sensitive nodes (issue 2206 #24). 2208 o Fixed default RESTCONF server port value to be 443 (issue #26). 2210 o Added client-cert-auth subtree to ietf-restconf-server module 2211 (issue #27). 2213 o Updated draft-ietf-netmod-snmp-cfg reference to RFC 7407 (issue 2214 #28). 2216 o Added description statements for groupings (issue #29). 2218 o Added description for braces to tree diagram section (issue #30). 2220 o Renamed feature from "rfc6187" to "ssh-x509-certs" (issue #31). 2222 Appendix C. Open Issues 2224 Please see: https://github.com/netconf-wg/server-model/issues. 2226 Authors' Addresses 2228 Kent Watsen 2229 Juniper Networks 2231 EMail: kwatsen@juniper.net 2232 Juergen Schoenwaelder 2233 Jacobs University Bremen 2235 EMail: j.schoenwaelder@jacobs-university.de