system
services
System

The gNOI service is a collection of operational RPC's that allow for the
management of a target outside of the configuration and telemetry pipeline.

Method Name Request / Response Type Description
Ping PingRequest
PingResponse

Ping executes the ping command on the target and streams back
the results. Some targets may not stream any results until all
results are in. The stream should provide single ping packet responses
and must provide summary statistics.
Traceroute TracerouteRequest
TracerouteResponse

Traceroute executes the traceroute command on the target and streams back
the results. Some targets may not stream any results until all
results are in. If a hop count is not explicitly provided,
30 is used.
Time TimeRequest
TimeResponse

Time returns the current time on the target. Time is typically used to
test if a target is actually responding.
SetPackage SetPackageRequest stream
SetPackageResponse stream

SetPackage places a software package (possibly including bootable images)
on the target. The file is sent in sequential messages, each message
up to 64KB of data. A final message must be sent that includes the hash
of the data sent. An error is returned if the location does not exist or
there is an error writing the data. If no checksum is received, the target
must assume the operation is incomplete and remove the partially
transmitted file. The target should initially write the file to a temporary
location so a failure does not destroy the original file.
SwitchControlProcessor SwitchControlProcessorRequest
SwitchControlProcessorResponse

SwitchControlProcessor will switch from the current route processor to the
provided route processor. If the current route processor is the same as the
one provided it is a NOOP. If the target does not exist an error is
returned.
Reboot RebootRequest
RebootResponse

Reboot causes the target to reboot, possibly at some point in the future.
If the method of reboot is not supported then the Reboot RPC will fail.
If the reboot is immediate the command will block until the subcomponents
have restarted.
If a reboot on the active control processor is pending the service must
reject all other reboot requests.
If a reboot request for active control processor is initiated with other
pending reboot requests it must be rejected.
RebootStatus RebootStatusRequest
RebootStatusResponse

RebootStatus returns the status of reboot for the target.
CancelReboot CancelRebootRequest
CancelRebootResponse

CancelReboot cancels any pending reboot request.
KillProcess KillProcessRequest
KillProcessResponse

KillProcess kills an OS process and optionally restarts it.
messages
CancelRebootRequest

A CancelRebootRequest requests the cancelation of any outstanding reboot
request.

Field Type Description
message string

informational reason for the cancel

subcomponents (repeated) gnoi.types.Path

optional sub-components.

CancelRebootResponse

Empty message

KillProcessRequest

KillProcessRequest describes the process kill operation. Either a pid or
process name must be specified, and a termination signal must be specified.

Field Type Description
pid uint32

Process ID of the process to be killed.

name string

Name of the process to be killed.

signal KillProcessRequest.Signal

restart bool

Whether the process should be restarted after termination.
This value is ignored when the termination signal is SIGHUP.

KillProcessResponse

KillProcessResponse describes the result of the process kill operation.

Empty message

Package

Package defines a single package file to be placed on the target.

Field Type Description
filename string

Destination path and filename of the package.

version string

Version of the package. (vendor internal name)

activate bool

Indicates that the package should be made active after receipt on
the device. For system image packages, the new image is expected to
be active after a reboot.

remote_download gnoi.common.RemoteDownload

Details for the device to download the package from a remote location.

PingRequest

A PingRequest describes the ping operation to perform. Only the destination
fields is required. Any field not specified is set to a reasonable server
specified value. Not all fields are supported by all vendors.

A count of 0 defaults to a vendor specified value, typically 5. A count of
-1 means continue until the RPC times out or is canceled.

If the interval is -1 then a flood ping is issued.

If the size is 0, the vendor default size will be used (typically 56 bytes).

Field Type Description
destination string

Destination address to ping. required.

source string

Source address to ping from.

count int32

Number of packets.

interval int64

Nanoseconds between requests.

wait int64

Nanoseconds to wait for a response.

size int32

Size of request packet. (excluding ICMP header)

do_not_fragment bool

Set the do not fragment bit. (IPv4 destinations)

do_not_resolve bool

Do not try resolve the address returned.

l3protocol gnoi.types.L3Protocol

Layer3 protocol requested for the ping.

PingResponse

A PingResponse represents either the reponse to a single ping packet
(the bytes field is non-zero) or the summary statistics (sent is non-zero).

For a single ping packet, time is the round trip time, in nanoseconds. For
summary statistics, it is the time spent by the ping operation. The time is
not always present in summary statistics. The std_dev is not always present
in summary statistics.

Field Type Description
source string

Source of received bytes.

time int64

sent int32

Total packets sent.

received int32

Total packets received.

min_time int64

Minimum round trip time in nanoseconds.

avg_time int64

Average round trip time in nanoseconds.

max_time int64

Maximum round trip time in nanoseconds.

std_dev int64

Standard deviation in round trip time.

bytes int32

Bytes received.

sequence int32

Sequence number of received packet.

ttl int32

Remaining time to live value.

RebootRequest

A RebootRequest requests the specified target be rebooted using the specified
method after the specified delay. Only the DEFAULT method with a delay of 0
is guaranteed to be accepted for all target types.

Field Type Description
method RebootMethod

delay uint64

Delay in nanoseconds before issuing reboot.

message string

Informational reason for the reboot.

subcomponents (repeated) gnoi.types.Path

Optional sub-components to reboot.

force bool

Force reboot if sanity checks fail. (ex. uncommited configuration)

RebootResponse

Empty message

RebootStatusRequest
Field Type Description
subcomponents (repeated) gnoi.types.Path

optional sub-component.

RebootStatusResponse
Field Type Description
active bool

If reboot is active.

wait uint64

Time left until reboot.

when uint64

Time to reboot in nanoseconds since the epoch.

reason string

Reason for reboot.

count uint32

Number of reboots since active.

SetPackageRequest

SetPackageRequest will place the package onto the target and optionally mark
it as the next bootable image. The initial message must be a package
message containing the filename and information about the file. Following the
initial message the contents are then streamed in maximum 64k chunks. The
final message must be a hash message contains the hash of the file contents.

Field Type Description
request (one of)
package Package

contents bytes

hash gnoi.types.HashType

Verification hash of data.

SetPackageResponse

Empty message

SwitchControlProcessorRequest
Field Type Description
control_processor gnoi.types.Path

SwitchControlProcessorResponse
Field Type Description
control_processor gnoi.types.Path

version string

Current software version.

uptime int64

Uptime in nanoseconds since epoch.

TimeRequest

A TimeRequest requests the current time accodring to the target.

Empty message

TimeResponse
Field Type Description
time uint64

Current time in nanoseconds since epoch.

TracerouteRequest

A TracerouteRequest describes the traceroute operation to perform. Only the
destination field is required. Any field not specified is set to a
reasonable server specified value. Not all fields are supported by all
vendors.

If the hop_count is -1 the traceroute will continue forever.

Field Type Description
source string

Source address to ping from.

destination string

Destination address to ping.

initial_ttl uint32

Initial TTL. (default=1)

max_ttl int32

Maximum number of hops. (default=30)

wait int64

Nanoseconds to wait for a response.

do_not_fragment bool

Set the do not fragment bit. (IPv4 destinations)

do_not_resolve bool

Do not try resolve the address returned.

l3protocol gnoi.types.L3Protocol

Layer-3 protocol requested for the ping.

l4protocol TracerouteRequest.L4Protocol

do_not_lookup_asn bool

Do not try to lookup ASN

TracerouteResponse

A TraceRouteResponse contains the result of a single traceoute packet.

There may be an optional initial response that provides information about the
traceroute request itself and contains at least one of the fields in the the
initial block of fields and none of the fields following that block. All
subsequent responses should not contain any of these fields.

Typically multiple responses are received for each hop, as the packets are
received.

The mpls field maps names to values. Example names include "Label", "CoS",
"TTL", "S", and "MRU".
[Perhaps we should list the canonical names that must be used when
applicable].

Field Type Description
destination_name string

The following fields are only filled in for the first message.
If any of these fields are specified, all fields following this
block are left unspecified.

destination_address string

hops int32

packet_size int32

hop int32

The following fields provide the disposition of a single traceroute
packet.

Hop number. required.

address string

Address of responding hop. required.

name string

Name of responding hop.

rtt int64

Round trip time in nanoseconds.

state TracerouteResponse.State

State of this hop.

icmp_code int32

Code terminating hop.

mpls (repeated) TracerouteResponse.MplsEntry

MPLS key/value pairs.

as_path (repeated) int32

AS path.

TracerouteResponse.MplsEntry
Field Type Description
key string

value string

enums
KillProcessRequest.Signal

Termination signal sent to the process.

Name Number Description
SIGNAL_UNSPECIFIED 0

Invalid default.
SIGNAL_TERM 1

Terminate the process gracefully.
SIGNAL_KILL 2

Terminate the process immediately.
SIGNAL_HUP 3

Reload the process configuration.
SIGNAL_ABRT 4

Terminate the process immediately and dump a core file.
RebootMethod

A RebootMethod determines what should be done with a target when a Reboot is
requested. Only the COLD method is required to be supported by all
targets. Methods the target does not support should result in failure.

It is vendor defined if a WARM reboot is the same as an NSF reboot.

Name Number Description
UNKNOWN 0

Invalid default method.
COLD 1

Shutdown and restart OS and all hardware.
POWERDOWN 2

Halt and power down, if possible.
HALT 3

Halt, if possible.
WARM 4

Reload configuration but not underlying hardware.
NSF 5

Non-stop-forwarding reboot, if possible.
POWERUP 7

Apply power, no-op if power is already on.
TracerouteRequest.L4Protocol
Name Number Description
ICMP 0

Use ICMP ECHO for probes.
TCP 1

Use TCP SYN for probes.
UDP 2

Use UDP for probes.
TracerouteResponse.State

State is the resulting state of a single traceoroute packet.

Name Number Description
DEFAULT 0

Normal hop response.
NONE 1

No response.
UNKNOWN 2

Unknown response state.
ICMP 3

See icmp_code field.
HOST_UNREACHABLE 4

Host unreachable.
NETWORK_UNREACHABLE 5

Network unreachable.
PROTOCOL_UNREACHABLE 6

Protocol unreachable.
SOURCE_ROUTE_FAILED 7

Source route failed.
FRAGMENTATION_NEEDED 8

Fragmentation needed.
PROHIBITED 9

Communication administratively prohibited.
PRECEDENCE_VIOLATION 10

Host precedence violation.
PRECEDENCE_CUTOFF 11

Precedence cutoff in effect.
common
messages
RemoteDownload

RemoteDownload defines the details for a device to initiate a file transfer
from or to a remote location.

Field Type Description
path string

The path information containing where to download the data from or to.
For HTTP(S), this will be the URL (i.e. foo.com/file.tbz2).
For SFTP and SCP, this will be the address:/path/to/file
(i.e. host.foo.com:/bar/baz).

protocol RemoteDownload.Protocol

credentials gnoi.types.Credentials

source_address string

Optional source address used to initiate connections from the device.
It can be either an IPv4 address or an IPv6 address, depending on the
connection's destination address.

types
messages
Credentials

Credentials defines credentials needed to perform authentication on a device.

Field Type Description
username string

password (one of)
cleartext string

hashed HashType

HashType

HashType defines the valid hash methods for data verification. UNSPECIFIED
should be treated an error.

Field Type Description
method HashType.HashMethod

hash bytes

Path

Path encodes a data tree path as a series of repeated strings, with
each element of the path representing a data tree node name and the
associated attributes.
Reference: gNMI Specification Section 2.2.2.

Field Type Description
origin string

Label to disambiguate path.

elem (repeated) PathElem

Elements of the path.

PathElem

PathElem encodes an element of a gNMI path, along with any attributes (keys)
that may be associated with it.
Reference: gNMI Specification Section 2.2.2.

Field Type Description
name string

The name of the element in the path.

key (repeated) PathElem.KeyEntry

Map of key (attribute) name to value.

PathElem.KeyEntry
Field Type Description
key string

value string

enums
HashType.HashMethod
Name Number Description
UNSPECIFIED 0

SHA256 1

SHA512 2

MD5 3

L3Protocol

Generic Layer 3 Protocol enumeration.

Name Number Description
UNSPECIFIED 0

IPV4 1

IPV6 2

extensions
.google.protobuf.FileOptions.gnoi_version

The gNOI service semantic version.

Extension Type Base Number Description
gnoi_version string .google.protobuf.FileOptions 1002

The gNOI service semantic version.

Scalar Value Types
Proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Created by Siva Sivakumar / Roman Dodin / srl-labs