Protocol Documentation
Table of Contents
api/admin/admin.proto
Chunk
Chunk is for streaming a model plugin file to the server. There is a built in limit in gRPC of 4MB - plugin is usually around 20MB so break in to chunks of approx 1-2MB.
| Field | Type | Label | Description |
|---|---|---|---|
| so_file | string | so_file is the name being streamed. | |
| content | bytes | content is the bytes content. |
CompactChangesRequest
CompactChangesRequest requests a compaction of the Network Change and Device Change stores
| Field | Type | Label | Description |
|---|---|---|---|
| retention_period | google.protobuf.Duration | retention_period is an optional duration of time counting back from the present moment Network changes that were created during this period should not be compacted Any network changes that are older should be compacted If not specified the duration is 0 |
CompactChangesResponse
CompactChangesResponse is a response to the Compact Changes command
ListModelsRequest
ListModelsRequest carries data for querying registered model plugins.
| Field | Type | Label | Description |
|---|---|---|---|
| verbose | bool | verbose option causes all of the ReadWrite and ReadOnly paths to be included. | |
| model_name | string | An optional filter on the name of the model plugins to list. | |
| model_version | string | An optional filter on the version of the model plugins to list |
ListSnapshotsRequest
ListSnapshotsRequest requests a list of snapshots for all devices and versions.
| Field | Type | Label | Description |
|---|---|---|---|
| subscribe | bool | subscribe indicates whether to subscribe to events (e.g. ADD, UPDATE, and REMOVE) that occur after all devices have been streamed to the client | |
| id | string | option to specify a specific device - if blank or '*' then select all Can support * (match many chars) or '?' (match one char) as wildcard |
ModelInfo
ModelInfo is general information about a model plugin.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | name is the name given to the model plugin - no spaces and title case. | |
| version | string | version is the semantic version of the Plugin e.g. 1.0.0. | |
| model_data | gnmi.ModelData | repeated | model_data is a set of metadata about the YANG files that went in to generating the model plugin. It includes name, version and organization for each YANG file, similar to how they are represented in gNMI Capabilities. |
| module | string | module is the name of the Model Plugin on the file system - usually ending in .so.<version>. | |
| getStateMode | uint32 | getStateMode is flag that defines how the "get state" operation works. 0) means that no retrieval of state is attempted 1) means that the synchronizer will make 2 requests to the device - one for Get with State and another for Get with Operational. 2) means that the synchronizer will do a Get request comprising of each one of the ReadOnlyPaths and their sub paths. If there is a list in any one of these paths it will be sent down as is, expecting the devices implementation of gNMI will be able to expand wildcards. 3) means that the synchronizer will do a Get request comprising of each one of the ReadOnlyPaths and their sub paths. If there is a list in any one of these paths, a separate call will be made first to find all the instances in the list and a Get including these expanded wildcards will be sent down to the device. | |
| read_only_path | ReadOnlyPath | repeated | read_only_path is all of the read only paths for the model plugin. |
| read_write_path | ReadWritePath | repeated | read_write_path is all of the read write paths for the model plugin. |
ReadOnlyPath
ReadOnlyPath extracted from the model plugin as the definition of a tree of read only items. In YANG models items are defined as ReadOnly with the config false keyword. This can be applied to single items (leafs) or collections (containers or lists). When this config false is applied to an object every item beneath it will also become readonly - here these are shown as subpaths. The complete read only path then will be a concatenation of both e.g. /cont1a/cont1b-state/list2b/index and the type is defined in the SubPath as UInt8.
| Field | Type | Label | Description |
|---|---|---|---|
| path | string | path of the topmost config false object e.g. /cont1a/cont1b-state | |
| sub_path | ReadOnlySubPath | repeated | ReadOnlySubPath is a set of children of the path including an entry for the type of the topmost object with subpath / An example is /list2b/index |
ReadOnlySubPath
ReadOnlySubPath is an extension to the ReadOnlyPath to define the datatype of the subpath
| Field | Type | Label | Description |
|---|---|---|---|
| sub_path | string | sub_path is the relative path of a child object e.g. /list2b/index | |
| value_type | onos.config.change.device.ValueType | value_type is the datatype of the read only path |
ReadWritePath
ReadWritePath is extracted from the model plugin as the definition of a writeable attributes. In YANG models items are writable by default unless they are specified as config false or have an item with config false as a parent. Each configurable item has metadata with meanings taken from the YANG specification RFC 6020.
| Field | Type | Label | Description |
|---|---|---|---|
| path | string | path is the full path to the attribute (leaf or leaf-list) | |
| value_type | onos.config.change.device.ValueType | value_type is the data type of the attribute | |
| units | string | units is the unit of measurement e.g. dB, mV | |
| description | string | description is an explaination of the meaning of the attribute | |
| mandatory | bool | mandatory shows whether the attribute is optional (false) or required (true) | |
| default | string | default is a default value used with optional attributes | |
| range | string | repeated | range is definition of the range of values a value is allowed |
| length | string | repeated | length is a defintion of the length restrictions for the attribute |
RegisterResponse
RegisterResponse carries status of model plugin registration.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | name is name of the model plugin. | |
| version | string | version is the semantic version of the model plugin. |
RollbackRequest
RollbackRequest carries the name of a network config to rollback. If there are subsequent changes to any of the devices in that config, the rollback will be rejected.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | name is an optional name of a Network Change to rollback. If no name is given the last network change will be rolled back. If the name given is not of the last network change and error will be given. | |
| comment | string | On optional comment to leave on the rollback. |
RollbackResponse
RollbackResponse carries the response of the rollback operation
| Field | Type | Label | Description |
|---|---|---|---|
| message | string | A message showing the result of the rollback. |
Type
Streaming event type
| Name | Number | Description |
|---|---|---|
| NONE | 0 | NONE indicates this response does not represent a state change |
| ADDED | 1 | ADDED is an event which occurs when an item is added |
| UPDATED | 2 | UPDATED is an event which occurs when an item is updated |
| REMOVED | 3 | REMOVED is an event which occurs when an item is removed |
ConfigAdminService
ConfigAdminService provides means for enhanced interactions with the configuration subsystem.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| UploadRegisterModel | Chunk stream | RegisterResponse | UploadRegisterModel uploads and adds the model plugin to the list of supported models. The file is serialized in to Chunks of less than 4MB so as not to break the gRPC byte array limit |
| ListRegisteredModels | ListModelsRequest | ModelInfo stream | ListRegisteredModels returns a stream of registered models. |
| RollbackNetworkChange | RollbackRequest | RollbackResponse | RollbackNetworkChange rolls back the specified network change (or the latest one). |
| ListSnapshots | ListSnapshotsRequest | .onos.config.snapshot.device.Snapshot stream | ListSnapshots gets a list of snapshots across all devices and versions, and streams them back to the caller. |
| CompactChanges | CompactChangesRequest | CompactChangesResponse | CompactChanges requests a snapshot of NetworkChange and DeviceChange stores. This will take all of the Network Changes older than the retention period and flatten them down to just one snapshot (replacing any older snapshot). This will act as a baseline for those changes within the retention period and any future changes. DeviceChanges will be snapshotted to correspond to these NetworkChange compactions leaving an individual snapshot perv device and version combination. |