gNOI

The Install RPC transfers the OS package to the target node. The target node first attempts to copy the specified OS package between the CPMs before it accepts the transfer from the client.

To refer to the OS version, SR Linux uses the same string in gNOI as the one used with ZTP (version string-build number) , for example: v22.11.1-010. The download folder for the OS is located at: /var/run/srlinux/gnoi. To validate that the transferred OS package is valid and bootable before installation, the platform performs a hash check against the md5sum that is embedded in the .bin file.

One Install RPC is required for each CPM. Concurrent Install RPCs are not allowed on the same target node.

 rpc Install(stream InstallRequest) returns (stream InstallResponse);

The Activate RPC sets the requested OS version for the target node to use at the next reboot. It also reboots the target node if the no_reboot flag is not set.

rpc Activate(ActivateRequest) returns (ActivateResponse);

The Verify RPC checks the OS version running on the target node. The client can call this RPC multiple times while the target node boots until the activation is successful.

rpc Verify(VerifyRequest) returns (VerifyResponse);

The Start RPC allows the client to instruct the target node to immediately clean all existing state data (including storage, configuration, logs, certificates, and licenses) and boot using the OS image configured as the golden image. The golden image is the image that the device resets to when a factory reset is performed. You can set the golden image using the tools system boot golden-image command. To view the available images to select from, use the tools system boot available-images command. If the golden image is not set, the system boots using the current OS image.

The Start RPC supports optional flags to:

• roll back to the OS configured as the golden image
• zero-fill any state data saved in persistent storage

If the golden image is configured and the factory_reset flag is set to true, SR Linux resets to the golden image. If the factory_reset flag is omitted or set to false, SR Linux boots using the current running image, but all existing state data is cleaned.

If any optional flags are set but not supported, the target node returns a gRPC Status message with code INVALID_ARGUMENT with the details value set to the appropriate ResetError message.

rpc Start(StartRequest) returns (StartResponse);

The Get RPC reads and streams the contents of a file from a target node to the client using sequential messages, and sends a final message containing the hash of the streamed data before closing the stream.

The target node returns an error if:

• An error occurs while reading the file.
• The file does not exist.

rpc Get(GetRequest) returns (stream GetResponse) {}

The Put RPC streams data to the target node and writes the data to a file. The client streams the file using sequential messages. The initial message contains information about the filename and permissions. The final message includes the hash of the streamed data.

The target node returns an error if:

• An error occurs while writing the data.
• The location does not exist.

rpc Put(stream PutRequest) returns (PutResponse) {}

The Stat RPC returns metadata about files on the target node.

If the path specified in the StatRequest references a directory, the StatResponse returns the metadata for all files and folders, including the parent directory. If the path references a direct path to a file, the StatResponse returns metadata for the specified file only.

rpc Stat(StatRequest) returns (StatResponse) {}

The Remove RPC removes the specified file from the target node.

The target node returns an error if:

• An error occurs during the remove operation (for example, permission denied).
• The file does not exist.
• The path references a directory instead of a file.

rpc Remove(RemoveRequest) returns (RemoveResponse) {}

The Ping RPC allows the client to execute the ping command on the target node. The target node streams the results back to the client. Some targets do not stream any results until they receive all results. If the RPC does not specify a packet count, the ping operation uses a default of five packets.

rpc Ping(PingRequest) returns (stream PingResponse) {}

The Traceroute RPC allows the client to execute the traceroute command on the target node. The target node streams the results back to the client. Some targets do not stream any results until they receive all results. If the RPC does not specify a hop count, the traceroute operation uses a default of 30.

rpc Traceroute(TracerouteRequest) returns (stream TracerouteResponse) {}

The Time RPC returns the current time on the target node. It is typically used to test whether the target is currently responding.

rpc Time(TimeRequest) returns (TimeResponse) {}

The SwitchControlProcessor RPC switches the active control processing module (CPM) on the target node to the control slot (A or B) that is specified in the request message.

rpc SwitchControlProcessor(SwitchControlProcessorRequest)
    returns (SwitchControlProcessorResponse) {}

The Reboot RPC allows the client to reboot a target node, either immediately or at some time in the future. It triggers the reboot of the entire chassis. It also supports specification of a reboot method (for example, cold or warm reboot), however, if the target node does not support the specified reboot method, the Reboot RPC fails.

If a reboot is pending on the active control processor, the service rejects all other reboot requests.

rpc Reboot(RebootRequest) returns (RebootResponse) {}

The CancelReboot RPC allows the client to cancel any pending reboot requests on the target node.

message CancelRebootResponse { }

The RebootStatus RPC allows the client to query the status of a reboot on the target node.

rpc RebootStatus(RebootStatusRequest) returns (RebootStatusResponse) {}

The KillProcess RPC allows a client to kill an OS process and optionally restart it on the target node.

To specify the process to kill, the RPC must match the application name referenced in the tools system app-management application <name> command.

rpc KillProcess(KillProcessRequest) returns (KillProcessResponse) {}

The Check RPC allows a client to execute a set of validations against a component. As with other Healthz operations, the component is specified using its gNMI path.

The Check RPC produces a Healthz ComponentStatus message, which contains a list of the artifacts generated from the validation process.

While the system can initiate health checks itself, these checks are limited to operations that do not impact the device functionality. Checks that are potentially service impacting require use of the Check RPC.

The CheckRequest message includes an optional event_id field. When populated, this field directs the system to perform the check for a prior event. In this case, the device collects artifacts that were not collected automatically when the event occurred (to prevent service impacts). The collected artifacts are returned in the artifact list for the event in subsequent Get or List RPC calls.

A CheckRequest for a previous event_id does not overwrite previous artifacts that were collected at the time of the event.

rpc Check(CheckRequest) returns (CheckResponse) {}

After a health check, the client can use the Get (or List) RPC to retrieve the health events that are associated with a component.

The Get RPC retrieves the latest health event for the specified component. Each event consists of a collection of data that you can use to debug or root cause the fault. Unlike the List RPC, the Get RPC returns only the latest event.

The GetResponse returns a ComponentStatus message that corresponds to the latest health event for the component and each of its subcomponents. As a result, the Get RPC can return multiple ComponentStatus messages for a single component.

Each ComponentStatus message includes a set of ArtifactHeader messages that correspond to the health event, and provide identifiers and types for the artifacts returned by the system. All artifacts listed within the same ComponentStatus message share the same acknowledgement state and expiry time.

When a client invokes a Get RPC on a path, this action is not recorded as an event for this path and no health checks are performed.

rpc Get(GetRequest) returns (GetResponse) {}

As an alternative to the Get RPC, the client can use the List RPC to retrieve not just the latest but all health events for the specified component and its subcomponents. Similar to the Get RPC, the List RPC also returns a series of ComponentStatus messages, which have the same semantics as those returned by the Get RPC.

By default, events that are already acknowledged are not returned.

rpc List(ListRequest) returns (ListResponse) {}

A client can use the Acknowledge RPC to indicate to the target node that the client retrieved a particular (component, event) tuple. To ensure that Healthz artifact storage does not cause resource exhaustion, SR Linux can remove saved artifacts, starting with acknowledged artifacts first.

rpc Acknowledge(AcknowledgeRequest) returns (AcknowledgeResponse) {}

The Artifact RPC allows a client to retrieve specific artifacts that are related to an event that the target node reported in a prior List or Get response.

Because these artifacts can be large, the Artifact RPC is implemented as a server-side streaming RPC. The Artifact RPC ensures that a target node sends these potentially large artifacts only when the client explicitly requests them.

Artifacts can be core files, dumps of state (info from state on the specified component), or other log files. The collection of info from state artifacts results in the capture of any failure reasons from either the oper-reason or oper-down-reason fields.

The client can acknowledge a retrieved event corresponding to a series of artifacts. Acknowledged events are no longer returned in the list of events by default.

Events persist across restarts of the system or its hardware and software components, and they are removed only for resource management purposes. SR Linux can use the acknowledged status to remove artifacts that are no longer relevant and, if necessary, remove artifacts that are not yet acknowledged.

rpc Artifact(ArtifactRequest) returns (stream ArtifactResponse) {}

To allow the gNOI Healthz events to be cleared using the CLI or by a gNMI or JSON-RPC client, SR Linux supports the following CLI command:

tools system grpc-server testing gnoi healthz [<component>] clear

You can omit the component value to clear all statistics for all components, or you can use one of the following parameters to clear statistics for the specified component only:

• chassis: chassis component
• control slot <id>: control module component
• fabric slot <id>: fabric module component
• fan-tray id <id>: fan component
• linecard slot <id>: line card component
• power-supply id <id>: power supply component
• transceiver interface <name>: transceiver component

The following steps show a typical call flow using the gNOI Packet Link Qualification RPCs. In these examples, the client is referred to as the orchestrator.

   
 Orchestrator                              Generator                              Reflector   
 
 | ------------- Capabilities() -------------> |                                         |

 | <------------CapbilityResponse ------------ |                                         |

 | -------------------------------------- Capabilities() ------------------------------> |

 | <------------------------------------ CapabilityResponse() -------------------------- |

   
 Orchestrator                              Generator                              Reflector

 | -------------------- Create() ------------> |                                         |
 
 | ----------------------------------------- Create() ---------------------------------> |

    *Generator and Reflector both validate the CreateRequest*                                     

   
 Orchestrator                              Generator                              Reflector

 | --------------------- Get() -------------> |                                          |
        
 | <---------------- GetResponse ------------ |                                          |

 | ----------------------------------------- Get() ------------------------------------> |

 | <------------------------------------- GetResponse----------------------------------- |

    *Loop until qualification complete*                                                     

   
 Orchestrator                              Generator                              Reflector

 | --------------------- List() -------------> |                                         |
        
 | <---------------- ListResponse ------------ |                                         |

 | ------------------------------------------- List() ---------------------------------> |

 | <--------------------------------------- ListResponse-------------------------------- |

                                                     

   
 Orchestrator                              Generator                              Reflector 

 | ------------------- Delete() -------------> |                                         | 
  
 | ----------------------------------------- Delete() ---------------------------------> |
                                                                         

The Capabilities RPC allows the client to determine the generation and reflection capabilities of target peers in preparation for a packet link qualification between the two devices.

rpc Capabilities(CapabilitiesRequest) returns (CapabilitiesResponse);

The Create RPC initiates a qualification operation for each interface. If it fails to create the qualification, the RPC returns an error.

When the Create RPC is called, the device interfaces are put into a forwarding mode which must not contain other traffic, either control or data. This setting can cause the generator or reflector endpoint to become unreachable.

An interface that is configured but not present in the state datastore is not eligible for testing, and interface not found is returned. An interface that is present in state but not in the configuration is eligible for testing.

An attempt to create a test with a duplicate ID returns an AlreadyExists error. This is applicable both to a test that is still running or to a completed test that is not yet deleted using the Delete RPC.

rpc Create(CreateRequest) returns (CreateResponse);

The Get RPC allows the client to retrieve the status for the specified qualification IDs.

rpc Get(GetRequest) returns (GetResponse);

The Delete RPC allows the client to remove the qualification results for the specified qualification IDs. If a qualification is still in progress, the qualification is first canceled before it is deleted. If a qualification cannot be stopped or deleted, the RPC returns an error.

A client can cancel a running qualification early for several reasons, such as:

• Determination that the errors have already exceeded a threshold
• Desire to change the rate or MTU for a running test
• Realization that the qualification was scheduled at the wrong time

rpc Delete(DeleteRequest) returns (DeleteResponse);

The List RPC allows the client to retrieve the current results for the specified qualification IDs from the generator and reflector nodes.

rpc List(ListRequest) returns (ListResponse);

To allow the gNOI Packet Link Qualification behavior to be invoked in the CLI or by a gNMI or JSON-RPC client, SR Linux supports the following CLI commands:

• system packet-link-qualification profile <profile>
• tools interface <name> packet-link-qualification start id <id> qualification-profile <profile>
• info from state interface <name> packet-link-qualification result <id>
• tools interface <name> packet-link-qualification cancel id <id>