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