idnits 2.17.1 draft-ietf-netconf-nmda-restconf-01.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 contain references ([I-D.ietf-netmod-revised-datastores], [RFC8040]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC8040, but the abstract doesn't seem to directly say this. It does mention RFC8040 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 226 has weird spacing: '...-origin urn:...' -- The document date (October 30, 2017) is 2363 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 (-10) exists of draft-ietf-netmod-revised-datastores-05 Summary: 1 error (**), 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: May 3, 2018 P. Shafer 7 K. Watsen 8 Juniper Networks 9 R. Wilton 10 Cisco Systems 11 October 30, 2017 13 RESTCONF Update to Support the NMDA 14 draft-ietf-netconf-nmda-restconf-01 16 Abstract 18 This document updates RESTCONF [RFC8040] in order to support the 19 Network Management Datastore Architecture (NMDA) defined in 20 [I-D.ietf-netmod-revised-datastores]. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 3, 2018. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Summary of Updates to RFC 8040 . . . . . . . . . . . . . . . 3 59 3. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 4. The {+restconf}/ds/ Resources . . . . . . . . . . 3 61 5. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 4 62 5.1. The "with-origin" query parameter . . . . . . . . . . . . 4 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 65 8. Normative References . . . . . . . . . . . . . . . . . . . . 5 66 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 6 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 69 1. Introduction 71 This document updates RESTCONF [RFC8040] in order to support the 72 Network Management Datastore Architecture (NMDA) defined in 73 [I-D.ietf-netmod-revised-datastores]. 75 The solution presented in this document is backwards compatible with 76 [RFC8040]. This is achieved by it only adding new top-level 77 resources, and thereby leaving the semantics of all existing 78 resources alone. 80 1.1. Terminology 82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 84 "OPTIONAL" in this document are to be interpreted as described in BCP 85 14 [RFC2119] [RFC8174] when, and only when, they appear in all 86 capitals, as shown here. 88 The following terms are defined in 89 [I-D.ietf-netmod-revised-datastores] and are not redefined here: 91 o operational state datastore 93 o running configuration datastore 95 o intended configuration datastore 97 2. Summary of Updates to RFC 8040 99 This document updates [RFC8040] in the following ways: 101 o Adds new top-level resource "/ds". 103 o Adds new query parameter "with-origin". 105 o Section 3.5.4, Paragraph 3 in [RFC8040] doesn't apply when 106 interacting with any resource under {+restconf}/ds. 108 o Updates section 10 in [RFC8040] by requiring servers that support 109 NMDA to implement "ietf-yang-library" as defined in 110 [I-D.nmdsdt-netconf-rfc7895bis]. 112 3. Conformance 114 RFC Ed.: Update 201X-XX-XX below with correct date. 116 An NMDA-compliant RESTCONF server MUST support the operational state 117 datastore. Such a server identifies that it supports 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, as specified in 121 [I-D.nmdsdt-netconf-rfc7895bis]. 123 A RESTCONF client can test if a server supports the NMDA by using 124 either the HEAD or GET methods on {+restconf}/ds/ietf- 125 datastores:operational. 127 4. The {+restconf}/ds/ Resources 129 This document defines a set of new resources representing datastores 130 as defined in [I-D.ietf-netmod-revised-datastores]. These resources 131 are available using the resource path template: 133 {+restconf}/ds/ 135 Where is encoded as an "identity" according to the JSON 136 encoding rules for identities, defined in Section 4 of [RFC7951]. 137 Such an identity MUST be derived from the "datastore" identity in 138 "ietf-datastores" [I-D.ietf-netmod-revised-datastores]. 140 Specifically: 142 o The resource {+restconf}/ds/ietf-datastores:operational refers to 143 the operational state datastore. 145 o The resource {+restconf}/ds/ietf-datastores:running refers to the 146 running configuration datastore. 148 o The resource {+restconf}/ds/ietf-datastores:intended refers to the 149 intended configuration datastore. 151 An NMDA-compliant server MUST implement {+restconf}/ds/ietf- 152 datastores:operational. Other datastore resources are optional to 153 implement. 155 If a server implements the example datastore "ds-ephemeral" in the 156 module "example-ds-ephemeral", it would implement the resource 157 {+restconf}/ds/example-ds-ephemeral:ds-ephemeral. 159 5. Protocol Operations 161 All existing protocol operations defined in [RFC8040] for the 162 {+restconf}/data resource are available for all of the new datastore 163 resources with the following exceptions: 165 o Dynamic datastores are excluded, as each dynamic datastore 166 definition needs to be reviewed for what protocol operations it 167 supports. 169 o Some datastores are read-only by nature (e.g., ), and 170 hence any attempt to modify these datastores will fail. 172 o The "with-defaults" query parameter ([RFC8040], Section 4.8.9) 173 does not apply when interacting with {+restconf}/ds/ietf- 174 datastores:operational. This means that all values are always 175 returned from the operational state datastore, even if a node 176 happens to have a default statement in the YANG module, and this 177 default value is being used by the server. If the "with-defaults" 178 query parameter is present in a request to this resource, the 179 server MUST return a response with a "400 Bad Request" status- 180 line. The error-tag value "invalid-value" is used in this case. 182 o [RFC8040], section 3.5.4, paragraph 3 does not apply when 183 interacting with any resource under {+restconf}/ds. 185 5.1. The "with-origin" query parameter 187 The GET operation adds a new query parameter named "with-origin", 188 which if present, requests that the server includes "origin" metadata 189 anotations in its response, as detailed in the NMDA. This parameter 190 is only valid when querying {+restconf}/ds/ietf- 191 datastores:operational or any datastores with identities derived from 192 the "operational" identity. Otherwise, if an invalid datastore is 193 specified then the server MUST return a response witha a "400 Bad 194 Request" status-line, using an error-tag value of "invalid-value". 195 "origin" metadata annotations are not included unless a client 196 explicitly requests them. 198 Data from can come from multiple sources. The server 199 should return the most accurate value for the "origin" metadata 200 annotation as possible, indicating the source of the operational 201 value, as specified in section 5.3.4 of the NMDA. 203 When encoding the origin metadata annotation for a hierarchy of 204 returned nodes, the annotation may be omitted for a child node when 205 the value matches that of the parent node (as described in ietf- 206 origin@2017-08-17). [RFC Editor, please check published revision 207 date.] 209 The "with-origin" query parameter is optional to support. It is 210 identified with the URI: 212 urn:ietf:params:restconf:capability:with-origin:1.0 214 6. Security Considerations 216 TBD 218 7. IANA Considerations 220 This document defines one capability in the "RESTCONF Capability 221 URNs" registry defined in [RFC8040]: 223 Index Capability Identifier 224 ------------------------------------------------------------------ 226 :with-origin urn:ietf:params:restconf:capability:with-origin:1.0 228 8. Normative References 230 [I-D.ietf-netmod-revised-datastores] 231 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 232 and R. Wilton, "Network Management Datastore 233 Architecture", draft-ietf-netmod-revised-datastores-05 234 (work in progress), October 2017. 236 [I-D.nmdsdt-netconf-rfc7895bis] 237 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Library", 238 draft-nmdsdt-netconf-rfc7895bis-01 (work in progress), 239 July 2017. 241 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 242 Requirement Levels", BCP 14, RFC 2119, 243 DOI 10.17487/RFC2119, March 1997, . 246 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 247 RFC 7951, DOI 10.17487/RFC7951, August 2016, 248 . 250 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 251 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 252 . 254 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 255 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 256 May 2017, . 258 Appendix A. Example 260 TBD 262 Authors' Addresses 264 Martin Bjorklund 265 Tail-f Systems 267 Email: mbj@tail-f.com 269 Juergen Schoenwaelder 270 Jacobs University 272 Email: j.schoenwaelder@jacobs-university.de 274 Phil Shafer 275 Juniper Networks 277 Email: phil@juniper.net 279 Kent Watsen 280 Juniper Networks 282 Email: kwatsen@juniper.net 283 Robert Wilton 284 Cisco Systems 286 Email: rwilton@cisco.com