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