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