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