1// 2// Copyright 2016 Google Inc. All Rights Reserved. 3// 4// Licensed under the Apache License, Version 2.0 (the "License"); 5// you may not use this file except in compliance with the License. 6// You may obtain a copy of the License at 7// 8// http://www.apache.org/licenses/LICENSE-2.0 9// 10// Unless required by applicable law or agreed to in writing, software 11// distributed under the License is distributed on an "AS IS" BASIS, 12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13// See the License for the specific language governing permissions and 14// limitations under the License. 15// 16syntax = "proto3"; 17 18import "google/protobuf/any.proto"; 19import "google/protobuf/descriptor.proto"; 20import "gnmi_ext.proto"; 21 22// Package gNMI defines a service specification for the gRPC Network Management 23// Interface. This interface is defined to be a standard interface via which 24// a network management system ("client") can subscribe to state values, 25// retrieve snapshots of state information, and manipulate the state of a data 26// tree supported by a device ("target"). 27// 28// This document references the gNMI Specification which can be found at 29// http://github.com/openconfig/reference/blob/master/rpc/gnmi 30package gnmi; 31 32// Define a protobuf FileOption that defines the gNMI service version. 33extend google.protobuf.FileOptions { 34 // The gNMI service semantic version. 35 string gnmi_service = 1001; 36} 37 38// gNMI_service is the current version of the gNMI service, returned through 39// the Capabilities RPC. 40option (gnmi_service) = "0.7.0"; 41 42service gNMI { 43 // Capabilities allows the client to retrieve the set of capabilities that 44 // is supported by the target. This allows the target to validate the 45 // service version that is implemented and retrieve the set of models that 46 // the target supports. The models can then be specified in subsequent RPCs 47 // to restrict the set of data that is utilized. 48 // Reference: gNMI Specification Section 3.2 49 rpc Capabilities(CapabilityRequest) returns (CapabilityResponse); 50 // Retrieve a snapshot of data from the target. A Get RPC requests that the 51 // target snapshots a subset of the data tree as specified by the paths 52 // included in the message and serializes this to be returned to the 53 // client using the specified encoding. 54 // Reference: gNMI Specification Section 3.3 55 rpc Get(GetRequest) returns (GetResponse); 56 // Set allows the client to modify the state of data on the target. The 57 // paths to modified along with the new values that the client wishes 58 // to set the value to. 59 // Reference: gNMI Specification Section 3.4 60 rpc Set(SetRequest) returns (SetResponse); 61 // Subscribe allows a client to request the target to send it values 62 // of particular paths within the data tree. These values may be streamed 63 // at a particular cadence (STREAM), sent one off on a long-lived channel 64 // (POLL), or sent as a one-off retrieval (ONCE). 65 // Reference: gNMI Specification Section 3.5 66 rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeResponse); 67} 68 69// Notification is a re-usable message that is used to encode data from the 70// target to the client. A Notification carries two types of changes to the data 71// tree: 72// - Deleted values (delete) - a set of paths that have been removed from the 73// data tree. 74// - Updated values (update) - a set of path-value pairs indicating the path 75// whose value has changed in the data tree. 76// Reference: gNMI Specification Section 2.1 77message Notification { 78 int64 timestamp = 1; // Timestamp in nanoseconds since Epoch. 79 Path prefix = 2; // Prefix used for paths in the message. 80 // An alias for the path specified in the prefix field. 81 // Reference: gNMI Specification Section 2.4.2 82 string alias = 3; 83 repeated Update update = 4; // Data elements that have changed values. 84 repeated Path delete = 5; // Data elements that have been deleted. 85 // This notification contains a set of paths that are always updated together 86 // referenced by a globally unique prefix. 87 bool atomic = 6; 88} 89 90// Update is a re-usable message that is used to store a particular Path, 91// Value pair. 92// Reference: gNMI Specification Section 2.1 93message Update { 94 Path path = 1; // The path (key) for the update. 95 Value value = 2 [deprecated=true]; // The value (value) for the update. 96 TypedValue val = 3; // The explicitly typed update value. 97 uint32 duplicates = 4; // Number of coalesced duplicates. 98} 99 100// TypedValue is used to encode a value being sent between the client and 101// target (originated by either entity). 102message TypedValue { 103 // One of the fields within the val oneof is populated with the value 104 // of the update. The type of the value being included in the Update 105 // determines which field should be populated. In the case that the 106 // encoding is a particular form of the base protobuf type, a specific 107 // field is used to store the value (e.g., json_val). 108 oneof value { 109 string string_val = 1; // String value. 110 int64 int_val = 2; // Integer value. 111 uint64 uint_val = 3; // Unsigned integer value. 112 bool bool_val = 4; // Bool value. 113 bytes bytes_val = 5; // Arbitrary byte sequence value. 114 float float_val = 6; // Floating point value. 115 Decimal64 decimal_val = 7; // Decimal64 encoded value. 116 ScalarArray leaflist_val = 8; // Mixed type scalar array value. 117 google.protobuf.Any any_val = 9; // protobuf.Any encoded bytes. 118 bytes json_val = 10; // JSON-encoded text. 119 bytes json_ietf_val = 11; // JSON-encoded text per RFC7951. 120 string ascii_val = 12; // Arbitrary ASCII text. 121 // Protobuf binary encoded bytes. The message type is not included. 122 // See the specification at 123 // github.com/openconfig/reference/blob/master/rpc/gnmi/protobuf-vals.md 124 // for a complete specification. 125 bytes proto_bytes = 13; 126 } 127} 128 129// Path encodes a data tree path as a series of repeated strings, with 130// each element of the path representing a data tree node name and the 131// associated attributes. 132// Reference: gNMI Specification Section 2.2.2. 133message Path { 134 // Elements of the path are no longer encoded as a string, but rather within 135 // the elem field as a PathElem message. 136 repeated string element = 1 [deprecated=true]; 137 string origin = 2; // Label to disambiguate path. 138 repeated PathElem elem = 3; // Elements of the path. 139 string target = 4; // The name of the target 140 // (Sec. 2.2.2.1) 141} 142 143// PathElem encodes an element of a gNMI path, along with any attributes (keys) 144// that may be associated with it. 145// Reference: gNMI Specification Section 2.2.2. 146message PathElem { 147 string name = 1; // The name of the element in the path. 148 map<string, string> key = 2; // Map of key (attribute) name to value. 149} 150 151// Value encodes a data tree node's value - along with the way in which 152// the value is encoded. This message is deprecated by gNMI 0.3.0. 153// Reference: gNMI Specification Section 2.2.3. 154message Value { 155 option deprecated = true; 156 bytes value = 1; // Value of the variable being transmitted. 157 Encoding type = 2; // Encoding used for the value field. 158} 159 160// Encoding defines the value encoding formats that are supported by the gNMI 161// protocol. These encodings are used by both the client (when sending Set 162// messages to modify the state of the target) and the target when serializing 163// data to be returned to the client (in both Subscribe and Get RPCs). 164// Reference: gNMI Specification Section 2.3 165enum Encoding { 166 JSON = 0; // JSON encoded text. 167 BYTES = 1; // Arbitrarily encoded bytes. 168 PROTO = 2; // Encoded according to out-of-band agreed Protobuf. 169 ASCII = 3; // ASCII text of an out-of-band agreed format. 170 JSON_IETF = 4; // JSON encoded text as per RFC7951. 171} 172 173// Error message previously utilised to return errors to the client. Deprecated 174// in favour of using the google.golang.org/genproto/googleapis/rpc/status 175// message in the RPC response. 176// Reference: gNMI Specification Section 2.5 177message Error { 178 option deprecated = true; 179 uint32 code = 1; // Canonical gRPC error code. 180 string message = 2; // Human readable error. 181 google.protobuf.Any data = 3; // Optional additional information. 182} 183 184// Decimal64 is used to encode a fixed precision decimal number. The value 185// is expressed as a set of digits with the precision specifying the 186// number of digits following the decimal point in the digit set. 187message Decimal64 { 188 int64 digits = 1; // Set of digits. 189 uint32 precision = 2; // Number of digits following the decimal point. 190} 191 192// ScalarArray is used to encode a mixed-type array of values. 193message ScalarArray { 194 // The set of elements within the array. Each TypedValue message should 195 // specify only elements that have a field identifier of 1-7 (i.e., the 196 // values are scalar values). 197 repeated TypedValue element = 1; 198} 199 200// SubscribeRequest is the message sent by the client to the target when 201// initiating a subscription to a set of paths within the data tree. The 202// request field must be populated and the initial message must specify a 203// SubscriptionList to initiate a subscription. The message is subsequently 204// used to define aliases or trigger polled data to be sent by the target. 205// Reference: gNMI Specification Section 3.5.1.1 206message SubscribeRequest { 207 oneof request { 208 SubscriptionList subscribe = 1; // Specify the paths within a subscription. 209 Poll poll = 3; // Trigger a polled update. 210 AliasList aliases = 4; // Aliases to be created. 211 } 212 // Extension messages associated with the SubscribeRequest. See the 213 // gNMI extension specification for further definition. 214 repeated gnmi_ext.Extension extension = 5; 215} 216 217// Poll is sent within a SubscribeRequest to trigger the device to 218// send telemetry updates for the paths that are associated with the 219// subscription. 220// Reference: gNMI Specification Section Section 3.5.1.4 221message Poll { 222} 223 224// SubscribeResponse is the message used by the target within a Subscribe RPC. 225// The target includes a Notification message which is used to transmit values 226// of the path(s) that are associated with the subscription. The same message 227// is to indicate that the target has sent all data values once (is 228// synchronized). 229// Reference: gNMI Specification Section 3.5.1.4 230message SubscribeResponse { 231 oneof response { 232 Notification update = 1; // Changed or sampled value for a path. 233 // Indicate target has sent all values associated with the subscription 234 // at least once. 235 bool sync_response = 3; 236 // Deprecated in favour of google.golang.org/genproto/googleapis/rpc/status 237 Error error = 4 [deprecated=true]; 238 } 239 // Extension messages associated with the SubscribeResponse. See the 240 // gNMI extension specification for further definition. 241 repeated gnmi_ext.Extension extension = 5; 242} 243 244// SubscriptionList is used within a Subscribe message to specify the list of 245// paths that the client wishes to subscribe to. The message consists of a 246// list of (possibly prefixed) paths, and options that relate to the 247// subscription. 248// Reference: gNMI Specification Section 3.5.1.2 249message SubscriptionList { 250 Path prefix = 1; // Prefix used for paths. 251 repeated Subscription subscription = 2; // Set of subscriptions to create. 252 // Whether target defined aliases are allowed within the subscription. 253 bool use_aliases = 3; 254 QOSMarking qos = 4; // DSCP marking to be used. 255 // Mode of the subscription. 256 enum Mode { 257 STREAM = 0; // Values streamed by the target (Sec. 3.5.1.5.2). 258 ONCE = 1; // Values sent once-off by the target (Sec. 3.5.1.5.1). 259 POLL = 2; // Values sent in response to a poll request (Sec. 3.5.1.5.3). 260 } 261 Mode mode = 5; 262 // Whether elements of the schema that are marked as eligible for aggregation 263 // should be aggregated or not. 264 bool allow_aggregation = 6; 265 // The set of schemas that define the elements of the data tree that should 266 // be sent by the target. 267 repeated ModelData use_models = 7; 268 // The encoding that the target should use within the Notifications generated 269 // corresponding to the SubscriptionList. 270 Encoding encoding = 8; 271 // An optional field to specify that only updates to current state should be 272 // sent to a client. If set, the initial state is not sent to the client but 273 // rather only the sync message followed by any subsequent updates to the 274 // current state. For ONCE and POLL modes, this causes the server to send only 275 // the sync message (Sec. 3.5.2.3). 276 bool updates_only = 9; 277} 278 279// Subscription is a single request within a SubscriptionList. The path 280// specified is interpreted (along with the prefix) as the elements of the data 281// tree that the client is subscribing to. The mode determines how the target 282// should trigger updates to be sent. 283// Reference: gNMI Specification Section 3.5.1.3 284message Subscription { 285 Path path = 1; // The data tree path. 286 SubscriptionMode mode = 2; // Subscription mode to be used. 287 uint64 sample_interval = 3; // ns between samples in SAMPLE mode. 288 // Indicates whether values that have not changed should be sent in a SAMPLE 289 // subscription. 290 bool suppress_redundant = 4; 291 // Specifies the maximum allowable silent period in nanoseconds when 292 // suppress_redundant is in use. The target should send a value at least once 293 // in the period specified. 294 uint64 heartbeat_interval = 5; 295} 296 297// SubscriptionMode is the mode of the subscription, specifying how the 298// target must return values in a subscription. 299// Reference: gNMI Specification Section 3.5.1.3 300enum SubscriptionMode { 301 TARGET_DEFINED = 0; // The target selects the relevant mode for each element. 302 ON_CHANGE = 1; // The target sends an update on element value change. 303 SAMPLE = 2; // The target samples values according to the interval. 304} 305 306// QOSMarking specifies the DSCP value to be set on transmitted telemetry 307// updates from the target. 308// Reference: gNMI Specification Section 3.5.1.2 309message QOSMarking { 310 uint32 marking = 1; 311} 312 313// Alias specifies a data tree path, and an associated string which defines an 314// alias which is to be used for this path in the context of the RPC. The alias 315// is specified as a string which is prefixed with "#" to disambiguate it from 316// data tree element paths. 317// Reference: gNMI Specification Section 2.4.2 318message Alias { 319 Path path = 1; // The path to be aliased. 320 string alias = 2; // The alias value, a string prefixed by "#". 321} 322 323// AliasList specifies a list of aliases. It is used in a SubscribeRequest for 324// a client to create a set of aliases that the target is to utilize. 325// Reference: gNMI Specification Section 3.5.1.6 326message AliasList { 327 repeated Alias alias = 1; // The set of aliases to be created. 328} 329 330// SetRequest is sent from a client to the target to update values in the data 331// tree. Paths are either deleted by the client, or modified by means of being 332// updated, or replaced. Where a replace is used, unspecified values are 333// considered to be replaced, whereas when update is used the changes are 334// considered to be incremental. The set of changes that are specified within 335// a single SetRequest are considered to be a transaction. 336// Reference: gNMI Specification Section 3.4.1 337message SetRequest { 338 Path prefix = 1; // Prefix used for paths in the message. 339 repeated Path delete = 2; // Paths to be deleted from the data tree. 340 repeated Update replace = 3; // Updates specifying elements to be replaced. 341 repeated Update update = 4; // Updates specifying elements to updated. 342 // Extension messages associated with the SetRequest. See the 343 // gNMI extension specification for further definition. 344 repeated gnmi_ext.Extension extension = 5; 345} 346 347// SetResponse is the response to a SetRequest, sent from the target to the 348// client. It reports the result of the modifications to the data tree that were 349// specified by the client. Errors for this RPC should be reported using the 350// https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto 351// message in the RPC return. The gnmi.Error message can be used to add additional 352// details where required. 353// Reference: gNMI Specification Section 3.4.2 354message SetResponse { 355 Path prefix = 1; // Prefix used for paths. 356 // A set of responses specifying the result of the operations specified in 357 // the SetRequest. 358 repeated UpdateResult response = 2; 359 Error message = 3 [deprecated=true]; // The overall status of the transaction. 360 int64 timestamp = 4; // Timestamp of transaction (ns since epoch). 361 // Extension messages associated with the SetResponse. See the 362 // gNMI extension specification for further definition. 363 repeated gnmi_ext.Extension extension = 5; 364} 365 366// UpdateResult is used within the SetResponse message to communicate the 367// result of an operation specified within a SetRequest message. 368// Reference: gNMI Specification Section 3.4.2 369message UpdateResult { 370 // The operation that was associated with the Path specified. 371 enum Operation { 372 INVALID = 0; 373 DELETE = 1; // The result relates to a delete of Path. 374 REPLACE = 2; // The result relates to a replace of Path. 375 UPDATE = 3; // The result relates to an update of Path. 376 } 377 // Deprecated timestamp for the UpdateResult, this field has been 378 // replaced by the timestamp within the SetResponse message, since 379 // all mutations effected by a set should be applied as a single 380 // transaction. 381 int64 timestamp = 1 [deprecated=true]; 382 Path path = 2; // Path associated with the update. 383 Error message = 3 [deprecated=true]; // Status of the update operation. 384 Operation op = 4; // Update operation type. 385} 386 387// GetRequest is sent when a client initiates a Get RPC. It is used to specify 388// the set of data elements for which the target should return a snapshot of 389// data. The use_models field specifies the set of schema modules that are to 390// be used by the target - where use_models is not specified then the target 391// must use all schema models that it has. 392// Reference: gNMI Specification Section 3.3.1 393message GetRequest { 394 Path prefix = 1; // Prefix used for paths. 395 repeated Path path = 2; // Paths requested by the client. 396 // Type of elements within the data tree. 397 enum DataType { 398 ALL = 0; // All data elements. 399 CONFIG = 1; // Config (rw) only elements. 400 STATE = 2; // State (ro) only elements. 401 // Data elements marked in the schema as operational. This refers to data 402 // elements whose value relates to the state of processes or interactions 403 // running on the device. 404 OPERATIONAL = 3; 405 } 406 DataType type = 3; // The type of data being requested. 407 Encoding encoding = 5; // Encoding to be used. 408 repeated ModelData use_models = 6; // The schema models to be used. 409 // Extension messages associated with the GetRequest. See the 410 // gNMI extension specification for further definition. 411 repeated gnmi_ext.Extension extension = 7; 412} 413 414// GetResponse is used by the target to respond to a GetRequest from a client. 415// The set of Notifications corresponds to the data values that are requested 416// by the client in the GetRequest. 417// Reference: gNMI Specification Section 3.3.2 418message GetResponse { 419 repeated Notification notification = 1; // Data values. 420 Error error = 2 [deprecated=true]; // Errors that occurred in the Get. 421 // Extension messages associated with the GetResponse. See the 422 // gNMI extension specification for further definition. 423 repeated gnmi_ext.Extension extension = 3; 424} 425 426// CapabilityRequest is sent by the client in the Capabilities RPC to request 427// that the target reports its capabilities. 428// Reference: gNMI Specification Section 3.2.1 429message CapabilityRequest { 430 // Extension messages associated with the CapabilityRequest. See the 431 // gNMI extension specification for further definition. 432 repeated gnmi_ext.Extension extension = 1; 433} 434 435// CapabilityResponse is used by the target to report its capabilities to the 436// client within the Capabilities RPC. 437// Reference: gNMI Specification Section 3.2.2 438message CapabilityResponse { 439 repeated ModelData supported_models = 1; // Supported schema models. 440 repeated Encoding supported_encodings = 2; // Supported encodings. 441 string gNMI_version = 3; // Supported gNMI version. 442 // Extension messages associated with the CapabilityResponse. See the 443 // gNMI extension specification for further definition. 444 repeated gnmi_ext.Extension extension = 4; 445} 446 447// ModelData is used to describe a set of schema modules. It can be used in a 448// CapabilityResponse where a target reports the set of modules that it 449// supports, and within the SubscribeRequest and GetRequest messages to specify 450// the set of models from which data tree elements should be reported. 451// Reference: gNMI Specification Section 3.2.3 452message ModelData { 453 string name = 1; // Name of the model. 454 string organization = 2; // Organization publishing the model. 455 string version = 3; // Semantic version of the model. 456} 457