package gnoi.system

Get desktop application:
View/edit binary Protocol Buffers messages

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.

• rpc Ping (PingRequest, stream PingResponse)

  system.proto:41

  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.

  message PingRequest

  system.proto:194

  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).

  • string destination = 1

    Destination address to ping. required.

  • string source = 2

    Source address to ping from.

  • int32 count = 3

    Number of packets.

  • int64 interval = 4

    Nanoseconds between requests.

  • int64 wait = 5

    Nanoseconds to wait for a response.

  • int32 size = 6

    Size of request packet. (excluding ICMP header)

  • bool do_not_fragment = 7

    Set the do not fragment bit. (IPv4 destinations)

  • bool do_not_resolve = 8

    Do not try resolve the address returned.

  • types.L3Protocol l3protocol = 9

    Layer3 protocol requested for the ping.

  • string network_instance = 10

    Network instance to ping the destination in

  message PingResponse

  system.proto:214

  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.

  • string source = 1

    Source of received bytes.

  • int64 time = 2

  • int32 sent = 3

    Total packets sent.

  • int32 received = 4

    Total packets received.

  • int64 min_time = 5

    Minimum round trip time in nanoseconds.

  • int64 avg_time = 6

    Average round trip time in nanoseconds.

  • int64 max_time = 7

    Maximum round trip time in nanoseconds.

  • int64 std_dev = 8

    Standard deviation in round trip time.

  • int32 bytes = 11

    Bytes received.

  • int32 sequence = 12

    Sequence number of received packet.

  • int32 ttl = 13

    Remaining time to live value.

• rpc Traceroute (TracerouteRequest, stream TracerouteResponse)

  system.proto:47

  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.

  message TracerouteRequest

  system.proto:237

  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.

  • string source = 1

    Source address to ping from.

  • string destination = 2

    Destination address to ping.

  • uint32 initial_ttl = 3

    Initial TTL. (default=1)

  • int32 max_ttl = 4

    Maximum number of hops. (default=30)

  • int64 wait = 5

    Nanoseconds to wait for a response.

  • bool do_not_fragment = 6

    Set the do not fragment bit. (IPv4 destinations)

  • bool do_not_resolve = 7

    Do not try resolve the address returned.

  • types.L3Protocol l3protocol = 8

    Layer-3 protocol requested for the ping.

  • TracerouteRequest.L4Protocol l4protocol = 9

  • bool do_not_lookup_asn = 10

    Do not try to lookup ASN

  • string network_instance = 11

    Network instance to trace the destination in

  message TracerouteResponse

  system.proto:270

  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].

  • string destination_name = 1

    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.

  • string destination_address = 2

  • int32 hops = 3

  • int32 packet_size = 4

  • int32 hop = 5

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

    Hop number. required.

  • string address = 6

    Address of responding hop. required.

  • string name = 7

    Name of responding hop.

  • int64 rtt = 8

    Round trip time in nanoseconds.

  • TracerouteResponse.State state = 9

    State of this hop.

  • int32 icmp_code = 10

    Code terminating hop.

  • map<string, string> mpls = 11

    MPLS key/value pairs.

  • repeated int32 as_path = 12

    AS path.

  • repeated TracerouteResponse.IcmpExtData icmp_ext_data = 13

    ICMP extension data

• rpc Time (TimeRequest, TimeResponse)

  system.proto:51

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

  message TimeRequest

  system.proto:177

  A TimeRequest requests the current time accodring to the target.

  (message has no fields)

  message TimeResponse

  system.proto:180

  • uint64 time = 1

    Current time in nanoseconds since epoch.

• rpc SetPackage (stream SetPackageRequest, SetPackageResponse)

  system.proto:61

  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.

  message SetPackageRequest

  system.proto:333

  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.

  • oneof request

    • Package package = 1

    • bytes contents = 2

    • types.HashType hash = 3

      Verification hash of data.

  message SetPackageResponse

  system.proto:341

  (message has no fields)

• rpc SwitchControlProcessor (SwitchControlProcessorRequest, SwitchControlProcessorResponse)

  system.proto:67

  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.

  message SwitchControlProcessorRequest

  system.proto:90

  • optional types.Path control_processor = 1

    Path to the target Control Processor.

  message SwitchControlProcessorResponse

  system.proto:95

  • optional types.Path control_processor = 1

    Path to the Control Processor that the system switched to.

  • string version = 2

    Current software version of the target Control Processor.

  • int64 uptime = 3

    Uptime of the target Control Processor in nanoseconds.

• rpc Reboot (RebootRequest, RebootResponse)

  system.proto:78

  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.

  message RebootRequest

  system.proto:107

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

  • RebootMethod method = 1

  • uint64 delay = 2

    Delay in nanoseconds before issuing reboot.

  • string message = 3

    Informational reason for the reboot.

  • repeated types.Path subcomponents = 4

    Optional sub-components to reboot.

  • bool force = 5

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

  message RebootResponse

  system.proto:119

  (message has no fields)

• rpc RebootStatus (RebootStatusRequest, RebootStatusResponse)

  system.proto:81

  RebootStatus returns the status of reboot for the target.

  message RebootStatusRequest

  system.proto:150

  • repeated types.Path subcomponents = 1

    optional sub-component.

  message RebootStatusResponse

  system.proto:154

  • bool active = 1

    If reboot is active.

  • uint64 wait = 2

    Time left until reboot.

  • uint64 when = 3

    Time to reboot in nanoseconds since the epoch.

  • string reason = 4

    Reason for reboot.

  • uint32 count = 5

    Number of reboots since active.

  • RebootMethod method = 6

    Type of reboot.

  • optional RebootStatus status = 7

    Applicable only when active = false.

• rpc CancelReboot (CancelRebootRequest, CancelRebootResponse)

  system.proto:84

  CancelReboot cancels any pending reboot request.

  message CancelRebootRequest

  system.proto:142

  A CancelRebootRequest requests the cancelation of any outstanding reboot request.

  • string message = 1

    informational reason for the cancel

  • repeated types.Path subcomponents = 2

    optional sub-components.

  message CancelRebootResponse

  system.proto:147

  (message has no fields)

• rpc KillProcess (KillProcessRequest, KillProcessResponse)

  system.proto:87

  KillProcess kills an OS process and optionally restarts it.

  message KillProcessRequest

  system.proto:346

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

  • uint32 pid = 1

    Process ID of the process to be killed.

  • string name = 2

    Name of the process to be killed.

  • KillProcessRequest.Signal signal = 3

  • bool restart = 4

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

  message KillProcessResponse

  system.proto:368

  KillProcessResponse describes the result of the process kill operation.

  (message has no fields)

Termination signal sent to the process.

Used in: KillProcessRequest

• 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.

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

Used in: SetPackageRequest

• string filename = 1

  Destination path and filename of the package.

• string version = 4

  Version of the package. (vendor internal name)

• bool activate = 5

  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.

• optional common.RemoteDownload remote_download = 6

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

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. A target should return 'INVALID_ARGUMENT` if UNKNOWN or any other unsupported method is called. It is vendor defined if a WARM reboot is the same as an NSF reboot.

Used in: RebootRequest, RebootStatusResponse

• 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.

Used in: RebootStatusResponse

• RebootStatus.Status status = 1

• string message = 2

Used in: RebootStatus

• STATUS_UNKNOWN = 0

• STATUS_SUCCESS = 1

• STATUS_RETRIABLE_FAILURE = 2

• STATUS_FAILURE = 3

Used in: TracerouteRequest

• ICMP = 0

  Use ICMP ECHO for probes.

• TCP = 1

  Use TCP SYN for probes.

• UDP = 2

  Use UDP for probes.

Used in: TracerouteResponse

• uint32 class = 1

  class number

• uint32 type = 2

  class type

• repeated uint32 data = 3

  raw words associated with this data

State is the resulting state of a single traceoroute packet.

Used in: TracerouteResponse

• 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.