Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

gNOI System Service

SUMMARY Use the gNOI System service to perform system operations on the target network device, including rebooting the device, upgrading software, and troubleshooting the network.

Overview

The gNOI System service provides RPCs to perform a number of different system operations on a network device, including the following operations:

  • Reboot a device
  • Execute ping and traceroute commands to troubleshoot the network
  • Upgrade software
  • Perform a Routing Engine switchover

The proto definition file is located at https://github.com/openconfig/gnoi/blob/master/system/system.proto.

Note:

The gnoi-system process restarts in the event of a system failure. To restart it manually, use the restart gnoi-system command.

Network Device Configuration

Before you begin:

No additional configuration is required to use the System service RPCs.

Ping and Traceroute

You can execute ping and traceroute commands on the network device to troubleshoot issues on your network.

Table 1: Supported system.proto RPCs for Troubleshooting the Network
RPC Description Introduced in Release
Ping()

Ping a device. The Ping() RPC supports IPv4 and IPv6 pings. This RPC streams back the results of the ping after the ping is complete.

Default number of packets: 5

Junos OS Evolved 22.2R1

Traceroute()

Execute the traceroute command on the target device and stream back the results.

Default hop count: 30

Junos OS Evolved 22.2R1

Example: Ping

In this example, the client executes the gnoi_ping_request.py Python application. The application sends the Ping() RPC to the network device, which then pings the specified device on the network.

The gnoi_ping_request.py application imports the grpc_channel module to establish the channel. The grpc_channel module is described in Configure gNOI Services. The application's arguments are stored in the gnoi_ping_request_args.txt file. The application and argument files are presented here.

gnoi_ping_request.py

gnoi_ping_request_args.txt

Execute the Application

On the client, execute the application, which prompts for the server's password for the RPC call credentials. The PingResponse indicates that the device sent five pings. The final response includes the summary statistics for the ping request, which shows that the device sent five pings and received five responses.

Reboot a Device

Use the System service RPCs to remotely reboot a device, check the status of the reboot, and cancel the reboot if needed. You can execute these RPCs on the device or on specific subcomponents. Junos devices support the following reboot methods:

  • COLD (1): Available for all types of reboots.

  • POWERDOWN (2): Use for FPC reboots.

  • HALT (3): Use for active Control Processor reboots.

  • POWERUP (7): Use for FPC reboots.

Table 2: Supported system.proto RPCs for Rebooting
RPC Description Introduced in Release
Reboot()

Reboot the target. You can only execute one reboot request on a target at a time.

You can optionally configure a delay to reboot in the future, reboot subcomponents individually, and add a message when the reboot initiates. The delay is configured in nanoseconds.

Junos devices support the following reboot methods:

  • COLD (1)

  • POWERDOWN (2)

  • HALT (3)

  • POWERUP (7)

Junos OS Evolved 22.2R1

RebootStatus() Return the status of the reboot.

Junos OS Evolved 22.2R1

CancelReboot() Cancel a pending reboot request.

Junos OS Evolved 22.2R1

Example: Reboot

In this example, the client executes the gnoi_reboot_request.py Python application. The application sends the reboot request and then checks the status of the reboot.

The application lets the user set the reboot delay in seconds. Since the RebootRequest() interprets the delay in nanoseconds, the application converts the user input into nanoseconds for the request. In this example, the client specifies a 60-second delay for the reboot operation.

The gnoi_reboot_request.py application imports the grpc_channel module to establish the channel. The grpc_channel module is described in Configure gNOI Services. The application's arguments are stored in the reboot_status_request_args.txt file. The application and argument files are presented here.

gnoi_reboot_status_request.py

reboot_status_request_args.txt

Execute the Application

When the client executes the application, the application prompts for the server's password for the RPC call credentials. The application then reboots the server after a 60 second delay and returns the applicable reboot status messages. The message set under reason also appears on the server immediately before the server reboots. In this example, any user logged into the server sees "Testing gNOI reboot" immediately before it reboots.

Upgrade Software

Table 3 lists the System service RPCs that support software upgrades.

Table 3: Supported system.proto RPCs for Software Upgrades
RPC Description Introduced in Release
SetPackage()

Install a software image on the target device.

Junos OS Evolved 22.2R1

You can use the SetPackage() RPC to copy a software image to the target device and install it. The source software image must reside on the local network management system. If the file copy operation is successful, and a file of the same name already exists at the target location, the file is overwritten. The RPC returns an error if the target location does not exist or if there is an error writing the data.

By default, SetPackage() does not reboot the device and activate the software. You must explicitly set the activate option to 1 in the SetPackageRequest message to activate the new software. If you activate the software, the device reboots and uses the new software image. If you do not activate the software, you must reboot the relevant nodes to complete the installation and activate the new software image.

Example: Install a Software Package

In this example, the client executes the gnoi_system_set_package.py Python application, which performs the following operations:

  • Copies the software package from the local network management system to the network device.
  • Installs the package on the network device.
  • Reboots the network device, thus activating the new software image.

The application constructs the SetPackageRequest message with the appropriate parameters to define the request for the copy and install operations. The application then calls the SetPackage() RPC to send the request to the network device. The SetPackageRequest message contains the following components:

  • An initial Package message containing the path and file information for the software image. The activate argument is set to 1 (True) to reboot the device and activate the software.
  • A stream of the software image file contents in sequential messages that do not exceed 64KB.
  • A final message with the file checksum to verify the integrity of the file contents.

The gnoi_system_set_package.py application imports the grpc_channel module to establish the channel. The grpc_channel module is described in Configure gNOI Services. The application's arguments are stored in the args_system_set_package.txt file. The application and argument files are as follows:

gnoi_system_set_package.py

args_system_set_package.txt

Execute the Application

When the client executes the application, the application copies the package from the local device to the network device, installs it, and then reboots the device to complete the installation.

Routing Engine Switchover

You can use the SwitchControlProcessor() RPC to perform a Routing Engine switchover.

Note:

Successive Routing Engine switchover events must be a minimum of 400 seconds apart after both Routing Engines have come up.

Table 4: Supported system.proto RPCs for Routing Engine Switchover
RPC Description Introduced in Release
SwitchControlProcessor()

Switch from the current Routing Engine to the specified Routing Engine. If the current and specified Routing Engines are the same, it is a NOOP. If the target does not exist, the RPC returns an error.

Note:

Junos devices do not support control_processor for SwitchControlProcessorResponse.

Junos OS Evolved 22.2R1

Example: Routing Engine Switchover

In this example, the gNOI client executes the gnoi_system_switch_control_processor.py application to perform a Routing Engine switchover. The client specifies which switch control processor, or Routing Engine, should be the primary Routing Engine by including the control_processor argument. If the target Routing Engine does not exist, the RPC returns an INVALID_ARGUMENT error.

The application imports the grpc_channel module to establish the channel. The grpc_channel module is described in Configure gNOI Services.

gnoi_system_switch_control_processor.py

Execute the Application

The client executes the application and sets the control_processor argument to re1 so that re1 becomes the primary Routing Engine.

After executing the operation, re1 is the primary Routing Engine on the target device.