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