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>

The Deploy RPC loads the specified container image to the container registry of the target node. If the specified container image is a plugin, it is not loaded into the registry until the StartPlugin RPC is called.

SR Linux suppports uploads of image up to two GB in size. No limit exists on the total disk space that the container registry can use. You must closely monitor the available space per partition to ensure sufficient space remains. If the required disk space is unavailable, the deployment fails.

SR Linux deploys independent container registries per CPM. The Containerz interface replicates all RPCs targeting the system to both CPMs to ensure the device is ready to support CPM switchovers. For example, issuing the Deploy RPC for an image on a dual CPM system places the image in the container registry on CPM A and the container registry on CPM B. The underlying filesystem backing the container registries is not replicated and remains tied to a specific CPM.

rpc Deploy(stream DeployRequest) returns (stream DeployResponse) {}

The ListImage RPC returns all images from the active CPM on the target node that match the filter specified in the ListImageRequest message.

SR Linux responds with a list of the images, their ID, and their tags.

rpc ListImage(ListImageRequest) returns (stream ListImageResponse) {}

The RemoveImage RPC removes the image that matches the specified name and tag from the target node. To perform a force delete, set force to True in the RemoveImageRequest message.

rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse) {}

The RemoveContainer RPC removes the specified container from the target node. If the specified container is running, it is not removed unless the force option is set to True in the RemoveContainerRequest message.

 rpc RemoveContainer(RemoveContainerRequest) returns (RemoveContainerResponse) {}

The ListContainer RPC returns all containers from the target node that match the filter specified in the ListContainerRequest message. SR Linux returns only running containers unless the all option is set to true in the ListContainerRequest message.

When a container is started on SR Linux using the location option, the ListContainerResponse message includes the following labels:

• net.openconfig.containerz.location.intended: The location field specified at deployment
• net.openconfig.containerz.location.actual: The current location of the container on the operational system
• net.openconfig.containerz.location.reason: If the container failed to be placed, the reason for the failure

rpc ListContainer(ListContainerRequest) returns (stream ListContainerResponse) {}

The StartContainer RPC starts the specified container on the target node. This RPC instantiates a container on an SR Linux device. The container is created using an image already available in the SR Linux container registry (using the Deploy RPC).

To start a container, provide the image_name, image tag and an optional instance_name in the StartContainerRequest message.

If no instance_name is provided, SR Linux assigns one. When an instance (identified by an instance_name) already exists, the StartContainer RPC returns an error if the container is running, or if it is stopped but the StartContainerRequest contains more fields than just the instance_name. If the existing container is stopped and the StartContainerRequest contains only the instance_name, the system starts the container.

Common additional parameters for the StartContainerRequest message include:

• ports: Multiple ports may be specified. Each port has an internal (container-side) port and an external (network-facing) port.
• environment: Each environment variable is a map of two strings, the first being the key and the second being the value.
• volumes: Storage volumes created using the CreateVolume RPC (see the CreateVolume RPC section for further details)

• network: The network the container connects to. Supported options include host and bridged. The network field also accepts any externally created network name, but the creation of these other named networks is not supported on SR Linux. When the network is defined as host, SR Linux starts the container in the network namespace in which the StartContainer RPC is received.
• cap: The capabilities granted to or revoked from the container. Each capability is defined as add or remove. Supported capabilities are: AUDIT_WRITE, CHOWN, DAC_OVERRIDE, FOWNER, FSETID, KILL, MKNOD, NET_BIND_SERVICE, NET_RAW, SETFCAP, SETGID, SETPCAP, SETUID, and SYS_CHROOT
• restart: The restart policy for the container. The available options are: NONE, ALWAYS, UNLESS_STOPPED, and ON_FAILURE. Nokia recommends setting containers to the ALWAYS restart policy to ensure that they are restarted upon boot and CPM switchover. The number of restrarts that a container attempts before being declared as failed can be specified in the attempts field of the Restart message.
• run_as: The user the container runs as. If set, SR Linux starts the container using the user or user:group notation..
• labels: The labels assigned to a container.
• limits: The resource limitation requirements for the container: max_cpu, soft_mem_bytes, and hard_mem_bytes. The max_cpu provides the maximum amount of CPUs that may be consumed (for example 0.5 means a maximum of half a CPU). It does not imply this CPU quantity is reserved for this container. The hard and soft memory limits (in bytes) define the memory consumption levels at which the container may be terminated (soft) or is terminated (hard).
• devices: The devices added to the container. Permissions for the specified device are derived from the provided permissions enum: r = READ, w = WRITE, m = MKNOD.

• location: The CPM onto which the container is scheduled. The supported options are L_UNKNOWN, L_PRIMARY, L_BACKUP and L_ALL. The primary CPM is the currently active CPM. If a CPM switchover occurs, then the primary and backup CPMs are switched. For example, a container scheduled as L_PRIMARY is placed onto the active CPM A then a CPM switchover occurs and the container is then scheduled onto CPM B as the L_PRIMARY CPM is now the one in slot B.

  Containers scheduled as L_UNKNOWN are placed onto the active CPM. Containers scheduled as L_ALL are started on both the active and standby CPMs. These are independent containers with independent storage. The containers are started in the same network namespace and so may be able to communicate with one another, depending on the selected options. Containers do not support high-availablilty switchover. In the case of a CPM switchover they are essentially destroyed and recreated.

rpc StartContainer(StartContainerRequest) returns (StartContainerResponse) {}

The StopContainer RPC stops the container specified by the instance_name in the StopContainerRequest message on the target node. The container is gracefully stopped unless the force option is set to True. In addition, if the restart option is set to True, the container is restarted after it has stopped.

rpc StopContainer(StopContainerRequest) returns (StopContainerResponse) {}

The UpdateContainer RPC updates the specified container on the target node to the image specified in the UpdateContainerRequest message.

The UpdateContainer RPC is by default, synchronous, meaning that it performs the upgrade and only returns after the activity is complete. To request an asynchronous update, set async to True in the UpdateContainerRequest message. In this case, SR Linux performs the admission checks to ensure that the request can proceed (such as whether the image exists) before completing the RPC. You must then monitor the upgrade process externally.

In the UpdateContainerRequest message, specify the instance_name, image_name, and image_tag.

A container update may fail for a number of reasons, including: referencing a non-existent container, an image or tag cannot be found, the required ports cannot be exposed, or the container is found but is not in a started state.

rpc UpdateContainer(UpdateContainerRequest) returns (UpdateContainerResponse) {}

The Log RPC streams the logs from the specified container. If the container is not running, the RPC returns the latest available logs. The instance_name is mandatory when calling the Log RPC.

rpc Log(LogRequest) returns (stream LogResponse) {}

The CreateVolume RPC creates the specified volume on the target node. The volumes are persistent and remain available after a reboot.

The CreateVolumeRequest accepts the following options:

• name: The name of the volume. If omitted, SR Linux creates one automatically
• driver: The filesystem driver associated with the volume. The following options are supported:
  • DS_LOCAL: Not specifying a driver results in the DS_LOCAL option being selected.
  • DS_CUSTOM: SR Linux supports only one instance of DS_CUSTOM; that is, the system cannot support two CreateVolumeRequests with driver type DS_CUSTOM and any other options.
• options: Two types of options are supported:
  • local_mount_options: The local filesystem mount options supported are: type, options and mountpoint. SR Linux supports the none type only. The options are joined into the Docker DriverOpts (o). If a propagation mode is not specified SR Linux appends ,rprivate to avoid inheriting host mount propagation which may impact operational performance. The mountpoint is a bind-style local mount.
  • custom_options: A set of key, value pairs that are appended to Docker DriverOpts verbatim.

There are no restrictions on the SR Linux filesystem path that may be selected as the location of a volume. Select the location with caution. If used incorrectly, it may render the system inoperable.

rpc CreateVolume(CreateVolumeRequest) returns (CreateVolumeResponse) {}

The RemoveVolume RPC removes the specified volume from the target node. If the specified volume does not exist, the RPC completes with no action taken.

rpc RemoveVolume(RemoveVolumeRequest) returns (RemoveVolumeResponse) {}

The ListVolume RPC returns all volumes from the target node that match the filter specified in the ListVolumeRequest message.

rpc ListVolume(ListVolumeRequest) returns (stream ListVolumeResponse) {}

The StartPlugin RPC starts the specified plugin on the target node.

 rpc StartPlugin(StartPluginRequest) returns (StartPluginResponse) {}

The StopPlugin RPC starts the specified plugin on the target node.

rpc StopPlugin(StopPluginRequest) returns (StopPluginResponse) {}

The ListPlugin RPC returns all containers from the target node that match the filter specified in the ListPluginRequest message.

rpc ListPlugins(ListPluginsRequest) returns (ListPluginsResponse) {}

The RemovePlugin RPC removes the specified plugin from the target node. However, the plugin is not removed if it is still enabled. You must first call the StopPlugin RPC before attempting to invoke the RemovePlugin RPC.

rpc RemovePlugin(RemovePluginRequest) returns (RemovePluginResponse) {}