idnits 2.17.1 draft-ietf-netconf-nmda-restconf-05.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 : ---------------------------------------------------------------------------- -- The abstract seems to indicate that this document updates RFC8342, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 9, 2018) is 2024 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 (-07) exists of draft-ietf-netconf-rfc7895bis-06 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Bjorklund 3 Internet-Draft Tail-f Systems 4 Updates: 8040 (if approved) J. Schoenwaelder 5 Intended status: Standards Track Jacobs University 6 Expires: April 12, 2019 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 October 9, 2018 13 RESTCONF Extensions to Support the Network Management Datastore 14 Architecture 15 draft-ietf-netconf-nmda-restconf-05 17 Abstract 19 This document extends the RESTCONF protocol defined in RFC 8040 in 20 order to support the Network Management Datastore Architecture 21 defined in RFC 8342. 23 This document updates RFC 8040 by introducing new datastore 24 resources, adding a new query parameter, and requiring the usage of 25 I-D.ietf-netconf-rfc7895bis by RESTCONF servers implementing the 26 Network Management Datastore Architecture. 28 RFC Ed.: Please replace "I-D.ietf-netconf-rfc7895bis" above with its 29 final RFC assignment and remove this note. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on April 12, 2019. 48 Copyright Notice 50 Copyright (c) 2018 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Datastore and YANG Library Requirements . . . . . . . . . . . 3 68 3. RESTCONF Extensions . . . . . . . . . . . . . . . . . . . . . 3 69 3.1. New Datastore Resources . . . . . . . . . . . . . . . . . 3 70 3.2. Protocol Operations . . . . . . . . . . . . . . . . . . . 4 71 3.2.1. With-defaults query parameter on the operational 72 state datastore . . . . . . . . . . . . . . . . . . . 5 73 3.2.2. New "with-origin" Query Parameter . . . . . . . . . . 5 74 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 76 6. Normative References . . . . . . . . . . . . . . . . . . . . 7 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 79 1. Introduction 81 This document extends the RESTCONF protocol defined in [RFC8040] in 82 order to support the Network Management Datastore Architecture (NMDA) 83 defined in [RFC8342]. 85 This document updates [RFC8040] in order to enable RESTCONF clients 86 to discover which datastores are supported by the RESTCONF server, 87 determine which modules are supported in each datastore, and to 88 interact with all the datastores supported by the NMDA. 89 Specifically, the update introduces new datastore resources, adds a 90 new query parameter, and requires the usage of 91 [I-D.ietf-netconf-rfc7895bis] by RESTCONF servers implementing the 92 NMDA. 94 The solution presented in this document is backwards compatible with 95 [RFC8040]. This is achieved by only adding new resources and leaving 96 the semantics of the existing resources unchanged. 98 1.1. Terminology 100 This document uses the terminology defined by the NMDA [RFC8342]. 102 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14, [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 2. Datastore and YANG Library Requirements 110 RFC Ed.: Please update 201X-XX-XX below with correct date and remove 111 this note. 113 An NMDA-compliant RESTCONF server MUST support the operational state 114 datastore and it MUST implement at least revision 201X-XX-XX of the 115 "ietf-yang-library" module defined in [I-D.ietf-netconf-rfc7895bis]. 117 Such a server identifies that it supports the NMDA both by 118 implementing the {+restconf}/ds/ietf-datastores:operational resource, 119 and by implementing at least revision 201X-XX-XX of the 120 "ietf-yang-library" module. 122 A RESTCONF client can test if a server supports the NMDA by using 123 either the HEAD or GET methods on {+restconf}/ds/ietf- 124 datastores:operational. 126 A RESTCONF client can discover which datastores and YANG modules the 127 server supports by reading the YANG library information from the 128 operational state datastore. 130 3. RESTCONF Extensions 132 This section describes the RESTCONF extensions needed to support the 133 NMDA. 135 3.1. New Datastore Resources 137 This document defines a set of new resources representing datastores 138 as defined in [RFC8342]. These resources are available using the 139 following resource path template: 141 {+restconf}/ds/ 143 The path component is encoded as an "identityref" 144 according to the JSON encoding rules for identities, defined in 145 Section 6.8 of [RFC7951]. The namespace-qualified form MUST be used. 146 Such an identity MUST be derived from the "datastore" identity 147 defined in the "ietf-datastores" YANG module [RFC8342]. 149 Specifically: 151 o The resource {+restconf}/ds/ietf-datastores:operational refers to 152 the operational state datastore. 154 o The resource {+restconf}/ds/ietf-datastores:running refers to the 155 running configuration datastore. 157 o The resource {+restconf}/ds/ietf-datastores:intended refers to the 158 intended configuration datastore. 160 An NMDA-compliant server MUST implement {+restconf}/ds/ietf- 161 datastores:operational. Other datastore resources MAY be 162 implemented. 164 YANG actions can only be invoked in {+restconf}/ds/ietf- 165 datastores:operational. 167 If a server implements other datastores, such as the example 168 datastore "ds-ephemeral" in the module "example-ds-ephemeral", the 169 server would implement the resource {+restconf}/ds/example- ds- 170 ephemeral:ds-ephemeral. 172 3.2. Protocol Operations 174 The protocol operations available for the new datastore resources 175 (Section 3.1) are the same as the protocol operations defined in 176 [RFC8040] for the {+restconf}/data resource with the following 177 exceptions: 179 o Dynamic configuration datastores are excluded, as each dynamic 180 configuration datastore definition needs to be reviewed for what 181 protocol operations it supports. 183 o Some datastores are read-only by nature (e.g., ), and 184 hence any attempt to modify these datastores will fail. A server 185 MUST return a response with a "405 Method Not Allowed" status-line 186 and error-tag value "operation-not-supported". 188 o The semantics of the "with-defaults" query parameter ([RFC8040], 189 Section 4.8.9) differs when interacting with the operational state 190 datastore. The semantics are described below, in Section 3.2.1. 192 o [RFC8040], Section 3.5.4, paragraph 3 does not apply when 193 interacting with any resource under {+restconf}/ds. 195 3.2.1. With-defaults query parameter on the operational state datastore 197 The "with-defaults" query parameter ([RFC8040], Section 4.8.9) is 198 OPTIONAL to support when interacting with {+restconf}/ds/ietf- 199 datastores:operational. The associated capability to indicate a 200 server's support is identified with the URI: 202 urn:ietf:params:restconf:capability:with-operational-defaults:1.0 204 For servers that support it, the behavior of the "with-defaults" 205 query parameter on the operational state datastore is defined as 206 follows: 208 o If no "with-defaults" query parameter is specified, or if it is 209 set to "explicit", "report-all", or "report-all-tagged", then the 210 "in use" values, as defined in [RFC8342] section 5.3, are returned 211 from the operational state datastore, even if a node happens to 212 have a default statement in the YANG module and this default value 213 is being used by the server. If the "with-defaults" parameter is 214 set to "report-all-tagged", any values that match the schema 215 default are tagged with additional metadata, as described in 216 [RFC8040], Section 4.8.9. 218 o If the "with-defaults" query parameter is set to "trim", all "in 219 use" values are returned, except that the output is filtered to 220 exclude any values that match the default defined in the YANG 221 schema. 223 Servers are not required to support all values in the "with-defaults" 224 query parameter on the operational state datastore. If a request is 225 made using a value that is not supported, then the error handling 226 behavior is as described in ([RFC8040], Section 4.8.9). 228 3.2.2. New "with-origin" Query Parameter 230 A new query parameter named "with-origin" is added to the GET 231 operation. If present, it requests that the server includes "origin" 232 metadata annotations in its response, as detailed in the NMDA. This 233 parameter is only valid when querying {+restconf}/ds/ietf- 234 datastores:operational or any datastores with identities derived from 235 the "operational" identity. Otherwise, if an invalid datastore is 236 specified then the server MUST return a response with a "400 Bad 237 Request" status-line, using an error-tag value of "invalid-value". 238 "origin" metadata annotations are not included unless a client 239 explicitly requests them. 241 Data in the operational state datatstore can come from multiple 242 sources. The server should return the most accurate value for the 243 "origin" metadata annotation as possible, indicating the source of 244 the operational value, as specified in Section 5.3.4 of [RFC8342]. 246 When encoding the origin metadata annotation for a hierarchy of 247 returned nodes, the annotation can be omitted for a child node when 248 the value matches that of the parent node, as described in 249 "ietf-origin" YANG module [RFC8342]. 251 The "with-origin" query parameter is OPTIONAL to support. It is 252 identified with the URI: 254 urn:ietf:params:restconf:capability:with-origin:1.0 256 4. IANA Considerations 258 This document defines two capability identifier URNs in the "RESTCONF 259 Capability URNs" registry defined in [RFC8040]: 261 Index 262 Capability Identifier 263 --------------------- 265 :with-origin 266 urn:ietf:params:restconf:capability:with-origin:1.0 268 :with-operational-defaults 269 urn:ietf:params:restconf:capability:with-operational-defaults:1.0 271 5. Security Considerations 273 This document extends the RESTCONF protocol by introducing new 274 datastore resources. The lowest RESTCONF layer is HTTPS, and the 275 mandatory-to-implement secure transport is TLS [RFC8446]. The 276 RESTCONF protocol uses the network configuration access control model 277 [RFC8341], which provides the means to restrict access for particular 278 RESTCONF users to a preconfigured subset of all available RESTCONF 279 protocol operations and content. 281 The security constraints for the base RESTCONF protocol (see 282 Section 12 of [RFC8040]) apply to the new RESTCONF datastore 283 resources defined in this document. 285 6. Normative References 287 [I-D.ietf-netconf-rfc7895bis] 288 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 289 and R. Wilton, "YANG Library", draft-ietf-netconf- 290 rfc7895bis-06 (work in progress), April 2018. 292 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 293 Requirement Levels", BCP 14, RFC 2119, 294 DOI 10.17487/RFC2119, March 1997, . 297 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 298 RFC 7951, DOI 10.17487/RFC7951, August 2016, 299 . 301 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 302 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 303 . 305 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 306 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 307 May 2017, . 309 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 310 Access Control Model", STD 91, RFC 8341, 311 DOI 10.17487/RFC8341, March 2018, . 314 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 315 and R. Wilton, "Network Management Datastore Architecture 316 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 317 . 319 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 320 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 321 . 323 Authors' Addresses 325 Martin Bjorklund 326 Tail-f Systems 328 Email: mbj@tail-f.com 329 Juergen Schoenwaelder 330 Jacobs University 332 Email: j.schoenwaelder@jacobs-university.de 334 Phil Shafer 335 Juniper Networks 337 Email: phil@juniper.net 339 Kent Watsen 340 Juniper Networks 342 Email: kwatsen@juniper.net 344 Robert Wilton 345 Cisco Systems 347 Email: rwilton@cisco.com