idnits 2.17.1
draft-ietf-netconf-restconf-client-server-10.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (March 9, 2019) is 1846 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-35) exists of
draft-ietf-netconf-keystore-08
== Outdated reference: A later version (-41) exists of
draft-ietf-netconf-tls-client-server-08
== Outdated reference: A later version (-05) exists of
draft-kwatsen-netconf-http-client-server-00
== Outdated reference: A later version (-02) exists of
draft-kwatsen-netconf-tcp-client-server-00
== Outdated reference: A later version (-36) exists of
draft-ietf-netconf-netconf-client-server-08
Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 NETCONF Working Group K. Watsen
3 Internet-Draft Watsen Networks
4 Intended status: Standards Track March 9, 2019
5 Expires: September 10, 2019
7 RESTCONF Client and Server Models
8 draft-ietf-netconf-restconf-client-server-10
10 Abstract
12 This document defines two YANG modules, one module to configure a
13 RESTCONF client and the other module to configure a RESTCONF server.
14 Both modules support the TLS transport protocol with both standard
15 RESTCONF and RESTCONF 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-tcp-client-server
33 o I-D.ietf-netconf-tls-client-server
35 o I-D.ietf-netconf-http-client-server
37 Artwork in this document contains shorthand references to drafts in
38 progress. Please apply the following replacements:
40 o "XXXX" --> the assigned RFC value for this draft
42 o "AAAA" --> the assigned RFC value for I-D.ietf-netconf-tcp-client-
43 server
45 o "CCCC" --> the assigned RFC value for I-D.ietf-netconf-tls-client-
46 server
48 o "BBBB" --> the assigned RFC value for I-D.ietf-netconf-http-
49 client-server
51 Artwork in this document contains placeholder values for the date of
52 publication of this draft. Please apply the following replacement:
54 o "2019-03-09" --> the publication date of this draft
56 The following Appendix section is to be removed prior to publication:
58 o Appendix A. Change Log
60 Status of This Memo
62 This Internet-Draft is submitted in full conformance with the
63 provisions of BCP 78 and BCP 79.
65 Internet-Drafts are working documents of the Internet Engineering
66 Task Force (IETF). Note that other groups may also distribute
67 working documents as Internet-Drafts. The list of current Internet-
68 Drafts is at https://datatracker.ietf.org/drafts/current/.
70 Internet-Drafts are draft documents valid for a maximum of six months
71 and may be updated, replaced, or obsoleted by other documents at any
72 time. It is inappropriate to use Internet-Drafts as reference
73 material or to cite them other than as "work in progress."
75 This Internet-Draft will expire on September 10, 2019.
77 Copyright Notice
79 Copyright (c) 2019 IETF Trust and the persons identified as the
80 document authors. All rights reserved.
82 This document is subject to BCP 78 and the IETF Trust's Legal
83 Provisions Relating to IETF Documents
84 (https://trustee.ietf.org/license-info) in effect on the date of
85 publication of this document. Please review these documents
86 carefully, as they describe your rights and restrictions with respect
87 to this document. Code Components extracted from this document must
88 include Simplified BSD License text as described in Section 4.e of
89 the Trust Legal Provisions and are provided without warranty as
90 described in the Simplified BSD License.
92 Table of Contents
94 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
95 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
96 2. The RESTCONF Client Model . . . . . . . . . . . . . . . . . . 4
97 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4
98 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9
99 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12
100 3. The RESTCONF Server Model . . . . . . . . . . . . . . . . . . 20
101 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 21
102 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24
103 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 27
104 4. Security Considerations . . . . . . . . . . . . . . . . . . . 36
105 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
106 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 37
107 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 38
108 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
109 6.1. Normative References . . . . . . . . . . . . . . . . . . 38
110 6.2. Informative References . . . . . . . . . . . . . . . . . 39
111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 41
112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 41
113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 41
114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 41
115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 41
116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 41
117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 42
118 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 42
119 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 42
120 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 42
121 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 42
122 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 43
123 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 43
125 1. Introduction
127 This document defines two YANG [RFC7950] modules, one module to
128 configure a RESTCONF client and the other module to configure a
129 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446]
130 transport protocol with both standard RESTCONF and RESTCONF Call Home
131 connections [RFC8071].
133 1.1. Terminology
135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
137 "OPTIONAL" in this document are to be interpreted as described in BCP
138 14 [RFC2119] [RFC8174] when, and only when, they appear in all
139 capitals, as shown here.
141 2. The RESTCONF Client Model
143 The RESTCONF client model presented in this section supports both
144 clients initiating connections to servers, as well as clients
145 listening for connections from servers calling home.
147 This model, like that presented in
148 [I-D.ietf-netconf-netconf-client-server], is designed to support any
149 number of possible transports. RESTCONF only supports the TLS
150 transport currently, thus this model only supports the TLS transport.
152 All private keys and trusted certificates are held in the keystore
153 model defined in [I-D.ietf-netconf-keystore].
155 YANG feature statements are used to enable implementations to
156 advertise which parts of the model the RESTCONF client supports.
158 2.1. Tree Diagram
160 The following tree diagram [RFC8340] provides an overview of the data
161 model for the "ietf-restconf-client" module. Just the container is
162 displayed below, but there is also a reusable grouping called
163 "restconf-client-grouping" that the container is using.
165 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
167 module: ietf-restconf-client
168 +--rw restconf-client
169 +--rw initiate! {initiate}?
170 | +--rw restconf-server* [name]
171 | +--rw name string
172 | +--rw endpoints
173 | +--rw endpoint* [name]
174 | +--rw name string
175 | +--rw (transport)
176 | | +--:(https) {https-initiate}?
177 | | +--rw https
178 | | +--rw remote-address inet:host
179 | | +--rw remote-port?
180 | | | inet:port-number
181 | | +--rw local-address? inet:ip-addr\
182 \ess
183 | | +--rw local-port?
184 | | | inet:port-number
185 | | +--rw tcp-keepalives {tcp-client-keepalive\
186 \s}?
187 | | | +--rw idle-time? uint16
188 | | | +--rw max-probes? uint16
189 | | | +--rw probe-interval? uint16
190 | | +--rw tls-client-identity
191 | | | +--rw (auth-type)
192 | | | +--:(certificate)
193 | | | +--rw certificate
194 | | | +--rw (local-or-keystore)
195 | | | +--:(local)
196 | | | | {local-keys-suppor\
197 \ted}?
198 | | | | +--rw local-definition
199 | | | | +--rw algorithm?
200 | | | | | asymmetric-ke\
201 \y-algorithm-ref
202 | | | | +--rw public-key?
203 | | | | | binary
204 | | | | +--rw private-key?
205 | | | | | union
206 | | | | +---x generate-hidden\
207 \-key
208 | | | | | +---w input
209 | | | | | +---w algorithm
210 | | | | | asymmet\
211 \ric-key-algorithm-ref
212 | | | | +---x install-hidden-\
213 \key
214 | | | | | +---w input
215 | | | | | +---w algorithm
216 | | | | | | asymmet\
217 \ric-key-algorithm-ref
218 | | | | | +---w public-ke\
219 \y?
220 | | | | | | binary
221 | | | | | +---w private-k\
222 \ey?
223 | | | | | binary
224 | | | | +--rw cert?
225 | | | | | end-entity-ce\
226 \rt-cms
227 | | | | +---n certificate-exp\
228 \iration
229 | | | | +-- expiration-date
230 | | | | yang:date-\
231 \and-time
232 | | | +--:(keystore)
233 | | | {keystore-supporte\
234 \d}?
235 | | | +--rw keystore-reference?
236 | | | ks:asymmetric-ke\
238 \y-certificate-ref
239 | | +--rw tls-server-auth
240 | | | +--rw pinned-ca-certs?
241 | | | | ta:pinned-certificates-ref
242 | | | | {ta:x509-certificates}?
243 | | | +--rw pinned-server-certs?
244 | | | ta:pinned-certificates-ref
245 | | | {ta:x509-certificates}?
246 | | +--rw tls-hello-params
247 | | | {tls-client-hello-params-config}?
248 | | | +--rw tls-versions
249 | | | | +--rw tls-version* identityref
250 | | | +--rw cipher-suites
251 | | | +--rw cipher-suite* identityref
252 | | +--rw tls-keepalives {tls-client-keepalive\
253 \s}?
254 | | | +--rw max-wait? uint16
255 | | | +--rw max-attempts? uint8
256 | | +--rw http-client-identity
257 | | | +--rw (auth-type)?
258 | | | +--:(basic)
259 | | | | +--rw basic
260 | | | | +--rw user-id? string
261 | | | | +--rw password? string
262 | | | +--:(bearer)
263 | | | | +--rw bearer
264 | | | | +--rw token? string
265 | | | +--:(digest)
266 | | | | +--rw digest
267 | | | | +--rw username? string
268 | | | | +--rw password? string
269 | | | +--:(hoba)
270 | | | | +--rw hoba
271 | | | +--:(mutual)
272 | | | | +--rw mutual
273 | | | +--:(negotiate)
274 | | | | +--rw negotiate
275 | | | +--:(oauth)
276 | | | | +--rw oauth
277 | | | +--:(scram-sha-1)
278 | | | | +--rw scram-sha-1
279 | | | +--:(scram-sha-256)
280 | | | | +--rw scram-sha-256
281 | | | +--:(vapid)
282 | | | +--rw vapid
283 | | +--rw http-keepalives
284 | | {http-client-keepalives}?
285 | | +--rw max-wait? uint16
286 | | +--rw max-attempts? uint8
287 | +--rw connection-type
288 | | +--rw (connection-type)
289 | | +--:(persistent-connection)
290 | | | +--rw persistent!
291 | | +--:(periodic-connection)
292 | | +--rw periodic!
293 | | +--rw period? uint16
294 | | +--rw anchor-time? yang:date-and-time
295 | | +--rw idle-timeout? uint16
296 | +--rw reconnect-strategy
297 | +--rw start-with? enumeration
298 | +--rw max-attempts? uint8
299 +--rw listen! {listen}?
300 +--rw idle-timeout? uint16
301 +--rw endpoint* [name]
302 +--rw name string
303 +--rw (transport)
304 +--:(https) {https-listen}?
305 +--rw https
306 +--rw local-address inet:ip-address
307 +--rw local-port? inet:port-number
308 +--rw tcp-keepalives {tcp-server-keepalives}?
309 | +--rw idle-time? uint16
310 | +--rw max-probes? uint16
311 | +--rw probe-interval? uint16
312 +--rw tls-client-identity
313 | +--rw (auth-type)
314 | +--:(certificate)
315 | +--rw certificate
316 | +--rw (local-or-keystore)
317 | +--:(local) {local-keys-supported\
318 \}?
319 | | +--rw local-definition
320 | | +--rw algorithm?
321 | | | asymmetric-key-algo\
322 \rithm-ref
323 | | +--rw public-key?
324 | | | binary
325 | | +--rw private-key?
326 | | | union
327 | | +---x generate-hidden-key
328 | | | +---w input
329 | | | +---w algorithm
330 | | | asymmetric-ke\
331 \y-algorithm-ref
332 | | +---x install-hidden-key
333 | | | +---w input
334 | | | +---w algorithm
335 | | | | asymmetric-ke\
336 \y-algorithm-ref
337 | | | +---w public-key?
338 | | | | binary
339 | | | +---w private-key?
340 | | | binary
341 | | +--rw cert?
342 | | | end-entity-cert-cms
343 | | +---n certificate-expiration
344 | | +-- expiration-date
345 | | yang:date-and-ti\
346 \me
347 | +--:(keystore) {keystore-supporte\
348 \d}?
349 | +--rw keystore-reference?
350 | ks:asymmetric-key-cert\
351 \ificate-ref
352 +--rw tls-server-auth
353 | +--rw pinned-ca-certs?
354 | | ta:pinned-certificates-ref
355 | | {ta:x509-certificates}?
356 | +--rw pinned-server-certs?
357 | ta:pinned-certificates-ref
358 | {ta:x509-certificates}?
359 +--rw tls-hello-params
360 | {tls-client-hello-params-config}?
361 | +--rw tls-versions
362 | | +--rw tls-version* identityref
363 | +--rw cipher-suites
364 | +--rw cipher-suite* identityref
365 +--rw tls-keepalives {tls-client-keepalives}?
366 | +--rw max-wait? uint16
367 | +--rw max-attempts? uint8
368 +--rw http-client-identity
369 | +--rw (auth-type)?
370 | +--:(basic)
371 | | +--rw basic
372 | | +--rw user-id? string
373 | | +--rw password? string
374 | +--:(bearer)
375 | | +--rw bearer
376 | | +--rw token? string
377 | +--:(digest)
378 | | +--rw digest
379 | | +--rw username? string
380 | | +--rw password? string
381 | +--:(hoba)
382 | | +--rw hoba
383 | +--:(mutual)
384 | | +--rw mutual
385 | +--:(negotiate)
386 | | +--rw negotiate
387 | +--:(oauth)
388 | | +--rw oauth
389 | +--:(scram-sha-1)
390 | | +--rw scram-sha-1
391 | +--:(scram-sha-256)
392 | | +--rw scram-sha-256
393 | +--:(vapid)
394 | +--rw vapid
395 +--rw http-keepalives {http-client-keepalives}?
396 +--rw max-wait? uint16
397 +--rw max-attempts? uint8
399 2.2. Example Usage
401 The following example illustrates configuring a RESTCONF client to
402 initiate connections, as well as listening for call-home connections.
404 This example is consistent with the examples presented in Section 3.2
405 of [I-D.ietf-netconf-keystore].
407 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
409
file "ietf-restconf-client@2019-03-09.yang"
549 module ietf-restconf-client {
550 yang-version 1.1;
551 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client";
552 prefix rcc;
554 import ietf-yang-types {
555 prefix yang;
556 reference
557 "RFC 6991: Common YANG Data Types";
558 }
560 import ietf-tcp-client {
561 prefix tcpc;
562 reference
563 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
564 }
566 import ietf-tcp-server {
567 prefix tcps;
568 reference
569 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
570 }
572 import ietf-tls-client {
573 prefix tlsc;
574 reference
575 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers";
577 }
579 import ietf-http-client {
580 prefix httpc;
581 reference
582 "RFC CCCC: YANG Groupings for HTTP Clients and HTTP Servers";
583 }
585 organization
586 "IETF NETCONF (Network Configuration) Working Group";
588 contact
589 "WG Web:
590 WG List:
591 Author: Kent Watsen
592 Author: Gary Wu ";
594 description
595 "This module contains a collection of YANG definitions for
596 configuring RESTCONF clients.
598 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
599 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
600 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
601 are to be interpreted as described in BCP 14 [RFC2119]
602 [RFC8174] when, and only when, they appear in all
603 capitals, as shown here.
605 Copyright (c) 2019 IETF Trust and the persons identified as
606 authors of the code. All rights reserved.
608 Redistribution and use in source and binary forms, with or
609 without modification, is permitted pursuant to, and subject
610 to the license terms contained in, the Simplified BSD
611 License set forth in Section 4.c of the IETF Trust's
612 Legal Provisions Relating to IETF Documents
613 (http://trustee.ietf.org/license-info).
615 This version of this YANG module is part of RFC XXXX; see
616 the RFC itself for full legal notices.";
618 revision 2019-03-09 {
619 description
620 "Initial version";
621 reference
622 "RFC XXXX: RESTCONF Client and Server Models";
623 }
624 // Features
626 feature initiate {
627 description
628 "The 'initiate' feature indicates that the RESTCONF client
629 supports initiating RESTCONF connections to RESTCONF servers
630 using at least one transport (e.g., HTTPS, etc.).";
631 }
633 feature https-initiate {
634 if-feature "initiate";
635 description
636 "The 'https-initiate' feature indicates that the RESTCONF
637 client supports initiating HTTPS connections to RESTCONF
638 servers. This feature exists as HTTPS might not be a
639 mandatory to implement transport in the future.";
640 reference
641 "RFC 8040: RESTCONF Protocol";
642 }
644 feature listen {
645 description
646 "The 'listen' feature indicates that the RESTCONF client
647 supports opening a port to accept RESTCONF server call
648 home connections using at least one transport (e.g.,
649 HTTPS, etc.).";
650 }
652 feature https-listen {
653 if-feature "listen";
654 description
655 "The 'https-listen' feature indicates that the RESTCONF client
656 supports opening a port to listen for incoming RESTCONF
657 server call-home connections. This feature exists as not
658 all RESTCONF clients may support RESTCONF call home.";
659 reference
660 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
661 }
663 // Groupings
665 grouping restconf-client-grouping {
666 description
667 "Top-level grouping for RESTCONF client configuration.";
668 container initiate {
669 if-feature "initiate";
670 presence "Enables client to initiate TCP connections";
671 description
672 "Configures client initiating underlying TCP connections.";
673 list restconf-server {
674 key "name";
675 min-elements 1;
676 description
677 "List of RESTCONF servers the RESTCONF client is to
678 initiate connections to in parallel.";
679 leaf name {
680 type string;
681 description
682 "An arbitrary name for the RESTCONF server.";
683 }
684 container endpoints {
685 description
686 "Container for the list of endpoints.";
687 list endpoint {
688 key "name";
689 min-elements 1;
690 ordered-by user;
691 description
692 "A non-empty user-ordered list of endpoints for this
693 RESTCONF client to try to connect to in sequence.
694 Defining more than one enables high-availability.";
695 leaf name {
696 type string;
697 description
698 "An arbitrary name for this endpoint.";
699 }
700 choice transport {
701 mandatory true;
702 description
703 "Selects between available transports. This is a
704 'choice' statement so as to support additional
705 transport options to be augmented in.";
706 case https {
707 if-feature "https-initiate";
708 container https {
709 description
710 "Specifies HTTPS-specific transport
711 configuration.";
712 uses tcpc:tcp-client-grouping {
713 refine "remote-port" {
714 default "443";
715 description
716 "The RESTCONF client will attempt to
717 connect to the IANA-assigned well-known
718 port value for 'https' (443) if no value
719 is specified.";
721 }
722 }
723 uses tlsc:tls-client-grouping {
724 refine "tls-client-identity/auth-type" {
725 mandatory true;
726 description
727 "RESTCONF clients MUST pass some
728 authentication credentials.";
729 }
730 }
731 uses httpc:http-client-grouping;
732 }
733 } // https
734 } // transport
735 container connection-type {
736 description
737 "Indicates the RESTCONF client's preference for how
738 the RESTCONF connection is maintained.";
739 choice connection-type {
740 mandatory true;
741 description
742 "Selects between available connection types.";
743 case persistent-connection {
744 container persistent {
745 presence "Indicates that a persistent connection
746 is to be maintained.";
747 description
748 "Maintain a persistent connection to the
749 RESTCONF server. If the connection goes down,
750 immediately start trying to reconnect to it,
751 using the reconnection strategy. This
752 connection type minimizes any RESTCONF server
753 to RESTCONF client data-transfer delay, albeit
754 at the expense of holding resources longer.";
755 }
756 }
757 case periodic-connection {
758 container periodic {
759 presence "Indicates that a periodic connection is
760 to be maintained.";
761 description
762 "Periodically connect to the RESTCONF server.
763 The RESTCONF server should close the
764 underlying TCP connection upon completing
765 planned activities.
767 This connection type increases resource
768 utilization, albeit with increased delay in
769 RESTCONF server to RESTCONF client
770 interactions.";
771 leaf period {
772 type uint16;
773 units "minutes";
774 default "60";
775 description
776 "Duration of time between periodic
777 connections.";
778 }
779 leaf anchor-time {
780 type yang:date-and-time {
781 // constrained to minute-level granularity
782 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}'
783 + '(Z|[\+\-]\d{2}:\d{2})';
784 }
785 description
786 "Designates a timestamp before or after which
787 a series of periodic connections are
788 determined. The periodic connections occur
789 at a whole multiple interval from the anchor
790 time. For example, for an anchor time is 15
791 minutes past midnight and a period interval
792 of 24 hours, then a periodic connection will
793 occur 15 minutes past midnight everyday.";
794 }
795 leaf idle-timeout {
796 type uint16;
797 units "seconds";
798 default 120; // two minutes
799 description
800 "Specifies the maximum number of seconds
801 that the underlying TCP session may remain
802 idle. A TCP session will be dropped if it
803 is idle for an interval longer than this
804 number of seconds If set to zero, then the
805 RESTCONF client will never drop a session
806 because it is idle.";
807 }
808 }
809 } // periodic-connection
810 } // connection-type
811 } // connection-type
812 container reconnect-strategy {
813 description
814 "The reconnection strategy directs how a RESTCONF
815 client reconnects to a RESTCONF server, after
816 discovering its connection to the server has
817 dropped, even if due to a reboot. The RESTCONF
818 client starts with the specified endpoint and
819 tries to connect to it max-attempts times before
820 trying the next endpoint in the list (round
821 robin).";
822 leaf start-with {
823 type enumeration {
824 enum first-listed {
825 description
826 "Indicates that reconnections should start
827 with the first endpoint listed.";
828 }
829 enum last-connected {
830 description
831 "Indicates that reconnections should start
832 with the endpoint last connected to. If
833 no previous connection has ever been
834 established, then the first endpoint
835 configured is used. RESTCONF clients
836 SHOULD be able to remember the last
837 endpoint connected to across reboots.";
838 }
839 enum random-selection {
840 description
841 "Indicates that reconnections should start with
842 a random endpoint.";
843 }
844 }
845 default "first-listed";
846 description
847 "Specifies which of the RESTCONF server's
848 endpoints the RESTCONF client should start
849 with when trying to connect to the RESTCONF
850 server.";
851 }
852 leaf max-attempts {
853 type uint8 {
854 range "1..max";
855 }
856 default "3";
857 description
858 "Specifies the number times the RESTCONF client
859 tries to connect to a specific endpoint before
860 moving on to the next endpoint in the list
861 (round robin).";
862 }
863 } // reconnect-strategy
864 } // endpoint
866 } // endpoints
867 } // restconf-server
868 } // initiate
870 container listen {
871 if-feature "listen";
872 presence "Enables client to accept call-home connections";
873 description
874 "Configures client accepting call-home TCP connections.";
875 leaf idle-timeout {
876 type uint16;
877 units "seconds";
878 default 3600; // one hour
879 description
880 "Specifies the maximum number of seconds that an
881 underlying TCP session may remain idle. A TCP session
882 will be dropped if it is idle for an interval longer
883 than this number of seconds. If set to zero, then
884 the server will never drop a session because it is
885 idle. Sessions that have a notification subscription
886 active are never dropped.";
887 }
888 list endpoint {
889 key "name";
890 min-elements 1;
891 description
892 "List of endpoints to listen for RESTCONF connections.";
893 leaf name {
894 type string;
895 description
896 "An arbitrary name for the RESTCONF listen endpoint.";
897 }
898 choice transport {
899 mandatory true;
900 description
901 "Selects between available transports. This is a
902 'choice' statement so as to support additional
903 transport options to be augmented in.";
904 case https {
905 if-feature "https-listen";
906 container https {
907 description
908 "HTTPS-specific listening configuration for inbound
909 connections.";
910 uses tcps:tcp-server-grouping {
911 refine "local-port" {
912 default "4336";
913 description
914 "The RESTCONF client will listen on the IANA-
915 assigned well-known port for 'restconf-ch-tls'
916 (4336) if no value is specified.";
917 }
918 }
919 uses tlsc:tls-client-grouping {
920 refine "tls-client-identity/auth-type" {
921 mandatory true;
922 description
923 "RESTCONF clients MUST pass some authentication
924 credentials.";
925 }
926 }
927 uses httpc:http-client-grouping;
928 }
929 } // case https
930 } // transport
931 } // endpoint
932 } // listen
933 } // restconf-client
935 // Protocol accessible node, for servers that implement this
936 // module.
938 container restconf-client {
939 uses restconf-client-grouping;
940 description
941 "Top-level container for RESTCONF client configuration.";
942 }
943 }
944
946 3. The RESTCONF Server Model
948 The RESTCONF server model presented in this section supports servers
949 both listening for connections as well as initiating call-home
950 connections.
952 All private keys and trusted certificates are held in the keystore
953 model defined in [I-D.ietf-netconf-keystore].
955 YANG feature statements are used to enable implementations to
956 advertise which parts of the model the RESTCONF server supports.
958 3.1. Tree Diagram
960 The following tree diagram [RFC8340] provides an overview of the data
961 model for the "ietf-restconf-server" module. Just the container is
962 displayed below, but there is also a reusable grouping called
963 "restconf-server-grouping" that the container is using.
965 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
967 module: ietf-restconf-server
968 +--rw restconf-server
969 +--rw listen! {listen}?
970 | +--rw endpoint* [name]
971 | +--rw name string
972 | +--rw (transport)
973 | +--:(https) {https-listen}?
974 | +--rw https
975 | +--rw local-address inet:ip-address
976 | +--rw local-port? inet:port-number
977 | +--rw tcp-keepalives {tcp-server-keepalives}?
978 | | +--rw idle-time? uint16
979 | | +--rw max-probes? uint16
980 | | +--rw probe-interval? uint16
981 | +--rw tls-server-identity
982 | | +--rw (local-or-keystore)
983 | | +--:(local) {local-keys-supported}?
984 | | | +--rw local-definition
985 | | | +--rw algorithm?
986 | | | | asymmetric-key-algorithm-ref
987 | | | +--rw public-key? bina\
988 \ry
989 | | | +--rw private-key? union
990 | | | +---x generate-hidden-key
991 | | | | +---w input
992 | | | | +---w algorithm
993 | | | | asymmetric-key-algorit\
994 \hm-ref
995 | | | +---x install-hidden-key
996 | | | | +---w input
997 | | | | +---w algorithm
998 | | | | | asymmetric-key-algorit\
999 \hm-ref
1000 | | | | +---w public-key? binary
1001 | | | | +---w private-key? binary
1002 | | | +--rw cert?
1003 | | | | end-entity-cert-cms
1004 | | | +---n certificate-expiration
1005 | | | +-- expiration-date
1006 | | | yang:date-and-time
1007 | | +--:(keystore) {keystore-supported}?
1008 | | +--rw keystore-reference?
1009 | | ks:asymmetric-key-certificate-r\
1010 \ef
1011 | +--rw tls-client-auth
1012 | | +--rw pinned-ca-certs?
1013 | | | ta:pinned-certificates-ref
1014 | | | {ta:x509-certificates}?
1015 | | +--rw pinned-client-certs?
1016 | | | ta:pinned-certificates-ref
1017 | | | {ta:x509-certificates}?
1018 | | +--rw cert-maps
1019 | | +--rw cert-to-name* [id]
1020 | | +--rw id uint32
1021 | | +--rw fingerprint
1022 | | | x509c2n:tls-fingerprint
1023 | | +--rw map-type identityref
1024 | | +--rw name string
1025 | +--rw tls-hello-params
1026 | | {tls-server-hello-params-config}?
1027 | | +--rw tls-versions
1028 | | | +--rw tls-version* identityref
1029 | | +--rw cipher-suites
1030 | | +--rw cipher-suite* identityref
1031 | +--rw tls-keepalives {tls-server-keepalives}?
1032 | | +--rw max-wait? uint16
1033 | | +--rw max-attempts? uint8
1034 | +--rw http-keepalives {http-server-keepalives}?
1035 | +--rw max-wait? uint16
1036 | +--rw max-attempts? uint8
1037 +--rw call-home! {call-home}?
1038 +--rw restconf-client* [name]
1039 +--rw name string
1040 +--rw endpoints
1041 | +--rw endpoint* [name]
1042 | +--rw name string
1043 | +--rw (transport)
1044 | +--:(https) {https-call-home}?
1045 | +--rw https
1046 | +--rw remote-address inet:host
1047 | +--rw remote-port? inet:port-num\
1048 \ber
1049 | +--rw local-address? inet:ip-addre\
1050 \ss
1051 | +--rw local-port? inet:port-num\
1052 \ber
1053 | +--rw tcp-keepalives {tcp-client-keepalive\
1055 \s}?
1056 | | +--rw idle-time? uint16
1057 | | +--rw max-probes? uint16
1058 | | +--rw probe-interval? uint16
1059 | +--rw tls-server-identity
1060 | | +--rw (local-or-keystore)
1061 | | +--:(local) {local-keys-supported}?
1062 | | | +--rw local-definition
1063 | | | +--rw algorithm?
1064 | | | | asymmetric-key-algorit\
1065 \hm-ref
1066 | | | +--rw public-key?
1067 | | | | binary
1068 | | | +--rw private-key?
1069 | | | | union
1070 | | | +---x generate-hidden-key
1071 | | | | +---w input
1072 | | | | +---w algorithm
1073 | | | | asymmetric-key-a\
1074 \lgorithm-ref
1075 | | | +---x install-hidden-key
1076 | | | | +---w input
1077 | | | | +---w algorithm
1078 | | | | | asymmetric-key-a\
1079 \lgorithm-ref
1080 | | | | +---w public-key? bin\
1081 \ary
1082 | | | | +---w private-key? bin\
1083 \ary
1084 | | | +--rw cert?
1085 | | | | end-entity-cert-cms
1086 | | | +---n certificate-expiration
1087 | | | +-- expiration-date
1088 | | | yang:date-and-time
1089 | | +--:(keystore) {keystore-supported}?
1090 | | +--rw keystore-reference?
1091 | | ks:asymmetric-key-certifi\
1092 \cate-ref
1093 | +--rw tls-client-auth
1094 | | +--rw pinned-ca-certs?
1095 | | | ta:pinned-certificates-ref
1096 | | | {ta:x509-certificates}?
1097 | | +--rw pinned-client-certs?
1098 | | | ta:pinned-certificates-ref
1099 | | | {ta:x509-certificates}?
1100 | | +--rw cert-maps
1101 | | +--rw cert-to-name* [id]
1102 | | +--rw id uint32
1103 | | +--rw fingerprint
1104 | | | x509c2n:tls-fingerprint
1105 | | +--rw map-type identityref
1106 | | +--rw name string
1107 | +--rw tls-hello-params
1108 | | {tls-server-hello-params-config}?
1109 | | +--rw tls-versions
1110 | | | +--rw tls-version* identityref
1111 | | +--rw cipher-suites
1112 | | +--rw cipher-suite* identityref
1113 | +--rw tls-keepalives {tls-server-keepalive\
1114 \s}?
1115 | | +--rw max-wait? uint16
1116 | | +--rw max-attempts? uint8
1117 | +--rw http-keepalives
1118 | {http-server-keepalives}?
1119 | +--rw max-wait? uint16
1120 | +--rw max-attempts? uint8
1121 +--rw connection-type
1122 | +--rw (connection-type)
1123 | +--:(persistent-connection)
1124 | | +--rw persistent!
1125 | +--:(periodic-connection)
1126 | +--rw periodic!
1127 | +--rw period? uint16
1128 | +--rw anchor-time? yang:date-and-time
1129 | +--rw idle-timeout? uint16
1130 +--rw reconnect-strategy
1131 +--rw start-with? enumeration
1132 +--rw max-attempts? uint8
1134 3.2. Example Usage
1136 The following example illustrates configuring a RESTCONF server to
1137 listen for RESTCONF client connections, as well as configuring call-
1138 home to one RESTCONF client.
1140 This example is consistent with the examples presented in Section 3.2
1141 of [I-D.ietf-netconf-keystore].
1143 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
1145
1149
1150
1151
1152 netconf/tls
1153
1154 11.22.33.44
1155
1156
1157 ct:rsa2048
1159 base64encodedvalue==
1160 base64encodedvalue==
1161 base64encodedvalue==
1162
1163
1164
1165 explicitly-trusted-client-ca-certs
1167 explicitly-trusted-client-certs
1169
1170
1171 1
1172 11:0A:05:11:00
1173 x509c2n:san-any
1174
1175
1176 2
1177 B3:4F:A1:8C:54
1178 x509c2n:specified
1179 scooby-doo
1180
1181
1182
1183
1184
1185
1187
1188
1189
1190 config-manager
1191
1192
1193 east-data-center
1194
1195 east.example.com
1196
1197
1198 ct:rsa2048
1201 base64encodedvalue==
1202 base64encodedvalue==
1203 base64encodedvalue==
1204
1205
1206
1207 explicitly-trusted-client-ca-certs
1209 explicitly-trusted-client-certs\
1210 \pinned-client-certs>
1211
1212
1213 1
1214 11:0A:05:11:00
1215 x509c2n:san-any
1216
1217
1218 2
1219 B3:4F:A1:8C:54
1220 x509c2n:specified
1221 scooby-doo
1222
1223
1224
1225
1226
1227
1228 west-data-center
1229
1230 west.example.com
1231
1232 15
1233 3
1234 30
1235
1236
1237
1238 ct:rsa2048
1240 base64encodedvalue==
1241 base64encodedvalue==
1242 base64encodedvalue==
1243
1244
1245
1246 explicitly-trusted-client-ca-certs
1248 explicitly-trusted-client-certs\
1249 \pinned-client-certs>
1250
1251
1252 1
1253 11:0A:05:11:00
1254 x509c2n:san-any
1255
1256
1257 2
1258 B3:4F:A1:8C:54
1259 x509c2n:specified
1260 scooby-doo
1261
1262
1263
1264
1265 30
1266 3
1267
1268
1269
1270
1271
1272
1273 300
1274 60
1275
1276
1277
1278 last-connected
1279 3
1280
1281
1282
1283
1285 3.3. YANG Module
1287 This YANG module has normative references to [RFC6991], [RFC7407],
1288 [RFC8040], [RFC8071], [I-D.kwatsen-netconf-tcp-client-server],
1289 [I-D.ietf-netconf-tls-client-server], and
1290 [I-D.kwatsen-netconf-http-client-server].
1292 file "ietf-restconf-server@2019-03-09.yang"
1293 module ietf-restconf-server {
1294 yang-version 1.1;
1295 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server";
1296 prefix rcs;
1298 import ietf-yang-types {
1299 prefix yang;
1300 reference
1301 "RFC 6991: Common YANG Data Types";
1302 }
1304 import ietf-x509-cert-to-name {
1305 prefix x509c2n;
1306 reference
1307 "RFC 7407: A YANG Data Model for SNMP Configuration";
1308 }
1310 import ietf-tcp-client {
1311 prefix tcpc;
1312 reference
1313 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
1314 }
1316 import ietf-tcp-server {
1317 prefix tcps;
1318 reference
1319 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
1320 }
1322 import ietf-tls-server {
1323 prefix tlss;
1324 reference
1325 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers";
1326 }
1328 import ietf-http-server {
1329 prefix https;
1330 reference
1331 "RFC CCCC: YANG Groupings for HTTP Clients and HTTP Servers";
1332 }
1334 organization
1335 "IETF NETCONF (Network Configuration) Working Group";
1337 contact
1338 "WG Web:
1339 WG List:
1340 Author: Kent Watsen
1341 Author: Gary Wu
1342 Author: Juergen Schoenwaelder
1343 ";
1345 description
1346 "This module contains a collection of YANG definitions for
1347 configuring RESTCONF servers.
1349 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
1350 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
1351 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
1352 are to be interpreted as described in BCP 14 [RFC2119]
1353 [RFC8174] when, and only when, they appear in all
1354 capitals, as shown here.
1356 Copyright (c) 2019 IETF Trust and the persons identified as
1357 authors of the code. All rights reserved.
1359 Redistribution and use in source and binary forms, with or
1360 without modification, is permitted pursuant to, and subject
1361 to the license terms contained in, the Simplified BSD
1362 License set forth in Section 4.c of the IETF Trust's
1363 Legal Provisions Relating to IETF Documents
1364 (http://trustee.ietf.org/license-info).
1366 This version of this YANG module is part of RFC XXXX; see
1367 the RFC itself for full legal notices.";
1369 revision 2019-03-09 {
1370 description
1371 "Initial version";
1372 reference
1373 "RFC XXXX: RESTCONF Client and Server Models";
1374 }
1376 // Features
1378 feature listen {
1379 description
1380 "The 'listen' feature indicates that the RESTCONF server
1381 supports opening a port to accept RESTCONF client connections
1382 using at least one transport (e.g., HTTPS, etc.).";
1383 }
1385 feature https-listen {
1386 if-feature "listen";
1387 description
1388 "The 'https-listen' feature indicates that the RESTCONF server
1389 supports opening a port to listen for incoming RESTCONF
1390 client connections. This feature exists as HTTPS might not
1391 be a mandatory to implement transport in the future.";
1392 reference
1393 "RFC 8040: RESTCONF Protocol";
1394 }
1396 feature call-home {
1397 description
1398 "The 'call-home' feature indicates that the RESTCONF
1399 server supports initiating RESTCONF call home connections
1400 to RESTCONF clients using at least one transport (e.g.,
1401 HTTPS, etc.).";
1402 reference
1403 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
1404 }
1406 feature https-call-home {
1407 if-feature "call-home";
1408 description
1409 "The 'https-call-home' feature indicates that the RESTCONF
1410 server supports initiating connections to RESTCONF clients.
1411 This feature exists as not all RESTCONF servers may
1412 support RESTCONF call home.";
1413 reference
1414 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
1415 }
1417 // Groupings
1419 grouping restconf-server-grouping {
1420 description
1421 "Top-level grouping for RESTCONF server configuration.";
1422 container listen {
1423 if-feature "listen";
1424 presence "Enables server to listen for TCP connections";
1425 description "Configures listen behavior";
1426 list endpoint {
1427 key "name";
1428 min-elements 1;
1429 description
1430 "List of endpoints to listen for RESTCONF connections.";
1431 leaf name {
1432 type string;
1433 description
1434 "An arbitrary name for the RESTCONF listen endpoint.";
1435 }
1436 choice transport {
1437 mandatory true;
1438 description
1439 "Selects between available transports. This is a
1440 'choice' statement so as to support additional
1441 transport options to be augmented in.";
1442 case https {
1443 if-feature "https-listen";
1444 container https {
1445 description
1446 "HTTPS-specific listening configuration for inbound
1447 connections.";
1448 uses tcps:tcp-server-grouping {
1449 refine "local-port" {
1450 default "443";
1451 description
1452 "The RESTCONF server will listen on the IANA-
1453 assigned well-known port value for 'https'
1454 (443) if no value is specified.";
1455 }
1456 }
1457 uses tlss:tls-server-grouping {
1458 refine "tls-client-auth" {
1459 must 'pinned-ca-certs or pinned-client-certs';
1460 description
1461 "RESTCONF servers MUST be able to validate
1462 clients.";
1463 }
1464 augment "tls-client-auth" {
1465 description
1466 "Augments in the cert-to-name structure,
1467 so the RESTCONF server can map TLS-layer
1468 client certificates to RESTCONF usernames.";
1469 container cert-maps {
1470 uses x509c2n:cert-to-name;
1471 description
1472 "The cert-maps container is used by a TLS-
1473 based RESTCONF server to map the RESTCONF
1474 client's presented X.509 certificate to
1475 a RESTCONF username. If no matching and
1476 valid cert-to-name list entry can be found,
1477 then the RESTCONF server MUST close the
1478 connection, and MUST NOT accept RESTCONF
1479 messages over it.";
1480 reference
1481 "RFC 7407: A YANG Data Model for SNMP
1482 Configuration.";
1483 }
1484 }
1485 }
1486 uses https:http-server-grouping;
1488 } // https container
1489 } // tls case
1490 } // transport
1491 } // endpoint
1492 } // listen
1494 container call-home {
1495 if-feature "call-home";
1496 presence "Enables server to initiate TCP connections";
1497 description "Configures call-home behavior";
1498 list restconf-client {
1499 key "name";
1500 min-elements 1;
1501 description
1502 "List of RESTCONF clients the RESTCONF server is to
1503 initiate call-home connections to in parallel.";
1504 leaf name {
1505 type string;
1506 description
1507 "An arbitrary name for the remote RESTCONF client.";
1508 }
1509 container endpoints {
1510 description
1511 "Container for the list of endpoints.";
1512 list endpoint {
1513 key "name";
1514 min-elements 1;
1515 ordered-by user;
1516 description
1517 "User-ordered list of endpoints for this RESTCONF
1518 client. Defining more than one enables high-
1519 availability.";
1520 leaf name {
1521 type string;
1522 description
1523 "An arbitrary name for this endpoint.";
1524 }
1525 choice transport {
1526 mandatory true;
1527 description
1528 "Selects between available transports. This is a
1529 'choice' statement so as to support additional
1530 transport options to be augmented in.";
1531 case https {
1532 if-feature "https-call-home";
1533 container https {
1534 description
1535 "Specifies HTTPS-specific call-home transport
1536 configuration.";
1537 uses tcpc:tcp-client-grouping {
1538 refine "remote-port" {
1539 default "4336";
1540 description
1541 "The RESTCONF server will attempt to connect
1542 to the IANA-assigned well-known port for
1543 'restconf-ch-tls' (4336) if no value is
1544 specified.";
1545 }
1546 }
1547 uses tlss:tls-server-grouping {
1548 refine "tls-client-auth" {
1549 must 'pinned-ca-certs or pinned-client-certs';
1550 description
1551 "RESTCONF servers MUST be able to validate
1552 clients.";
1553 }
1554 augment "tls-client-auth" {
1555 description
1556 "Augments in the cert-to-name structure,
1557 so the RESTCONF server can map TLS-layer
1558 client certificates to RESTCONF usernames.";
1559 container cert-maps {
1560 uses x509c2n:cert-to-name;
1561 description
1562 "The cert-maps container is used by a
1563 TLS-based RESTCONF server to map the
1564 RESTCONF client's presented X.509
1565 certificate to a RESTCONF username. If
1566 no matching and valid cert-to-name list
1567 entry can be found, then the RESTCONF
1568 server MUST close the connection, and
1569 MUST NOT accept RESTCONF messages over
1570 it.";
1571 reference
1572 "RFC 7407: A YANG Data Model for SNMP
1573 Configuration.";
1574 }
1575 }
1576 }
1577 uses https:http-server-grouping;
1578 }
1579 }
1580 } // transport
1581 } // endpoint
1582 } // endpoints
1583 container connection-type {
1584 description
1585 "Indicates the RESTCONF server's preference for how the
1586 RESTCONF connection is maintained.";
1587 choice connection-type {
1588 mandatory true;
1589 description
1590 "Selects between available connection types.";
1591 case persistent-connection {
1592 container persistent {
1593 presence "Indicates that a persistent connection is
1594 to be maintained.";
1595 description
1596 "Maintain a persistent connection to the RESTCONF
1597 client. If the connection goes down, immediately
1598 start trying to reconnect to it, using the
1599 reconnection strategy.
1601 This connection type minimizes any RESTCONF
1602 client to RESTCONF server data-transfer delay,
1603 albeit at the expense of holding resources
1604 longer.";
1605 }
1606 }
1607 case periodic-connection {
1608 container periodic {
1609 presence "Indicates that a periodic connection is
1610 to be maintained.";
1611 description
1612 "Periodically connect to the RESTCONF client. The
1613 RESTCONF client should close the underlying TCP
1614 connection upon completing planned activities.
1616 This connection type increases resource
1617 utilization, albeit with increased delay in
1618 RESTCONF client to RESTCONF client interactions.";
1619 leaf period {
1620 type uint16;
1621 units "minutes";
1622 default "60";
1623 description
1624 "Duration of time between periodic connections.";
1625 }
1626 leaf anchor-time {
1627 type yang:date-and-time {
1628 // constrained to minute-level granularity
1629 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}'
1630 + '(Z|[\+\-]\d{2}:\d{2})';
1631 }
1632 description
1633 "Designates a timestamp before or after which a
1634 series of periodic connections are determined.
1635 The periodic connections occur at a whole
1636 multiple interval from the anchor time. For
1637 example, for an anchor time is 15 minutes past
1638 midnight and a period interval of 24 hours, then
1639 a periodic connection will occur 15 minutes past
1640 midnight everyday.";
1641 }
1642 leaf idle-timeout {
1643 type uint16;
1644 units "seconds";
1645 default 120; // two minutes
1646 description
1647 "Specifies the maximum number of seconds that
1648 the underlying TCP session may remain idle.
1649 A TCP session will be dropped if it is idle
1650 for an interval longer than this number of
1651 seconds. If set to zero, then the server
1652 will never drop a session because it is idle.";
1653 }
1654 }
1655 }
1656 }
1657 }
1658 container reconnect-strategy {
1659 description
1660 "The reconnection strategy directs how a RESTCONF server
1661 reconnects to a RESTCONF client after discovering its
1662 connection to the client has dropped, even if due to a
1663 reboot. The RESTCONF server starts with the specified
1664 endpoint and tries to connect to it max-attempts times
1665 before trying the next endpoint in the list (round
1666 robin).";
1667 leaf start-with {
1668 type enumeration {
1669 enum first-listed {
1670 description
1671 "Indicates that reconnections should start with
1672 the first endpoint listed.";
1673 }
1674 enum last-connected {
1675 description
1676 "Indicates that reconnections should start with
1677 the endpoint last connected to. If no previous
1678 connection has ever been established, then the
1679 first endpoint configured is used. RESTCONF
1680 servers SHOULD be able to remember the last
1681 endpoint connected to across reboots.";
1682 }
1683 enum random-selection {
1684 description
1685 "Indicates that reconnections should start with
1686 a random endpoint.";
1687 }
1688 }
1689 default "first-listed";
1690 description
1691 "Specifies which of the RESTCONF client's endpoints
1692 the RESTCONF server should start with when trying
1693 to connect to the RESTCONF client.";
1694 }
1695 leaf max-attempts {
1696 type uint8 {
1697 range "1..max";
1698 }
1699 default "3";
1700 description
1701 "Specifies the number times the RESTCONF server tries
1702 to connect to a specific endpoint before moving on to
1703 the next endpoint in the list (round robin).";
1704 }
1705 }
1706 } // restconf-client
1707 } // call-home
1708 } // restconf-server-grouping
1710 // Protocol accessible node, for servers that implement this
1711 // module.
1713 container restconf-server {
1714 uses restconf-server-grouping;
1715 description
1716 "Top-level container for RESTCONF server configuration.";
1717 }
1718 }
1719
1721 4. Security Considerations
1723 The YANG module defined in this document uses a grouping defined in
1724 [I-D.ietf-netconf-tls-client-server]. Please see the Security
1725 Considerations section in that document for concerns related that
1726 grouping.
1728 The YANG module defined in this document is designed to be accessed
1729 via YANG based management protocols, such as NETCONF [RFC6241] and
1730 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
1731 implement secure transport layers (e.g., SSH, TLS) with mutual
1732 authentication.
1734 The NETCONF access control model (NACM) [RFC8341] provides the means
1735 to restrict access for particular users to a pre-configured subset of
1736 all available protocol operations and content.
1738 There are a number of data nodes defined in this YANG module that are
1739 writable/creatable/deletable (i.e., config true, which is the
1740 default). These data nodes may be considered sensitive or vulnerable
1741 in some network environments. Write operations (e.g., edit-config)
1742 to these data nodes without proper protection can have a negative
1743 effect on network operations. These are the subtrees and data nodes
1744 and their sensitivity/vulnerability:
1746 /: The entire data trees defined by the modules defined in this
1747 draft are sensitive to write operations. For instance, the
1748 addition or removal of references to keys, certificates,
1749 trusted anchors, etc., can dramatically alter the implemented
1750 security policy. However, no NACM annotations are applied as
1751 the data SHOULD be editable by users other than a designated
1752 'recovery session'.
1754 Some of the readable data nodes in this YANG module may be considered
1755 sensitive or vulnerable in some network environments. It is thus
1756 important to control read access (e.g., via get, get-config, or
1757 notification) to these data nodes. These are the subtrees and data
1758 nodes and their sensitivity/vulnerability:
1760 NONE
1762 Some of the RPC operations in this YANG module may be considered
1763 sensitive or vulnerable in some network environments. It is thus
1764 important to control access to these operations. These are the
1765 operations and their sensitivity/vulnerability:
1767 NONE
1769 5. IANA Considerations
1771 5.1. The IETF XML Registry
1773 This document registers two URIs in the "ns" subregistry of the IETF
1774 XML Registry [RFC3688]. Following the format in [RFC3688], the
1775 following registrations are requested:
1777 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client
1778 Registrant Contact: The NETCONF WG of the IETF.
1779 XML: N/A, the requested URI is an XML namespace.
1781 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server
1782 Registrant Contact: The NETCONF WG of the IETF.
1783 XML: N/A, the requested URI is an XML namespace.
1785 5.2. The YANG Module Names Registry
1787 This document registers two YANG modules in the YANG Module Names
1788 registry [RFC6020]. Following the format in [RFC6020], the the
1789 following registrations are requested:
1791 name: ietf-restconf-client
1792 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client
1793 prefix: ncc
1794 reference: RFC XXXX
1796 name: ietf-restconf-server
1797 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server
1798 prefix: ncs
1799 reference: RFC XXXX
1801 6. References
1803 6.1. Normative References
1805 [I-D.ietf-netconf-keystore]
1806 Watsen, K., "YANG Data Model for a Centralized Keystore
1807 Mechanism", draft-ietf-netconf-keystore-08 (work in
1808 progress), March 2019.
1810 [I-D.ietf-netconf-tls-client-server]
1811 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for TLS
1812 Clients and TLS Servers", draft-ietf-netconf-tls-client-
1813 server-08 (work in progress), October 2018.
1815 [I-D.kwatsen-netconf-http-client-server]
1816 Watsen, K., "YANG Groupings for HTTP Clients and HTTP
1817 Servers", draft-kwatsen-netconf-http-client-server-00
1818 (work in progress), March 2019.
1820 [I-D.kwatsen-netconf-tcp-client-server]
1821 Watsen, K., "YANG Groupings for TCP Clients and TCP
1822 Servers", draft-kwatsen-netconf-tcp-client-server-00 (work
1823 in progress), March 2019.
1825 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1826 Requirement Levels", BCP 14, RFC 2119,
1827 DOI 10.17487/RFC2119, March 1997,
1828 .
1830 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
1831 the Network Configuration Protocol (NETCONF)", RFC 6020,
1832 DOI 10.17487/RFC6020, October 2010,
1833 .
1835 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
1836 RFC 6991, DOI 10.17487/RFC6991, July 2013,
1837 .
1839 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
1840 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
1841 December 2014, .
1843 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
1844 RFC 7950, DOI 10.17487/RFC7950, August 2016,
1845 .
1847 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
1848 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
1849 .
1851 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
1852 RFC 8071, DOI 10.17487/RFC8071, February 2017,
1853 .
1855 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
1856 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
1857 May 2017, .
1859 6.2. Informative References
1861 [I-D.ietf-netconf-netconf-client-server]
1862 Watsen, K., "NETCONF Client and Server Models", draft-
1863 ietf-netconf-netconf-client-server-08 (work in progress),
1864 October 2018.
1866 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
1867 DOI 10.17487/RFC3688, January 2004,
1868 .
1870 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
1871 and A. Bierman, Ed., "Network Configuration Protocol
1872 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
1873 .
1875 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
1876 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
1877 .
1879 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
1880 Access Control Model", STD 91, RFC 8341,
1881 DOI 10.17487/RFC8341, March 2018,
1882 .
1884 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
1885 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
1886 .
1888 Appendix A. Change Log
1890 A.1. 00 to 01
1892 o Renamed "keychain" to "keystore".
1894 A.2. 01 to 02
1896 o Filled in previously missing 'ietf-restconf-client' module.
1898 o Updated the ietf-restconf-server module to accomodate new grouping
1899 'ietf-tls-server-grouping'.
1901 A.3. 02 to 03
1903 o Refined use of tls-client-grouping to add a must statement
1904 indicating that the TLS client must specify a client-certificate.
1906 o Changed restconf-client??? to be a grouping (not a container).
1908 A.4. 03 to 04
1910 o Added RFC 8174 to Requirements Language Section.
1912 o Replaced refine statement in ietf-restconf-client to add a
1913 mandatory true.
1915 o Added refine statement in ietf-restconf-server to add a must
1916 statement.
1918 o Now there are containers and groupings, for both the client and
1919 server models.
1921 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams
1923 o Updated examples to inline key and certificates (no longer a
1924 leafref to keystore)
1926 A.5. 04 to 05
1928 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams
1930 o Updated examples to inline key and certificates (no longer a
1931 leafref to keystore)
1933 A.6. 05 to 06
1935 o Fixed change log missing section issue.
1937 o Updated examples to match latest updates to the crypto-types,
1938 trust-anchors, and keystore drafts.
1940 o Reduced line length of the YANG modules to fit within 69 columns.
1942 A.7. 06 to 07
1944 o removed "idle-timeout" from "persistent" connection config.
1946 o Added "random-selection" for reconnection-strategy's "starts-with"
1947 enum.
1949 o Replaced "connection-type" choice default (persistent) with
1950 "mandatory true".
1952 o Reduced the periodic-connection's "idle-timeout" from 5 to 2
1953 minutes.
1955 o Replaced reconnect-timeout with period/anchor-time combo.
1957 A.8. 07 to 08
1959 o Modified examples to be compatible with new crypto-types algs
1961 A.9. 08 to 09
1963 o Corrected use of "mandatory true" for "address" leafs.
1965 o Updated examples to reflect update to groupings defined in the
1966 keystore draft.
1968 o Updated to use groupings defined in new TCP and HTTP drafts.
1970 o Updated copyright date, boilerplate template, affiliation, and
1971 folding algorithm.
1973 A.10. 09 to 10
1975 o Reformatted YANG modules.
1977 Acknowledgements
1979 The authors would like to thank for following for lively discussions
1980 on list and in the halls (ordered by last name): Andy Bierman, Martin
1981 Bjorklund, Benoit Claise, Ramkumar Dhanapal, Mehmet Ersue, Balazs
1982 Kovacs, David Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci,
1983 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert
1984 Wijnen.
1986 Author's Address
1988 Kent Watsen
1989 Watsen Networks
1991 EMail: kent+ietf@watsen.net