idnits 2.17.1 draft-openconfig-rtgwg-gnmi-spec-00.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 document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 194: '... MUST be unique. In this cont...' RFC 2119 keyword, line 202: '...fication message MUST include the "tim...' RFC 2119 keyword, line 209: '...Timestamp values MUST be represented a...' RFC 2119 keyword, line 210: '...st 1970 00:00:00 UTC). The value MUST...' RFC 2119 keyword, line 228: '...n" - field which MAY be used to disamb...' (147 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Subscriptions are set once, and subsequently not modified by a client. If a client wishes to subscribe to additional paths from a target, it MUST do so by sending an additional "Subscribe" RPC call, specifying a new "SubscriptionList" message. In order to end an existing subscription, a client simply closes the gRPC channel that relates to that subscription. If a channel is initiated with a "SubscribeRequest" message that does not specify a "SubscriptionList" message with the "request" field, the target MUST consider this an error. If an additional "SubscribeRequest" message specifying a "SubscriptionList" is sent via an existing channel, the target MUST respond to this message with "SubscribeResponse" message indicating an error message, with a contained error message indicating an error code of "InvalidArgument (4)"; existing subscriptions on other gRPC channels MUST not be modified or terminated. -- The document date (March 13, 2017) is 2594 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? '2' on line 1601 looks like a reference -- Missing reference section? 'REFERENCE-PROTO' on line 119 looks like a reference -- Missing reference section? '3' on line 1603 looks like a reference -- Missing reference section? 'GNMI-SPEC' on line 120 looks like a reference -- Missing reference section? '4' on line 1606 looks like a reference -- Missing reference section? '5' on line 1609 looks like a reference -- Missing reference section? '6' on line 1611 looks like a reference -- Missing reference section? '7' on line 1614 looks like a reference -- Missing reference section? '8' on line 1616 looks like a reference -- Missing reference section? '9' on line 1618 looks like a reference -- Missing reference section? '10' on line 1620 looks like a reference -- Missing reference section? '11' on line 1622 looks like a reference -- Missing reference section? '12' on line 1624 looks like a reference -- Missing reference section? '13' on line 1626 looks like a reference -- Missing reference section? 'GNMI-AUTH' on line 672 looks like a reference -- Missing reference section? '15' on line 1632 looks like a reference -- Missing reference section? '1' on line 1599 looks like a reference -- Missing reference section? '14' on line 1629 looks like a reference -- Missing reference section? '16' on line 1635 looks like a reference -- Missing reference section? '17' on line 1643 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 21 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Shakir 3 Internet-Draft A. Shaikh 4 Intended status: Informational P. Borman 5 Expires: September 14, 2017 M. Hines 6 C. Lebsack 7 C. Morrow 8 Google 9 March 13, 2017 11 gRPC Network Management Interface (gNMI) 12 draft-openconfig-rtgwg-gnmi-spec-00 14 Abstract 16 This document describes the gRPC Network Management Interface (gNMI), 17 a network management protocol based on the gRPC RPC framework. gNMI 18 supports retrieval and manipuation of state from network elements 19 where the data is represented by a tree structure, and addressable by 20 paths. The gNMI service defines operations for configuration 21 management, operational state retrieval, and bulk data collection via 22 streaming telemtry. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 14, 2017. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Common Message Types and Encodings . . . . . . . . . . . . . 4 60 2.1. Reusable Notification Message Format . . . . . . . . . . 4 61 2.2. Common Data Types . . . . . . . . . . . . . . . . . . . . 5 62 2.2.1. Timestamps . . . . . . . . . . . . . . . . . . . . . 5 63 2.2.2. Paths . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.2.3. Node Values . . . . . . . . . . . . . . . . . . . . . 6 65 2.3. Encoding Data in an Update Message . . . . . . . . . . . 6 66 2.3.1. JSON and JSON_IETF . . . . . . . . . . . . . . . . . 6 67 2.3.2. Bytes . . . . . . . . . . . . . . . . . . . . . . . . 9 68 2.3.3. Protobuf . . . . . . . . . . . . . . . . . . . . . . 9 69 2.3.4. ASCII . . . . . . . . . . . . . . . . . . . . . . . . 9 70 2.4. Use of Data Schema Paths . . . . . . . . . . . . . . . . 9 71 2.4.1. Path Prefixes . . . . . . . . . . . . . . . . . . . . 9 72 2.4.2. Path Aliases . . . . . . . . . . . . . . . . . . . . 10 73 2.4.3. Interpretation of Paths Used in RPCs . . . . . . . . 11 74 2.5. Error handling . . . . . . . . . . . . . . . . . . . . . 12 75 2.6. Schema Definition Models . . . . . . . . . . . . . . . . 13 76 2.6.1. The ModelData message . . . . . . . . . . . . . . . . 13 77 3. Service Definition . . . . . . . . . . . . . . . . . . . . . 14 78 3.1. Session Security, Authentication and RPC Authorization . 14 79 3.2. Capability Discovery . . . . . . . . . . . . . . . . . . 15 80 3.2.1. The CapabilityRequest message . . . . . . . . . . . . 15 81 3.2.2. The CapabilityResponse message . . . . . . . . . . . 15 82 3.3. Retrieving Snapshots of State Information . . . . . . . . 16 83 3.3.1. The GetRequest Message . . . . . . . . . . . . . . . 16 84 3.3.2. The GetResponse message . . . . . . . . . . . . . . . 17 85 3.3.3. Considerations for using Get . . . . . . . . . . . . 18 86 3.4. Modifying State . . . . . . . . . . . . . . . . . . . . . 18 87 3.4.1. The SetRequest Message . . . . . . . . . . . . . . . 19 88 3.4.2. The SetResponse Message . . . . . . . . . . . . . . . 20 89 3.4.3. Transactions . . . . . . . . . . . . . . . . . . . . 20 90 3.4.4. Modes of Update: Replace versus Update . . . . . . . 21 91 3.4.5. Modifying Paths Identified by Attributes . . . . . . 21 92 3.4.6. Deleting Configuration . . . . . . . . . . . . . . . 22 93 3.4.7. Error Handling . . . . . . . . . . . . . . . . . . . 23 94 3.5. Subscribing to Telemetry Updates . . . . . . . . . . . . 24 95 3.5.1. Managing Subscriptions . . . . . . . . . . . . . . . 26 96 3.5.2. Sending Telemetry Updates . . . . . . . . . . . . . . 32 98 4.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 35 99 Appendix A. Appendix: Current Protobuf Message and Service 100 Specification . . . . . . . . . . . . . . . . . . . 36 101 Appendix B. Appendix: Current Outstanding Issues/Future Features 36 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 104 1. Introduction 106 This document defines a gRPC [1]-based protocol for the modification 107 and retrieval of configuration from a network element, as well as the 108 control and generation of telemetry streams from a network element to 109 a data collection system. The intention is that a single gRPC 110 service definition can cover both configuration and telemetry - 111 allowing a single implementation on the network element, as well as a 112 single NMS element to interact with the device via telemetry and 113 configuration RPCs. 115 All messages within the gRPC service definition are defined as 116 protocol buffers [2] (specifically proto3). gRPC service definitions 117 are expected to be described using the relevant features of the 118 protobuf IDL. A reference protobuf definition is maintained in 119 [REFERENCE-PROTO] [3]. The current, authoritative version of this 120 specification is available at [GNMI-SPEC] [4]. 122 The service defined within this document is assumed to carry payloads 123 that contain data instances of OpenConfig [5] YANG schemas, but can 124 be used for any data with the following characteristics: 126 1. structure can be represented by a tree structure where nodes can 127 be uniquely identified by a path consisting of node names, or 128 node names coupled with attributes; 130 2. values can be serialised into a scalar object. 132 Currently, values may be serialised to a scalar object through 133 encoding as a JSON string, a byte-array, or a serialised protobuf 134 object - although the definition of new serialisations is possible. 136 Throughout this specification the following terminology is used: 138 o _Telemetry_ - refers to streaming data relating to underlying 139 characteristics of the device - either operational state or 140 configuration. 142 o _Configuration_ - elements within the data schema which are read/ 143 write and can be manipulated by the client. 145 o _Target_ - the device within the protocol which acts as the owner 146 of the data that is being manipulated or reported on. Typically 147 this will be a network device. 149 o _Client_ - the device or system using the protocol described in 150 this document to query/modify data on the target, or act as a 151 collector for streamed data. Typically this will be a network 152 management system. 154 2. Common Message Types and Encodings 156 2.1. Reusable Notification Message Format 158 When a target wishes to communicate data relating to the state of its 159 internal database to an interested client, it does so via means of a 160 common "Notification" message. Notification messages are reused in 161 other higher-layer messages for various purposes. The exact use of 162 the Notification message is described on a per-RPC basis. 164 The fields of the Notification message are as follows: 166 o "timestamp" - The time at which the data was collected by the 167 device from the underlying source, or the time that the target 168 generated the Notification message (in the case that the data does 169 not reflect an underlying data source). This value is always 170 represented according to the definition in Section 2.2.1. 172 o "prefix" - a prefix which is applied to all path fields (encoded 173 as per Section 2.2.2) included in the "Notification" message. The 174 paths expressed within the message are formed by the concatenation 175 of "prefix + path". The "prefix" always precedes the "path" 176 elements. Further semantics of prefixes are described in 177 Section 2.4.1. 179 o "alias"- a string providing an alias for the prefix specified 180 within the notification message. The encoding of an alias, and 181 the procedure for their creation is described in Section 2.4.2"." 183 o "update" - a list of update messages that indicate changes in the 184 underlying data of the target. Both modification and creation of 185 data is expressed through the update message. 187 * An "Update" message has two subfields: 189 + "path" - a path encoded as per Section 2.2.2. 191 + "value" - a value encoded as per Section 2.2.3. 193 * The set of paths that are specified within the list of updates 194 MUST be unique. In this context, the path is defined to be the 195 fully resolved path (including the prefix). In the case that 196 there is a duplicate path specified within an update, only the 197 final update should be processed by the receiving entity. 199 o "delete" - a list of paths (encoded as per Section 2.2.2) that 200 indicate the deletion of data nodes on the target. 202 The creator of a Notification message MUST include the "timestamp" 203 field. All other fields are optional. 205 2.2. Common Data Types 207 2.2.1. Timestamps 209 Timestamp values MUST be represented as the number of nanoseconds 210 since the Unix epoch (January 1st 1970 00:00:00 UTC). The value MUST 211 be encoded as a signed 64-bit integer ("int64"). 213 2.2.2. Paths 215 Paths are represented according to gNMI Path Conventions [6], a 216 simplified form of XPATH. Rather than utilising a single string to 217 represent the path - with the "/" character separating each element 218 of the path, the path is represented by an ordered list of strings, 219 starting at the root node, and ending at the most specific path 220 element. 222 A path is represented by the "Path" message with the following 223 fields: 225 o "element" -- a set of path elements, encoded as strings (see 226 examples below). 228 o "origin" - field which MAY be used to disambiguate the path if 229 necessary. For example, the origin may be used to indicate which 230 organization defined the schema to which the path belongs. 232 Each "Path" element should correspond to a node in the data tree. 233 For example, the path "/a/b/c/d" is encoded as: 235 path: < 236 element: "a" 237 element: "b" 238 element: "c" 239 element: "d" 240 > 242 Where attributes are to be specified, these are encoded alongside the 243 node name within the path element, for example a node specified by 244 "/a/e[key=k1]/f/g" would have the path encoded as: 246 path: < 247 element: "a" 248 element: "e[key=k1]" 249 element: "f" 250 element: "g" 251 > 253 The root node ("/") is indicated by encoding a single path element 254 which is an empty string, as per the following example: 256 path: < 257 element: "" 258 > 260 Paths (defined to be the concatenation of the "Prefix" and "Path" 261 within the message) specified within a message MUST be absolute - no 262 messages with relative paths should be generated. 264 2.2.3. Node Values 266 The value of a data node is encoded as a two-field message: 268 o "bytes" - an arbitrary series of bytes which indicates the value 269 of the node referred to within the message context. 271 o "type" - a field indicating the type of data contained in the 272 bytes field. Currently defined types are: 274 2.3. Encoding Data in an Update Message 276 2.3.1. JSON and JSON_IETF 278 The "JSON" type indicates that the value included within the "bytes" 279 field of the node value message is encoded as a JSON string. This 280 format utilises the specification in RFC7159 [7]. Additional types 281 (e.g., "JSON_IETF") are utilised to indicate specific additional 282 characteristics of the encoding of the JSON data (particularly where 283 they relate to serialisation of YANG-modeled data). 285 For any JSON encoding: 287 o In the case that the data item at the specified path is a leaf 288 node (i.e., has no children) the value of that leaf is encoded 289 directly - i.e., the "bare" value is specified (i.e., a JSON 290 object is not required, and a bare JSON value is included). 292 o Where the data item referred to has child nodes, the value field 293 contains a serialised JSON entity (object or array) corresponding 294 to the referenced item. 296 Using the following example data tree: 298 root + 299 | 300 +-- a + 301 | 302 +-- b[name=b1] + 303 | 304 +-- c + 305 | 306 +-- d (string) 307 +-- e (uint32) 309 The following serialisations would be used (note that the examples 310 below follow the conventions for textproto, and Golang-style 311 backticks are used for string literals that would otherwise require 312 escaping): 314 For "/a/b[name=b1]/c/d": 316 update: < 317 path: < 318 element: "a" 319 element: "b[name=b1]" 320 element: "c" 321 element: "d" 322 > 323 value: < 324 value: "AStringValue" 325 type: JSON 326 > 327 > 329 For "/a/b[name=b1]/c/e": 331 update: < 332 path: < 333 element: "a" 334 element: "b[name=b1]" 335 element: "c" 336 element: "e" 337 > 338 value: < 339 Value: 10042 // decoded byte array 340 type: JSON 341 > 342 > 344 For "/a/b[name=b1]/c": 346 update: < 347 path: < 348 element: "a" 349 element: "b[name=b1]" 350 element: "c" 351 > 352 value: < 353 value: { "d": "AStringValue", "e": 10042 } 354 type: JSON 355 > 356 > 358 For "/a" : 360 update: < 361 path: < 362 element: "a" 363 > 364 value: < 365 value: `{ "b": [ 366 { 367 "name": "b1", 368 "c": { 369 "d": "AStringValue", 370 "e": 10042 371 } 372 } 373 ] 374 }` 375 type: JSON_IETF 376 > 377 > 379 Note that all JSON values MUST be valid JSON. That is to say, whilst 380 a value or object may be included in the message, the relevant 381 quoting according to the JSON specification in RFC7159 [8] must be 382 used. This results in quoted string values, and unquoted number 383 values. 385 "JSON_IETF" encoded data MUST conform with the rules for JSON 386 serialisation described in RFC7951 [9]. Data specified with a type 387 of JSON MUST be valid JSON, but no additional constraints are placed 388 upon it. An implementation MUST NOT serialise data with mixed "JSON" 389 and "JSON_IETF" encodings. 391 Both the client and target MUST support the JSON encoding as a 392 minimum. 394 2.3.2. Bytes 396 The "BYTES" type indicates that the contents of the "bytes" field of 397 the message contains a byte sequence whose semantics is opaque to the 398 protocol. 400 2.3.3. Protobuf 402 The "PROTOBUF" type indicates that the contents of the "bytes" field 403 of the message contains a serialised protobuf message. Note that in 404 the case that the sender utilises this type, the receiver must 405 understand the schema (and hence the type of protobuf message that is 406 serialised) in order to decode the value. Such agreement is not 407 guaranteed by the protocol and hence must be established out-of-band. 409 2.3.4. ASCII 411 The "ASCII" type indicates that the contents of the "bytes" field of 412 the message contains system-formatted ASCII encoded text. For 413 configuration data, for example, this may consist of semi-structured 414 CLI configuration data formatted according to the target platform. 415 The gNMI protocol does not define the format of the text - this must 416 be established out-of-band. 418 2.4. Use of Data Schema Paths 420 2.4.1. Path Prefixes 422 In a number of messages, a prefix can be specified to reduce the 423 lengths of path fields within the message. In this case, a "prefix" 424 field is specified within a message - comprising of a valid path 425 encoded according to Section Section 2.2.2 In the case that a prefix 426 is specified, the absolute path is comprised of the concatenation of 427 the list of path elements representing the prefix and the list of 428 path elements in the "path" field. 430 For example, again considering the data tree shown in 431 Section Section 2.3.1 if a "Notification" message updating values, a 432 prefix could be used to refer to the "/a/b[name=b1]/c/d" and 433 "/a/b[name=b1]/c/e"data nodes: 435 notification: < 436 timestamp: (timestamp) // timestamp as int64 437 prefix: < 438 element: "a" 439 element: "b[name=b1]" 440 element: "c" 441 > 442 update: < 443 path: < 444 element: "d" 445 > 446 value: < 447 value: "AStringValue" 448 type: JSON 449 > 450 > 451 update: < 452 path: < 453 element: "e" 454 > 455 value: < 456 value: 10042 // converted to int representation 457 type: JSON 458 > 459 > 460 > 462 2.4.2. Path Aliases 464 In some cases, a client or target MAY desire to utilises aliases for 465 a particular path - such that subsequent messages can be compressed 466 by utilising the alias, rather than using a complete representation 467 of the path. Doing so reduces total message length, by ensuring that 468 redundant information can be removed. 470 Support for path aliases MAY be provided by a target. In a case 471 where a target does not support aliases, the maximum message length 472 SHOULD be considered, especially in terms of bandwidth utilisation, 473 and the efficiency of message generation. 475 A path alias is encoded as a string. In order to avoid valid data 476 paths clashing with aliases (e.g., "a" in the above example), an 477 alias name MUST be prefixed with a "#" character. 479 The means by which an alias is created is defined on a per-RPC basis. 480 In order to delete an alias, the alias name is sent with the path 481 corresponding to the alias empty. 483 Aliases MUST be specified as a fully expanded path, and hence MUST 484 NOT reference other aliases within their definition, such that a 485 single alias lookup is sufficient to resolve the absolute path. 487 2.4.3. Interpretation of Paths Used in RPCs 489 When a client specifies a path within an RPC message which indicates 490 a read, or retrieval of data, the path MUST be interpreted such that 491 it refers to the node directly corresponding with the path *and* all 492 its children. The path refers to the direct node and all descendent 493 branches which originate from the node, recursively down to each leaf 494 element. If specific nodes are expected to be excluded then an RPC 495 MAY provide means to filter nodes, such as regular-expression based 496 filtering, lists of excluded paths, or metadata-based filtering 497 (based on annotations of the data schema being manipulated, should 498 such annotations be available and understood by both client and 499 target). 501 For example, consider the following data tree: 503 root + 504 | 505 +-- childA + 506 | | 507 | +-- leafA1 508 | +-- leafA2 509 | +-- childA3 --+ 510 | | 511 | +-- leafA31 512 | +-- leafA32 513 | 514 +-- childB + 515 | 516 +-- leafB1 517 +-- leafB2 519 A path referring to "root" (which is represented by a Path consisting 520 of a single element specifying an empty string) should result in the 521 nodes "childA" and "childB" and all of their children ("leafA1, 522 leafA2, leafB1, leafB2, childA3, leafA31" and "leafA32") being 523 considered by the relevant operation. 525 In the case that the RPC is modifying the state of data (i.e., a 526 write operation), such recursion is not required - rather the 527 modification operation should be considered to be targeted at the 528 node within the schema that is specified by the path, and the value 529 should be deserialized such that it modifies the content of any child 530 nodes if required to do so. 532 2.5. Error handling 534 Where the client or target wishes to indicate an error, an "Error" 535 message is generated. Errors MUST be represented by a canonical gRPC 536 error code (Java [10], Golang [11], C++ [12]) . The entity generating 537 the error MUST specify a free-text string which indicates the context 538 of the error, allowing the receiving entity to generate log entries 539 that allow a human operator to understand the exact error that 540 occurred, and its context. Each RPC defines the meaning of the 541 relevant canonical error codes within the context of the operation it 542 performs. 544 The canonical error code that is chosen MUST consider the expected 545 behavior of the client on receipt of the message. For example, error 546 codes which indicate that a client may subsequently retry SHOULD only 547 be used where retrying the RPC is expected to result in a different 548 outcome. 550 A re-usable "Error" message MUST be used when sending errors in 551 response to an RPC operation. This message has the following fields: 553 o "code" - an unsigned 32-bit integer value corresponding to the 554 canonical gRPC error code. 556 o "message"- a human-readable string describing the error condition 557 in more detail. This string is not expected to be machine- 558 parsable, but rather provide contextual information which may be 559 passed to upstream systems. 561 o "data"- an arbitrary sequence of bytes (encoded as 562 "[proto.Any](https://github.com/google/protobuf/blob/master/src/ 563 google/protobuf/any.proto)") which provides further contextual 564 information relating to the error. 566 2.6. Schema Definition Models 568 The data tree supported by the target is expected to be defined by a 569 set of schemas. The definition and format of these models is out of 570 scope of this specification (YANG-modeled data is one example). In 571 the case that such schema definitions are used, the client should be 572 able to determine the models that are supported by the target, so 573 that it can generate valid modifications to the data tree, and 574 interpret the data returned by "Get" and "Subscribe" RPC calls. 576 Additionally, the client may wish to restrict the set of models that 577 are utilised by the target so that it can validate the data returned 578 to it against a specific set of data models. This is particularly 579 relevant where the target may otherwise add new values to restricted 580 value data elements (e.g., those representing an enumerated type), or 581 augment new data elements into the data tree. 583 In order to allow the client to restrict the set of data models to be 584 used when interacting with the target, the client MAY discover the 585 set of models that are supported by the target using the 586 "Capabilities" RPC described in Section 3.2. For subsequent "Get" 587 and "Subscribe" RPCs, the client MAY specify the models to be used by 588 the target. The set of models to use is expressed as a "ModelData" 589 message, as specified in Section 2.6.1. 591 If the client specifies a set of models in a "Get" or "Subscribe" 592 RPC, the target MUST NOT utilize data tree elements that are defined 593 in schema modules outside the specified set. In addition, where 594 there are data tree elements that have restricted value sets (e.g., 595 enumerated types), and the set is extended by a module which is 596 outside of the set, such values MUST NOT be used in data instances 597 that are sent to the client. Where there are other elements of the 598 schema that depend on the existence of such enumerated values, the 599 target MUST NOT include such values in data instances sent to the 600 client. 602 2.6.1. The ModelData message 604 The "ModelData" message describes a specific model that is supported 605 by the target and used by the client. The fields of the "ModelData" 606 message identify a data model registered in a model catalog, as 607 described in [MODEL_CATALOG_DOC] [13] (the schema of the catalog 608 itself - expressed in YANG - is described in [MODEL_CATALOG_YANG 609 [14]]). Each model specified by a "ModelData" message may refer to a 610 specific schema module, a bundle of modules, or an augmentation or 611 deviation, as described by the catalog entry. 613 Each "ModelData" message contains the following fields: 615 o "name" - name of the model expressed as a string. 617 o "organization" - the organization publishing the model, expressed 618 as a string. 620 o "version" - the supported (or requested) version of the model, 621 expressed as a string which represents the semantic version of the 622 catalog entry. 624 The combination of "name", "organization", and "version" uniquely 625 identifies an entry in the model catalog. 627 3. Service Definition 629 A single gRPC service is defined - future revisions of this 630 specification MAY result in additional services being introduced, and 631 hence an implementation MUST NOT make assumptions that limit to a 632 single service definition. 634 The service consists of the following RPCs: 636 o "Capabilities" - defined in Section 3.2 and used by the client and 637 target as an initial handshake to exchange capability information 639 o "Get" - defined in Section 3.3, used to retrieve snapshots of the 640 data on the target by the client. 642 o "Set" - defined in Section 3.4 and used by the client to modify 643 the state of the target. 645 o "Subscribe" - defined in Section 3.5 and used to control 646 subscriptions to data on the target by the client. 648 3.1. Session Security, Authentication and RPC Authorization 650 The session between the client and server MUST be encrypted using TLS 651 - and a target or client MUST NOT fall back to unencrypted channels. 653 New connections are mutually authenticated -- each entity validates 654 the X.509 certificate of the remote entity to ensure that the remote 655 entity is both known, and authorized to connect to the local system. 657 If the target is expected to authenticate an RPC operation, the 658 client MUST supply a username and password in the metadata of the RPC 659 message (e.g., "SubscribeRequest", "GetRequest" or "SetRequest"). If 660 the client supplies username/password credentials, the target MUST 661 authenticate the RPC per its local authentication functionality. 663 Authorization is also performed per-RPC by the server, through 664 validating client-provided metadata. The client MAY include the 665 appropriate AAA metadata, which MUST contain a username, and MAY 666 include a password in the context of each RPC call it generates. If 667 the client includes both username and password, the target MUST 668 authenticate and authorize the request. If the client only supplies 669 the username, the target MUST authorize the RPC request. 671 A more detailed discussion of the requirements for authentication and 672 encryption used for gNMI is in [GNMI-AUTH] [15]. 674 3.2. Capability Discovery 676 A client MAY discover the capabilities of the target using the 677 "Capabilities" RPC. The "CapabilityRequest" message is sent by the 678 client to interrogate the target. The target MUST reply with a 679 "CapabilityResponse" message that includes its gNMI service version, 680 the versioned data models it supports, and the supported data 681 encodings. This information is used in subsequent RPC messages from 682 the client to indicate the set of models that the client will use 683 (for "Get", "Subscribe" as described in Section 2.6) , and the 684 encoding to be used for the data. 686 When the client does not specify the models it is using, the target 687 SHOULD use all data schema modules that it supports when considering 688 the data tree to be addressed. If the client does not specify the 689 encoding in an RPC message, it MUST send JSON encoded values (the 690 default encoding). 692 3.2.1. The CapabilityRequest message 694 The "CapabilityRequest" message is sent by the client to request 695 capability information from the target. The "CapabilityRequest" 696 message carries no additional fields. 698 3.2.2. The CapabilityResponse message 700 The "CapabilityResponse" message has the following fields: 702 o "supported_models" - a set of "ModelData" messages (as defined in 703 Section 2.6.1) describing each of the models supported by the 704 target 706 o "supported_encodings" - an enumeration field describing the data 707 encodings supported by the target, as described in Section 2.3. 709 o "gNMI_version" - the semantic version of the gNMI service 710 supported by the target, specified as a string. The version 711 should be interpreted as per [OPENCONFIG-SEMVER [16]]. 713 3.3. Retrieving Snapshots of State Information 715 In some cases, a client may require a snapshot of the state that 716 exists on the target. In such cases, a client desires some subtree 717 of the data tree to be serialized by the target and transmitted to 718 it. It is expected that the values that are retrieved (whether 719 writeable by the client or not) are collected immediately and 720 provided to the client. 722 The "Get" RPC provides an interface by which a client can request a 723 set of paths to be serialized and transmitted to it by the target. 724 The client sends a "GetRequest" message to the target, specifying the 725 data that is to be retrieved. The fields of the "GetRequest" message 726 are described in Section 3.3.1. 728 Upon reception of a "GetRequest", the target serializes the requested 729 paths, and returns a "GetResponse" message. The target MUST reflect 730 the values of the specified leaves at a particular collection time, 731 which MAY be different for each path specified within the 732 "GetRequest" message. 734 The target closes the channel established by the "Get" RPC following 735 the transmission of the "GetResponse" message. 737 3.3.1. The GetRequest Message 739 The "GetRequest" message contains the following fields: 741 o "prefix" - a path (specified as per Section 2.2.2), and used as 742 described in Section 2.4.1. The prefix is applied to all paths 743 within the "GetRequest" message. 745 o "path" - a set of paths (expressed as per Section 2.2.2) for which 746 the client is requesting a data snapshot from the target. The 747 path specified MAY utilize wildcards. In the case that the path 748 specified is not valid, the target MUST populate the "error" field 749 of the "GetResponse" message indicating an error code of 750 "InvalidArgument" and SHOULD provide information about the invalid 751 path in the error message. 753 o "type" - the type of data that is requested from the target. The 754 valid values for type are described below. 756 o "encoding" - the encoding that the target should utilise to 757 serialise the subtree of the data tree requested. The type MUST 758 be one of the encodings specified in Section 2.3. If the 759 "Capabilities" RPC has been utilised, the client SHOULD use an 760 encoding advertised as supported by the target. If the encoding 761 is not specified, JSON MUST be used. If the target does not 762 support the specified encoding, the target MUST populate the error 763 field of the "GetResponse" message, specifying an error of 764 "InvalidArgument". The error message MUST indicate that the 765 specified encoding is unsupported. 767 o "use_models" - a set of "ModelData" messages (defined in 768 Section 2.6.1) indicating the schema definition modules that 769 define the data elements that should be returned in response to 770 the Get RPC call. The semantics of the "use_models" field are 771 defined in Section 2.6. 773 Since the data tree stored by the target may consist of different 774 types of data (e.g., values that are operational in nature, such as 775 protocol statistics) - the client MAY specify that a subset of values 776 in the tree are of interest. In order for such filtering to be 777 implemented, the data schema on the target MUST be annotated in a 778 manner which specifies the type of data for individual leaves, or 779 subtrees of the data tree. 781 The types of data currently defined are: 783 o "CONFIG" - specified to be data that the target considers to be 784 read/write. If the data schema is described in YANG, this 785 corresponds to the "config true" set of leaves on the target. 787 o "STATE" - specified to be the read-only data on the target. If 788 the data schema is described in YANG, "STATE" data is the "config 789 false" set of leaves on the target. 791 o "OPERATIONAL" - specified to be the read-only data on the target 792 that is related to software processes operating on the device, or 793 external interactions of the device. 795 If the "type" field is not specified, the target MUST return CONFIG, 796 STATE and OPERATIONAL data fields in the tree resulting from the 797 client's query. 799 3.3.2. The GetResponse message 801 The "GetResponse" message consists of: 803 o "notification" - a set of "Notification" messages, as defined in 804 Section 2.1. The target MUST generate a "Notification" message 805 for each path specified in the client's "GetRequest", and hence 806 MUST NOT collapse data from multiple paths into a single 807 "Notification" within the response. The "timestamp" field of the 808 "Notification" message MUST be set to the time at which the 809 target's snapshot of the relevant path was taken. 811 o "error" - an "Error" message encoded as per the specification in 812 Section 2.5, used to indicate errors in the "GetRequest" received 813 by the target from the client. 815 3.3.3. Considerations for using Get 817 The "Get" RPC is intended for clients to retrieve relatively small 818 sets of data as complete objects, for example a part of the 819 configuration. Such requests are not expected to put a significant 820 resource burden on the target. Since the target is expected to 821 return the entire snapshot in the "GetResponse" message, "Get" is not 822 well-suited for retrieving very large data sets, such as the full 823 contents of the routing table, or the entire component inventory. 824 For such operations, the "Subscribe" RPC is the recommended 825 mechanism, e.g. using the "ONCE" mode as described in Section 3.5. 827 Another consideration for "Get" is that the timestamp returned is 828 associated with entire set of data requested, although individual 829 data items may have been sampled by the target at different times. 830 If the client requires higher accuracy for individual data items, the 831 "Subscribe" RPC is recommended to request a telemetry stream (see 832 Section 3.5.2). 834 3.4. Modifying State 836 Modifications to the state of the target are made through the "Set" 837 RPC. A client sends a "SetRequest" message to the target indicating 838 the modifications it desires. 840 A target receiving a "SetRequest" message processes the operations 841 specified within it - which are treated as a transaction (see 842 Section 3.4.3). The server MUST process deleted paths (within the 843 "delete" field of the "SetRequest"), followed by paths to be replaced 844 (within the "replace" field), and finally updated paths (within the 845 "update" field). The order of the replace and update fields MUST be 846 treated as significant within a single "SetRequest" message. If a 847 single path is specified multiple times for a single operation (i.e., 848 within "update" or "replace"), then the state of the target MUST 849 reflect the application of all of the operations in order, even if 850 they overwrite each other. 852 In response to a "SetRequest", the target MUST respond with a 853 "SetResponse" message. For each operation specified in the 854 "SetRequest" message, an "UpdateResult" message MUST be included in 855 the response field of the "SetResponse". The order in which the 856 operations are applied MUST be maintained such that "UpdateResult" 857 messages can be correlated to the "SetRequest" operations. In the 858 case of a failure of an operation, the "error" field of the 859 "UpdateResult" message MUST be populated with an "Error" message as 860 per the specification in Section 2.5. In addition, the "error" field 861 of the "SetResponse" message MUST be populated with an error message 862 indicating the success or failure of the set of operations within the 863 "SetRequest" message (again using the error handling behavior defined 864 in Section 2.5). 866 3.4.1. The SetRequest Message 868 A "SetRequest" message consists of the following fields: 870 o "prefix" - specified as per Section 2.4.1. The prefix specified 871 is applied to all paths defined within other fields of the 872 message. 874 o "delete" - A set of paths, specified as per Section 2.2.2, which 875 are to be removed from the data tree. A specification of the 876 behavior of a delete is defined in Section 3.4.6. 878 o "replace" - A set of "Update" messages indicating elements of the 879 data tree whose content is to be replaced. 881 o "update" - A set of "Update" messages indicating elements of the 882 data tree whose content is to be updated. 884 The semantics of "updating" versus "replacing" content are defined in 885 Section 3.4.4 887 A re-usable "Update" message is utilised to indicate changes to paths 888 where a new value is required. The "Update" message contains two 889 fields: 891 o "path" - a path encoded as per Section 2.2.2 indicating the path 892 of the element to be modified. 894 o "value" - a value encoded as per Section 2.2.3 indicating the 895 value applied to the specified node. The semantics of how the 896 node is updated is dependent upon the context of the update 897 message, as specified in Section 3.4.4. 899 3.4.2. The SetResponse Message 901 A "SetResponse" consists of the following fields: 903 o "prefix" - specified as per Section 2.4.1. The prefix specified 904 is applied to all paths defined within other fields of the 905 message. 907 o "message" - an error message as specified in Section 2.5. The 908 target SHOULD specify a "message" in the case that the update was 909 successfully applied, in which case an error code of "OK (0)" 910 "MUST" be specified. In cases where an update was not 911 successfully applied, the contents of the error message MUST be 912 specified as per Section 2.5. 914 o "response" - containing a list of responses, one per operation 915 specified within the "SetRequest" message. Each response consists 916 of an "UpdateResult" message with the following fields: 918 * "timestamp" - a timestamp (encoded as per Section 2.2.1) at 919 which the set request message was accepted by the system. 921 * "path" - the path (encoded as per Section 2.2.2) specified 922 within the "SetRequest". In the case that a common prefix was 923 not used within the "SetRequest", the target MAY specify a 924 "prefix" to reduce repetition of path elements within multiple 925 "UpdateResult" messages in the "request" field. 927 * "op" - the operation corresponding to the path. This value 928 MUST be one of "DELETE", "REPLACE", or "UPDATE". 930 * "message" - an error message (as specified in Section 2.5). 931 This field follows the same rules as the message field within 932 the "SetResponse" message specified above. 934 3.4.3. Transactions 936 All changes to the state of the target that are included in an 937 individual "SetRequest" message are considered part of a transaction. 938 That is, either all modifications within the request are applied, or 939 the target MUST rollback the state changes to reflect its state 940 before any changes were applied. The state of the target MUST NOT 941 appear to be changed until such time as all changes have been 942 accepted successfully. Hence, telemetry update messages MUST NOT 943 reflect a change in state until such time as the intended 944 modifications have been accepted. 946 As per the specification in Section 3.4, within an individual 947 transaction ("SetRequest") the order of operations is "delete", 948 "replace", "update". 950 As the scope of a "transaction" is a single "SetRequest" message, a 951 client desiring a set of changes to be applied together MUST ensure 952 that they are encapsulated within a single "SetRequest" message. 954 3.4.4. Modes of Update: Replace versus Update 956 Changes to read-write values on the target are applied based on the 957 "replace" and "update" fields of the "SetRequest" message. 959 For both replace and update operations, if the path specified does 960 not exist, the target MUST create the data tree element and populate 961 it with the data in the "Update" message, provided the path is valid 962 according to the data tree schema. If invalid values are specified, 963 the target MUST cease processing updates within the "SetRequest" 964 method, return the data tree to the state prior to any changes, and 965 return a "SetResponse" message indicating the error encountered. 967 For "replace" operations, the behavior regarding omitted data 968 elements in the "Update" depends on whether they refer to non-default 969 values (i.e., set by a previous "SetRequest"), or unmodified 970 defaults. When the "replace" operation omits values that have been 971 previously set, they MUST be treated as deleted from the data tree. 972 Otherwise, omitted data elements MUST be created with their default 973 values on the target. 975 For "update" operations, only the value of those data elements that 976 are specified explicitly should be treated as changed. 978 3.4.5. Modifying Paths Identified by Attributes 980 The path convention defined in Section 2.2.2 allows nodes in the data 981 tree to be identified by a unique set of node names (e.g.,"/a/b/c/d") 982 or paths that consist of node names coupled with attributes (e.g., 983 "/a/e[key=10]"). In the case where where a node name plus attribute 984 name is required to uniquely identify an element (i.e., the path 985 within the schema represents a list, map, or array), the following 986 considerations apply: 988 o In the case that multiple attribute values are required to 989 uniquely address an element - e.g., "/a/f[k1=10][k2=20]"- and a 990 replace or update operation's path specifies a subset of the 991 attributes (e.g., "/a/f[k1=10]") then this MUST be considered an 992 error by the target system - and an error code of"InvalidArgument 993 (3)" specified. 995 o Where the path specified refers to a node which itself represents 996 the collection of objects (list, map, or array) a replace 997 operation MUST remove all collection entries that are not supplied 998 in the value provided in the "SetRequest". An update operation 999 MUST be considered to add new entries to the collection if they do 1000 not exist. 1002 o In the case that key values are specified both as attributes of a 1003 node, and as their own elements within the data tree, update or 1004 replace operations that modify instances of the key in conflicting 1005 ways MUST be considered an error. The target MUST return an error 1006 code of "InvalidArgument (3)". 1008 For example, consider a tree corresponding to the examples above, as 1009 illustrated below. 1011 root + 1012 | 1013 + a --+ 1014 | 1015 +-- f[k1=10][k2=20] --+ 1016 | | 1017 | +-- k1 = 10 1018 | +-- k2 = 20 1019 | 1020 +-- f[k1=10][k2=21] --+ 1021 | 1022 +-- k1 = 10 1023 +-- k2 = 21 1025 In this case, nodes "k1" and "k2" are standalone nodes within the 1026 schema, but also correspond to attribute values for the node ""f"". 1027 In this case, an update or replace message specifying a path of "/a/ 1028 f[k1=10][k2=20]" setting the value of "k1" to 100 MUST be considered 1029 erroneous, and an error code of "InvalidArgument (3)" specified. 1031 3.4.6. Deleting Configuration 1033 Where a path is contained within the "delete" field of the 1034 "SetRequest" message, it should be removed from the target's data 1035 tree. In the case that the path specified is to an element that has 1036 children, these children MUST be recursively deleted. If a wildcard 1037 path is utilised, the wildcards MUST be expanded by the target, and 1038 the corresponding elements of the data tree deleted. Such wildcards 1039 MUST support paths specifying a subset of attributes required to 1040 identify entries within a collection (list, array, or map) of the 1041 data schema. 1043 In the case that a path specifies an element within the data tree 1044 that does not exist, these deletes MUST be silently accepted. 1046 3.4.7. Error Handling 1048 When a client issues a "SetRequest", and the target is unable to 1049 apply the specified changes, an error MUST be reported to the client. 1050 The error is specified in multiple places: 1052 o Within a "SetResponse" message, the error field indicates the 1053 completion status of the entire transaction. 1055 o With a "UpdateResult" message, where the error field indicates the 1056 completion status of the individual operation. 1058 The target MUST specify the "message" field within a "SetResponse" 1059 message such that the overall status of the transaction is reflected. 1060 In the case that no error occurs, the target MUST complete this field 1061 specifying the "OK (0)" canonical error code. 1063 In the case that any operation within the "SetRequest" message fails, 1064 then (as per Section 3.4.3), the target MUST NOT apply any of the 1065 specified changes, and MUST consider the transaction as failed. The 1066 target SHOULD set the "message" field of the "SetResponse" message to 1067 an error message with the code field set to "Aborted (10)", and MUST 1068 set the "message" field of the "UpdateResult" corresponding to the 1069 failed operation to an "Error" message indicating failure. In the 1070 case that the processed operation is not the only operation within 1071 the "SetRequest" the target MUST set the "message" field of the 1072 "UpdateResult" messages for all other operations, setting the code 1073 field to "Aborted (10)". 1075 For the operation that the target is unable to process, the "message" 1076 field MUST be set to a specific error code indicating the reason for 1077 failure based on the following mappings to canonical gRPC error 1078 codes: 1080 o When the client has specified metadata requiring authentication 1081 (see Section 3.1), and the authentication fails - "Unauthenticated 1082 (16)". 1084 o When the client does not have permission to modify the path 1085 specified by the operation - "PermissionDenied (7)". 1087 o When the operation specifies a path that cannot be parsed by the 1088 target - "InvalidArgument (3)". In this case, the "message" field 1089 of the "Error" message specified SHOULD specify human-readable 1090 text indicating that the path could not be parsed. 1092 o When the operation is an update or replace operation that 1093 corresponds to a path that is not valid - "NotFound (5)". In this 1094 case the "message" field of the "Error" message specified SHOULD 1095 specify human-readable text indicating the path that was invalid. 1097 o When the operation is an update or replace operation that includes 1098 an invalid value within the "Update" message specified - 1099 "InvalidArgument (3)". This error SHOULD be used in cases where 1100 the payload specifies scalar values that do not correspond to the 1101 correct schema type, and in the case that multiple values are 1102 specified using a particular encoding (e.g., JSON) which cannot be 1103 decoded by the target. 1105 3.5. Subscribing to Telemetry Updates 1107 When a client wishes to receive updates relating to the state of data 1108 instances on a target, it creates a subscription via the "Subscribe" 1109 RPC. A subscription consists of one or more paths, with a specified 1110 subscription mode. The mode of each subscription determines the 1111 triggers for updates for data sent from the target to the client. 1113 All requests for new subscriptions are encapsulated within a 1114 "SubscribeRequest" message - which itself has a mode which describes 1115 the longevity of the subscription. A client may create a 1116 subscription which has a dedicated stream to return one-off data 1117 ("ONCE"); a subscription that utilizes a stream to periodically 1118 request a set of data ("POLL"); or a long-lived subscription that 1119 streams data according to the triggers specified within the 1120 individual subscription's mode ("STREAM"). 1122 The target generates messages according to the type of subscription 1123 that has been created, at the frequency requested by the client. The 1124 methods to create subscriptions are described in Section 3.5.1. 1126 Subscriptions are created for a set of paths - which cannot be 1127 modified throughout the lifetime of the subscription. In order to 1128 cancel a subscription, the client closes the gRPC channel over which 1129 the "Subscribe" RPC was initiated, or terminates the entire gRPC 1130 session. 1132 Subscriptions are fundamentally a set of independent update messages 1133 relating to the state of the data tree. That is, it is not possible 1134 for a client requesting a subscription to assume that the set of 1135 update messages received represent a snapshot of the data tree at a 1136 particular point in time. Subscriptions therefore allow a client to: 1138 o Receive ongoing updates from a target which allow synchronization 1139 between the client and target for the state of elements within the 1140 data tree. In this case (i.e., a "STREAM" subscription), a client 1141 creating a subscription receives an initial set of updates, 1142 terminated by a message indicating that initial synchronisation 1143 has completed, and then receives subsequent updates indicating 1144 changes to the initial state of those elements. 1146 o Receive a single view (polled, or one-off) for elements of the 1147 data tree on a per-data element basis according to the state that 1148 they are in at the time that the message is transmitted. This can 1149 be more resource efficient for both target and client than a 1150 "GetRequest" for large subtrees within the data tree. The target 1151 does not need to coalesce values into a single snapshot view, or 1152 create an in-memory representation of the subtree at the time of 1153 the request, and subsequently transmit this entire view to the 1154 client. 1156 Based on the fact that subsequent update messages are considered to 1157 be independent, and to ensure that the efficiencies described above 1158 can be achieved, by default a target MUST NOT aggregate values within 1159 an update message. 1161 In some cases, however, elements of the data tree may be known to 1162 change together, or need to be interpreted by the subscriber 1163 together. Such data MUST be explicitly marked in the schema as being 1164 eligible to be aggregated when being published. Additionally, the 1165 subscribing client MUST explicitly request aggregation of eligible 1166 schema elements for the subscription - by means of the 1167 "allow_aggregation" flag within a "SubscriptionList" message. For 1168 elements covered by a subscription that are not explicitly marked 1169 within the schema as being eligible for aggregation the target MUST 1170 NOT coalesce these values, regardless of the value of the 1171 "allow_aggregation" flag. 1173 When aggregation is not permitted by the client or the schema each 1174 update message MUST contain a (key, value) pair - where the key MUST 1175 be a path to a single leaf element within the data tree (encoded 1176 according to Section 2.2.2). The value MUST encode only the value of 1177 the leaf specified. In most cases, this will be a scalar value 1178 (i.e., a JSON value if a JSON encoding is utilised), but in some 1179 cases, where an individual leaf element within the schema represents 1180 an object, it MAY represent a set of values (i.e., a JSON or Protobuf 1181 object). 1183 Where aggregation is permitted by both the client and schema, each 1184 update message MUST contain a key value pair, where the key MUST be 1185 the path to the element within the data tree which is explicitly 1186 marked as being eligible for aggregation. The value MUST be an 1187 object which encodes the children of the data tree element specified. 1189 For JSON, the value is therefore a JSON object, and for Protobuf is a 1190 series of binary-encoded Protobuf messages. 1192 3.5.1. Managing Subscriptions 1194 3.5.1.1. The SubscribeRequest Message 1196 A "SubscribeRequest" message is sent by a client to request updates 1197 from the target for a specified set of paths. 1199 The fields of the "SubscribeRequest" are as follows: 1201 o A group of fields, only one of which may be specified, which 1202 indicate the type of operation that the "SubscribeRequest" relates 1203 to. These are: 1205 * "subscribe" - a "SubscriptionList" message specifying a new set 1206 of paths that the client wishes to subscribe to. 1208 * "poll"- a "Poll" message used to specify (on an existing 1209 channel) that the client wishes to receive a polled update for 1210 the paths specified within the subscription. The semantics of 1211 the "Poll" message are described in Section 3.5.1.5.3. 1213 * "aliases" - used by a client to define (on an existing channel) 1214 a new path alias (as described in Section 2.4.2). The use of 1215 the aliases message is described in Section 3.5.1.6. 1217 In order to create a new subscription (and its associated channel) a 1218 client MUST send a "SubscribeRequest" message, specifying the 1219 "subscribe" field. The "SubscriptionList" may create a one-off 1220 subscription, a poll-only subscription, or a streaming subscription. 1221 In the case of ONCE subscriptions, the channel between client and 1222 target MUST be closed following the initial response generation. 1224 Subscriptions are set once, and subsequently not modified by a 1225 client. If a client wishes to subscribe to additional paths from a 1226 target, it MUST do so by sending an additional "Subscribe" RPC call, 1227 specifying a new "SubscriptionList" message. In order to end an 1228 existing subscription, a client simply closes the gRPC channel that 1229 relates to that subscription. If a channel is initiated with a 1230 "SubscribeRequest" message that does not specify a "SubscriptionList" 1231 message with the "request" field, the target MUST consider this an 1232 error. If an additional "SubscribeRequest" message specifying a 1233 "SubscriptionList" is sent via an existing channel, the target MUST 1234 respond to this message with "SubscribeResponse" message indicating 1235 an error message, with a contained error message indicating an error 1236 code of "InvalidArgument (4)"; existing subscriptions on other gRPC 1237 channels MUST not be modified or terminated. 1239 If a client initiates a "Subscribe" RPC with a "SubscribeRequest" 1240 message which does not contain a "SubscriptionList" message, this is 1241 an error. A "SubscribeResponse" message with the contained "error" 1242 message indicating a error code of "InvalidArgument" MUST be sent. 1243 The error text SHOULD indicate that an out-of-order operation was 1244 requested on a non-existent subscription. The target MUST 1245 subsequently close the channel. 1247 3.5.1.2. The SubscriptionList Message 1249 A "SubscriptionList" message is used to indicate a set of paths for 1250 which common subscription behavior are required. The fields of the 1251 message are: 1253 o "subscription" - a set of "Subscription" messages that indicate 1254 the set of paths associated with the subscription list. 1256 o "mode" - the type of subscription that is being created. This may 1257 be "ONCE" (described in Section 3.5.1.5.1); "STREAM" (described in 1258 Section 3.5.1.5.2); or "POLL" (described in Section 3.5.1.5.3). 1259 The default value for the mode field is "STREAM". 1261 o "prefix"- a common prefix that is applied to all paths specified 1262 within the message as per the definition in Section 2.4.1. The 1263 default prefix is null. 1265 o "use_aliases"- a boolean flag indicating whether the client 1266 accepts target aliases via the subscription channel. In the case 1267 that such aliases are accepted, the logic described in 1268 Section 2.4.2 is utilised. By default, path aliases created by 1269 the target are not supported. 1271 o "qos" - a field describing the packet marking that is to be 1272 utilised for the responses to the subscription that is being 1273 created. This field has a single sub-value, "marking", which 1274 indicates the DSCP value as a 32-bit unsigned integer. If the 1275 "qos" field is not specified, the device should export telemetry 1276 traffic using its default DSCP marking for management-plane 1277 traffic. 1279 o "allow_aggregation" - a boolean value used by the client to allow 1280 schema elements that are marked as eligible for aggregation to be 1281 combined into single telemetry update messages. By default, 1282 aggregation MUST NOT be used. 1284 o "use_models" - a "ModelData" message (as specified in 1285 Section 2.6.1) specifying the schema definition modules that the 1286 target should use when creating a subscription. When specified, 1287 the target MUST only consider data elements within the defined set 1288 of schema models as defined in Section 2.6. When "use_models" is 1289 not specified, the target MUST consider all data elements that are 1290 defined in all schema modules that it supports. 1292 A client generating a "SubscriptionList" message MUST include the 1293 "subscription" field - which MUST be a non-empty set of 1294 "Subscription" messages, all other fields are optional. 1296 3.5.1.3. The Subscription Message 1298 A "Subscription" message generically describes a set of data that is 1299 to be subscribed to by a client. It contains a "path", specified as 1300 per the definition in Section 2.2.2. 1302 There is no requirement for the path that is specified within the 1303 message to exist within the current data tree on the server. Whilst 1304 the path within the subscription SHOULD be a valid path within the 1305 set of schema modules that the target supports, subscribing to any 1306 syntactically valid path within such modules MUST be allowed. In the 1307 case that a particular path does not (yet) exist, the target MUST NOT 1308 close the channel, and instead should continue to monitor for the 1309 existence of the path, and transmit telemetry updates should it exist 1310 in the future. The target MAY send a "SubscribeResponse" message 1311 populating the error field with "NotFound (5)" to inform the client 1312 that the path does not exist at the time of subscription creation. 1314 For "POLL" and "STREAM" subscriptions, a client may optionally 1315 specify additional parameters within the "Subscription" message. The 1316 semantics of these additional fields are described in the relevant 1317 section of this document. 1319 3.5.1.4. The SubscribeResponse Message 1321 A "SubscribeResponse" message is transmitted by a target to a client 1322 over an established channel created by the "Subscribe" RPC. The 1323 message contains the following fields: 1325 o A set of fields referred to as the "response" fields, only one of 1326 which can be specified per "SubscribeResponse" message: 1328 * "update" - a "Notification" message providing an update value 1329 for a subscribed data entity as described in Section 3.5.2. 1330 The "update" field is also utilised when a target wishes to 1331 create an alias within a subscription, as described in 1332 Section 3.5.2.2. 1334 * "sync_response" - a boolean field indicating that a particular 1335 set of data values has been transmitted, used for "POLL" and 1336 "STREAM" subscriptions. 1338 * "error" - an "Error" message transmitted to indicate an error 1339 has occurred within a particular "Subscribe" RPC call. 1341 3.5.1.5. Creating Subscriptions 1343 3.5.1.5.1. ONCE Subscriptions 1345 A subscription operating in the "ONCE" mode acts as a single request/ 1346 response channel. The target creates the relevant update messages, 1347 transmits them, and subsequently closes the channel. 1349 In order to create a one-off subscription, a client sends a 1350 "SubscribeRequest" message to the target. The "subscribe" field 1351 within this message specifies a "SubscriptionList" with the mode 1352 field set to "ONCE". Updates corresponding to the subscription are 1353 generated as per the semantics described in Section 3.5.2. 1355 Following the transmission of all updates which correspond to data 1356 items within the set of paths specified within the subscription list, 1357 a "SubscribeResponse" message with the "sync_response" field set to 1358 "true" MUST be transmitted, and the channel over which the 1359 "SubscribeRequest" was received MUST be closed. 1361 3.5.1.5.2. STREAM Subscriptions 1363 Stream subscriptions are long-lived subscriptions which continue to 1364 transmit updates relating to the set of paths that are covered within 1365 the subscription indefinitely. 1367 A "STREAM" subscription is created by sending a "SubscribeRequest" 1368 message with the subscribe field containing a "SubscriptionList" 1369 message with the type specified as "STREAM". Each entry within the 1370 "Subscription" message is specified with one of the following 1371 "modes": 1373 o On Change ("ON_CHANGE") - when a subscription is defined to be "on 1374 change", data updates are only sent when the value of the data 1375 item changes. A heartbeat interval MAY be specified along with an 1376 "on change" subscription - in this case, the value of the data 1377 item(s) MUST be re-sent once per heartbeat interval regardless of 1378 whether the value has changed or not. 1380 o Sampled ("SAMPLE") - a subscription that is defined to be sampled 1381 MUST be specified along with a "sample_interval" encoded as an 1382 unsigned 64-bit integer representing nanoseconds. The value of 1383 the data item(s) is sent once per sample interval to the client. 1384 If the target is unable to support the desired "sample_interval" 1385 it MUST reject the subscription by returning a "SubscribeResponse" 1386 message with the error field set to an error message indicating 1387 the "InvalidArgument (3)" error code. If the "sample_interval" is 1388 set to 0, the target MUST create the subscription and send the 1389 data with the lowest interval possible for the target. 1391 * Optionally, the "suppress_redundant" field of the 1392 "Subscription" message may be set for a sampled subscription. 1393 In the case that it is set to "true", the target SHOULD NOT 1394 generate a telemetry update message unless the value of the 1395 path being reported on has changed since the last update was 1396 generated. Updates MUST only be generated for those individual 1397 leaf nodes in the subscription that have changed. That is to 1398 say that for a subscription to "/a/b" - where there are leaves 1399 "c" and "d" branching from the "b" node - if the value of "c" 1400 has changed, but "d" remains unchanged, an update for "d" MUST 1401 NOT be generated, whereas an update for "c" MUST be generated. 1403 * A "heartbeat_interval" MAY be specified to modify the behavior 1404 of "suppress_redundant" in a sampled subscription. In this 1405 case, the target MUST generate one telemetry update per 1406 heartbeat interval, regardless of whether the 1407 "suppress_redundant" flag is set to "true". This value is 1408 specified as an unsigned 64-bit integer in nanoseconds. 1410 o Target Defined "(TARGET_DEFINED)" - when a client creates a 1411 subscription specifying the target defined mode, the target SHOULD 1412 determine the best type of subscription to be created on a per- 1413 leaf basis. That is to say, if the path specified within the 1414 message refers to some leaves which are event driven (e.g., the 1415 changing of state of an entity based on an external trigger) then 1416 an "ON_CHANGE" subscription may be created, whereas if other data 1417 represents counter values, a "SAMPLE" subscription may be created. 1419 3.5.1.5.3. POLL Subscriptions 1421 Polling subscriptions are used for on-demand retrieval of statistics 1422 via long-lived channels. A poll subscription relates to a certain 1423 set of subscribed paths, and is initiated by sending a 1424 "SubscribeRequest" message with encapsulated "SubscriptionList". 1425 "Subscription" messages contained within the "SubscriptionList" 1426 indicate the set of paths that are of interest to the polling client. 1428 To retrieve data from the target, a client sends a "SubscribeRequest" 1429 message to the target, containing a "poll" field, specified to be an 1430 empty "Poll" message. On reception of such a message, the target 1431 MUST generate updates for all the corresponding paths within the 1432 "SubscriptionList". Updates MUST be generated according to 1433 Section 3.5.2. 1435 3.5.1.6. Client-defined Aliases within a Subscription 1437 When a client wishes to create an alias that a target should use for 1438 a path, the client should send a "SubscribeRequest" message 1439 specifying the "aliases" field. The "aliases" field consists of an 1440 "AliasList" message. An "AliasList" specifies a list of aliases, 1441 each of which consists of: 1443 o "path" - the target path for the alias - encoded as per 1444 Section 2.2.2. 1446 o "alias" - the (client-defined) alias for the path, encoded as per 1447 Section 2.4.2. 1449 Where a target is unable to support a client-defined alias it SHOULD 1450 respond with a "SubscribeResponse" message with the error field 1451 indicating an error of the following types: 1453 o "InvalidArgument (3)" where the specified alias is not acceptable 1454 to the target. 1456 o "AlreadyExists (6)" where the alias defined is a duplicate of an 1457 existing alias for the client. 1459 o "ResourceExhausted (8)" where the target has insufficient memory 1460 or processing resources to support the alias. 1462 o "Unknown (2)" in all other cases. 1464 Thus, for a client to create an alias corresponding to the 1465 path"/a/b/c/d[id=10]/e" with the name "shortPath", it sends a 1466 "SubscribeRequest" message with the following fields specified: 1468 subscriberequest: < 1469 aliases: < 1470 alias: < 1471 path: < 1472 element: "a" 1473 element: "b" 1474 element: "c" 1475 element: "d[id=10]" 1476 element: "e" 1477 > 1478 alias: "#shortPath" 1479 > 1480 > 1481 > 1483 If the alias is acceptable to the target, subsequent updates are 1484 transmitted using the "#shortPath" alias in the same manner as 1485 described in Section 3.5.2.2. 1487 3.5.2. Sending Telemetry Updates 1489 3.5.2.1. Bundling of Telemetry Updates 1491 Since multiple "Notification" messages can be included in the update 1492 field of a "SubscribeResponse" message, it is possible for a target 1493 to bundle messages such that fewer messages are sent to the client. 1494 The advantage of such bundling is clearly to reduce the number of 1495 bytes on the wire (caused by message overhead). Since "Notification" 1496 messages contain the timestamp at which an event occurred, or a 1497 sample was taken, such bundling does not affect the sample accuracy 1498 to the client. However, bundling does have a negative impact on the 1499 freshness of the data in the client - and on the client's ability to 1500 react to events on the target. 1502 Since it is not possible for the target to infer whether its clients 1503 are sensitive to the latency introduced by bundling, if a target 1504 implements optimizations such that multiple "Notification" messages 1505 are bundled together, it MUST provide an ability to disable this 1506 functionality within the configuration of the gNMI service. 1507 Additionally, a target SHOULD provide means by which the operator can 1508 control the maximum number of updates that are to be bundled into a 1509 single message, This configuration is expected to be implemented out- 1510 of-band to the gNMI protocol itself. 1512 3.5.2.2. Target-defined Aliases within a Subscription 1514 Where the "use_aliases" field of a "SubscriptionList" message has 1515 been set to "true", a target MAY create aliases for paths within a 1516 subscription. A target-defined alias MUST be created separately from 1517 an update to the corresponding data item(s). 1519 To create a target-defined alias, a "SubscribeResponse" message is 1520 generated with the "update" field set to a "Notification" message. 1521 The "Notification" message specifies the aliased path within the 1522 "prefix" field, and a non-null "alias" field, specified according to 1523 Section 2.4.2. 1525 Thus, a target wishing to create an alias relating to the path "/a/b/ 1526 c[id=10]" and subsequently update children of the "c[id=10]"entity 1527 must: 1529 1. Generate a "SubscribeResponse" message and transmit it over the 1530 channel to the client: 1532 subscriberesponse: < 1533 update: < 1534 timestamp: (timestamp) 1535 prefix: < 1536 element: "a" 1537 element: "b" 1538 element: "c[id=10]" 1539 > 1540 alias: "#42" 1541 > 1542 > 1544 1. Subsequently, this alias can be used to provide updates for the 1545 "child1" leaf corresponding to "/a/b/c[id=10]/child1": 1547 subscriberesponse: < 1548 update: < 1549 timestamp: (timestamp) 1550 prefix: < 1551 element: "#42" 1552 > 1553 update: < 1554 path: < 1555 element: "child1" 1556 > 1557 value: < 1558 value: 102 // integer representation 1559 type: JSON_IETF 1560 > 1561 > 1562 > 1563 > 1565 3.5.2.3. Sending Telemetry Updates 1567 When an update for a subscribed telemetry path is to be sent, a 1568 "SubscribeResponse" message is sent from the target to the client, on 1569 the channel associated with the subscription. The "update" field of 1570 the message contains a "Notification" message as per the description 1571 in Section 2.1. The "timestamp" field of the "Notification" message 1572 MUST be set to the time at which the value of the path that is being 1573 updated was collected. 1575 Where a leaf node's value has changed, or a new node has been 1576 created, an "Update" message specifying the path and value for the 1577 updated data item MUST be appended to the "update" field of the 1578 message. 1580 Where a node within the subscribed paths has been removed, the 1581 "delete" field of the "Notification" message MUST have the path of 1582 the node that has been removed appended to it. 1584 When the target has transmitted the initial updates for all paths 1585 specified within the subscription, a "SubscribeResponse" message with 1586 the "sync_response" field set to "true" MUST be transmitted to the 1587 client to indicate that the initial transmission of updates has 1588 concluded. This provides an indication to the client that all of the 1589 existing data for the subscription has been sent at least once. For 1590 "STREAM" subscriptions, such messages are not required for subsequent 1591 updates. For "POLL" subscriptions, after each set of updates for 1592 individual poll request, a "SubscribeResponse" message with the 1593 "sync_response" field set to "true" MUST be generated. 1595 4. References 1597 4.1. URIs 1599 [1] http://grpc.io 1601 [2] https://developers.google.com/protocol-buffers/ 1603 [3] https://github.com/openconfig/reference/blob/master/rpc/gnmi/ 1604 gnmi.proto 1606 [4] https://github.com/openconfig/reference/blob/master/rpc/gnmi/ 1607 gnmi-specification.md 1609 [5] http://www.openconfig.net/ 1611 [6] https://github.com/openconfig/reference/blob/master/rpc/gnmi/ 1612 gnmi-path-conventions.md 1614 [7] https://tools.ietf.org/html/rfc7159 1616 [8] https://tools.ietf.org/html/rfc7159 1618 [9] https://tools.ietf.org/html/rfc7951 1620 [10] http://www.grpc.io/grpc-java/javadoc/index.html 1622 [11] https://godoc.org/google.golang.org/grpc/codes#Code 1624 [12] http://www.grpc.io/grpc/cpp/classgrpc_1_1_status.html 1626 [13] https://datatracker.ietf.org/doc/draft-openconfig-netmod-model- 1627 catalog/ 1629 [14] https://tools.ietf.org/html/draft-openconfig-netmod-model- 1630 catalog-01 1632 [15] https://github.com/openconfig/reference/blob/master/rpc/gnmi/ 1633 gnmi-authentication.md 1635 [16] http://www.openconfig.net/documentation/semantic-versioning/ 1637 [17] https://github.com/openconfig/reference/blob/master/rpc/gnmi/ 1638 gnmi.proto 1640 Appendix A. Appendix: Current Protobuf Message and Service 1641 Specification 1643 The latest Protobuf IDL gNMI specification is found at [17]. 1645 Appendix B. Appendix: Current Outstanding Issues/Future Features 1647 o Ability for the client to exclude paths from a subscription or 1648 get. 1650 o "Dial out" for the target to register with an NMS and publish pre- 1651 configured subscriptions. 1653 Authors' Addresses 1655 Rob Shakir 1656 Google, Inc. 1657 1600 Amphitheatre Parkway 1658 Mountain View, CA 94043 1660 Email: robjs@google.com 1662 Anees Shaikh 1663 Google 1664 1600 Amphitheatre Pkwy 1665 Mountain View, CA 94043 1666 US 1668 Email: aashaikh@google.com 1670 Paul Borman 1671 Google 1672 1600 Amphitheatre Pkwy 1673 Mountain View, CA 94043 1674 US 1676 Email: borman@google.com 1678 Marcus Hines 1679 Google 1680 1600 Amphitheatre Pkwy 1681 Mountain View, CA 94043 1682 US 1684 Email: hines@google.com 1685 Carl Lebsack 1686 Google 1687 1600 Amphitheatre Pkwy 1688 Mountain View, CA 94043 1689 US 1691 Email: csl@google.com 1693 Chris Morrow 1694 Google 1696 Email: christopher.morrow@gmail.com