Skip to navigation

Switch Management

View as MarkdownOpen in Claude

Manage switch firmware and NVOS system images, passwords, factory reset, and attestation.

RPCExecutionSummary
ListSwitchFirmwareSynchronousListSwitchFirmware lists the firmware for switch.
PushSwitchFirmwareSynchronousPushSwitchFirmware pushes a firmware binary to target switch.
ListSwitchSystemImagesSynchronousListSwitchSystemImages retrieves the list of OS images available on the switch.
UpdateSwitchSystemImageAsynchronous, parent and child jobsUpdateSwitchSystemImage initiates asynchronous switch system image updates on a caller-supplied list of switch nodes.
ApplySwitchSystemImageAsynchronous, parent and child jobsApplySwitchSystemImage ingests a firmware object from SOT JSON, downloads required artifacts, resolves the switch system image artifact from the ingested firmware object, and starts updates for supplied switches.
ApplyStoredSwitchSystemImageAsynchronous, parent and child jobsApplyStoredSwitchSystemImage resolves a stored switch system image and starts updates for supplied switches.
BatchResetSwitchFactoryDefaultAsynchronous, parent and child jobsBatchResetSwitchFactoryDefault submits asynchronous NVOS factory resets.
UpdateSwitchSystemPasswordAsynchronous, parent and child jobsUpdateSwitchSystemPassword initiates asynchronous OS-level password updates for a specific user on a caller-supplied list of switch nodes.
BatchCollectSwitchSpdmAttestationEvidenceSynchronousBatchCollectSwitchSpdmAttestationEvidence synchronously generates and retrieves fresh SPDM evidence from caller-supplied switch trays.

For definitions of execution modes and job polling, refer to Async jobs.

ListSwitchFirmware

rack_manager.RackManager/ListSwitchFirmware

ListSwitchFirmware lists the firmware for switch. Returns version, update status, and health for switch firmware component.

PropertyValue
ExecutionSynchronous. The response carries the full result.
TargetRegistered inventory. Reads or changes nodes and racks stored in RMS inventory.
Behavior detailsOperations guide
Protobuf referenceListSwitchFirmware

Request: ListSwitchFirmwareRequest

FieldTypeDescription
rack_idstringRack ID for inventory lookup
node_idstringNode ID for inventory lookup
component_typeSwitchFirmwareComponentTypeRequired: Firmware component type enum

Response: ListSwitchFirmwareResponse

FieldTypeDescription
statusReturnCodeRETURN_CODE_SUCCESS if retrieved, RETURN_CODE_FAILURE otherwise
result_jsonstringJSON object containing firmware inventory result
error_messagestringError details if retrieval failed

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"rack_id": "<rack_id>",
"node_id": "<node_id>",
"component_type": "SWITCH_FIRMWARE_COMPONENT_TYPE_UNKNOWN"
}' \
"$RMS_ADDR" rack_manager.RackManager/ListSwitchFirmware

PushSwitchFirmware

rack_manager.RackManager/PushSwitchFirmware

PushSwitchFirmware pushes a firmware binary to target switch. Returns success or error_message

This call uploads the file to the switch and does not install it.

PropertyValue
ExecutionSynchronous. The response carries the full result.
TargetRegistered inventory. Reads or changes nodes and racks stored in RMS inventory.
Behavior detailsOperations guide
Protobuf referencePushSwitchFirmware

Request: PushSwitchFirmwareRequest

FieldTypeDescription
rack_idstringRequired: Rack ID for inventory lookup
node_idstringRequired: Node ID for inventory lookup
component_typeSwitchFirmwareComponentTypeRequired: Firmware component type enum
filenamestringRequired: Desired filename on the switch (used as-is, no suffix modification)
local_file_pathstringRequired: Local file path on rackmanager host (file must be at least 1KB)

Response: PushSwitchFirmwareResponse

FieldTypeDescription
statusReturnCodeRETURN_CODE_SUCCESS if pushed, RETURN_CODE_FAILURE otherwise
result_jsonstringJSON object containing push result
error_messagestringError details if push failed

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"rack_id": "<rack_id>",
"node_id": "<node_id>",
"component_type": "SWITCH_FIRMWARE_COMPONENT_TYPE_UNKNOWN",
"filename": "<filename>",
"local_file_path": "<local_file_path>"
}' \
"$RMS_ADDR" rack_manager.RackManager/PushSwitchFirmware

ListSwitchSystemImages

rack_manager.RackManager/ListSwitchSystemImages

ListSwitchSystemImages retrieves the list of OS images available on the switch. Returns information about installed and staged images.

PropertyValue
ExecutionSynchronous. The response carries the full result.
TargetRegistered inventory. Reads or changes nodes and racks stored in RMS inventory.
Behavior detailsOperations guide
Protobuf referenceListSwitchSystemImages

Request: ListSwitchSystemImagesRequest

FieldTypeDescription
rack_idstringRack containing the target switch
node_idstringTarget switch node identifier

Response: ListSwitchSystemImagesResponse

FieldTypeDescription
statusReturnCodeRETURN_CODE_SUCCESS if retrieved, RETURN_CODE_FAILURE otherwise
images_jsonstringJSON array containing image information
error_messagestringError details if query failed

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"rack_id": "<rack_id>",
"node_id": "<node_id>"
}' \
"$RMS_ADDR" rack_manager.RackManager/ListSwitchSystemImages

UpdateSwitchSystemImage

rack_manager.RackManager/UpdateSwitchSystemImage

UpdateSwitchSystemImage initiates asynchronous switch system image updates on a caller-supplied list of switch nodes. Each node is identified by its NodeInfo. Returns a parent job ID for tracking overall batch status, along with individual node job IDs. Use GetSwitchSystemImageJobStatus to track progress.

PropertyValue
ExecutionAsynchronous, parent and child jobs. The response returns a parent job ID and the work continues after the call returns.
Job trackingPoll GetSwitchSystemImageJobStatus with the job ID in response.job_id. Per-node child job IDs are in jobs.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceUpdateSwitchSystemImage

Request: UpdateSwitchSystemImageRequest

FieldTypeDescription
nodesNodeSetSwitch nodes to update
image_filenamestringBinary filename as it should exist on the switch
local_file_pathstringLocal file path on the RMS host
allow_onie_recoveryboolAllow recovery in cases where NVOS is not installed

Response: UpdateSwitchSystemImageResponse

FieldTypeDescription
responseNodeBatchResponse-
jobsrepeated SwitchSystemImageUpdateJobInfoIndividual job ID per switch

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"nodes": {
"nodes": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
]
},
"image_filename": "<image_filename>",
"local_file_path": "<local_file_path>",
"allow_onie_recovery": false
}' \
"$RMS_ADDR" rack_manager.RackManager/UpdateSwitchSystemImage

ApplySwitchSystemImage

rack_manager.RackManager/ApplySwitchSystemImage

ApplySwitchSystemImage ingests a firmware object from SOT JSON, downloads required artifacts, resolves the switch system image artifact from the ingested firmware object, and starts updates for supplied switches.

RMS treats the ingested firmware object as ephemeral for this request. It uses access_token only for artifact download and does not persist the token or object.

PropertyValue
ExecutionAsynchronous, parent and child jobs. The response returns a parent job ID and the work continues after the call returns.
Job trackingPoll GetSwitchSystemImageJobStatus with the job ID in response.job_id. Per-node child job IDs are in jobs.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceApplySwitchSystemImage

Request: ApplySwitchSystemImageRequest

FieldTypeDescription
rack_idstring-
config_jsonstringSOT JSON containing the firmware object ID and switch image
access_tokenoptional stringUsed only for artifact download; RMS does not persist it
software_typestring”dev” or “prod”
hardware_typestring-
nodesNodeSetCaller-supplied switch nodes
allow_onie_recoveryboolAllow recovery in cases where NVOS is not installed

Response: ApplySwitchSystemImageResponse

FieldTypeDescription
responseNodeBatchResponseresponse.job_id is parent job id
object_idstring-
image_filenamestring-
jobsrepeated SwitchSystemImageUpdateJobInfo-

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"rack_id": "<rack_id>",
"config_json": "<config_json>",
"access_token": "<access_token>",
"software_type": "<software_type>",
"hardware_type": "<hardware_type>",
"nodes": {
"nodes": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
]
},
"allow_onie_recovery": false
}' \
"$RMS_ADDR" rack_manager.RackManager/ApplySwitchSystemImage

ApplyStoredSwitchSystemImage

rack_manager.RackManager/ApplyStoredSwitchSystemImage

ApplyStoredSwitchSystemImage resolves a stored switch system image and starts updates for supplied switches.

PropertyValue
ExecutionAsynchronous, parent and child jobs. The response returns a parent job ID and the work continues after the call returns.
Job trackingPoll GetSwitchSystemImageJobStatus with the job ID in response.job_id. Per-node child job IDs are in jobs.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceApplyStoredSwitchSystemImage

Request: ApplyStoredSwitchSystemImageRequest

FieldTypeDescription
rack_idstring-
object_idstringEmpty means use default for hardware_type
software_typestring”dev” or “prod”
hardware_typestring-
nodesNodeSetCaller-supplied switch nodes
allow_onie_recoveryboolAllow recovery in cases where NVOS is not installed

Response: ApplyStoredSwitchSystemImageResponse

FieldTypeDescription
responseNodeBatchResponseresponse.job_id is parent job id
object_idstring-
image_filenamestring-
jobsrepeated SwitchSystemImageUpdateJobInfo-

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"rack_id": "<rack_id>",
"object_id": "<object_id>",
"software_type": "<software_type>",
"hardware_type": "<hardware_type>",
"nodes": {
"nodes": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
]
},
"allow_onie_recovery": false
}' \
"$RMS_ADDR" rack_manager.RackManager/ApplyStoredSwitchSystemImage

BatchResetSwitchFactoryDefault

rack_manager.RackManager/BatchResetSwitchFactoryDefault

BatchResetSwitchFactoryDefault submits asynchronous NVOS factory resets. All switches in the request use the same domain for NVUE mTLS material. Returns a parent job ID. Use GetJobStatus with child job states to track per-node progress. Unlike the SDN reset, this wipes NVOS configuration back to factory defaults.

A per-node job completes once the switch has rebooted after the reset and is reachable again via the default login; the factory default password is preserved, not rotated. If the supplied switch credentials do not work, RMS falls back to the factory default password to perform the reset, without assuming a switch was already reset just because the default login works. Set allow_ssh_fallback to permit reset submission over SSH when the reset cannot be submitted through NVUE. This fallback is disabled by default.

This operation is destructive. It wipes NVOS configuration.

PropertyValue
ExecutionAsynchronous, parent and child jobs. The response returns a parent job ID and the work continues after the call returns.
Job trackingPoll GetJobStatus with the job ID in response.job_id. Set include_child_job_states on GetJobStatus to read per-node child jobs.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceBatchResetSwitchFactoryDefault

Request: BatchResetSwitchFactoryDefaultRequest

FieldTypeDescription
nodesNodeSetTarget switch identities and direct connection information
domainoptional stringOptional domain for the target switch group; defaults to configured switch domain when unset
allow_ssh_fallbackboolAllow SSH fallback when the reset cannot be submitted through NVUE; defaults to false

Response: BatchResetSwitchFactoryDefaultResponse

FieldTypeDescription
responseNodeBatchResponseresponse.job_id is the parent job ID for GetJobStatus

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"nodes": {
"nodes": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
]
},
"domain": "<domain>",
"allow_ssh_fallback": false
}' \
"$RMS_ADDR" rack_manager.RackManager/BatchResetSwitchFactoryDefault

UpdateSwitchSystemPassword

rack_manager.RackManager/UpdateSwitchSystemPassword

UpdateSwitchSystemPassword initiates asynchronous OS-level password updates for a specific user on a caller-supplied list of switch nodes. The caller supplies both the current password and desired next password so retries can resume after a partial failure. Returns a parent job ID in response.job_id; use GetJobStatus to track progress.

The per-node results in the response report job admission only. Poll the jobs to learn whether each password change succeeded. The request sets only the new password for username and takes no current password. RMS reaches each switch with the credentials in that node’s endpoint, and those credentials can belong to a different user than username. On a retry, RMS probes password to detect an earlier partial success.

PropertyValue
ExecutionAsynchronous, parent and child jobs. The response returns a parent job ID and the work continues after the call returns.
Job trackingPoll GetJobStatus with the job ID in response.job_id. Set include_child_job_states on GetJobStatus to read per-node child jobs.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceUpdateSwitchSystemPassword

Request: UpdateSwitchSystemPasswordRequest

FieldTypeDescription
nodesNodeSetSwitch nodes to update
usernamestringTarget OS username whose password will be changed (mandatory)
passwordstringNew password to set for the user (mandatory)

Response: UpdateSwitchSystemPasswordResponse

FieldTypeDescription
responseNodeBatchResponseresponse.job_id is the parent job ID for GetJobStatus

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"nodes": {
"nodes": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
]
},
"username": "<username>",
"password": "<password>"
}' \
"$RMS_ADDR" rack_manager.RackManager/UpdateSwitchSystemPassword

BatchCollectSwitchSpdmAttestationEvidence

rack_manager.RackManager/BatchCollectSwitchSpdmAttestationEvidence

BatchCollectSwitchSpdmAttestationEvidence synchronously generates and retrieves fresh SPDM evidence from caller-supplied switch trays.

PropertyValue
ExecutionSynchronous. The response carries the full result.
TargetCaller-supplied nodes. The request carries each node’s endpoints and credentials, and RMS does not store them.
Behavior detailsOperations guide
Protobuf referenceBatchCollectSwitchSpdmAttestationEvidence

Request: BatchCollectSwitchSpdmAttestationEvidenceRequest

FieldTypeDescription
targetsrepeated NodeInfoSwitch trays from which RMS collects evidence
noncebytesCaller-generated nonce bound into every SPDM measurement
domainoptional stringOptional site selector; defaults to —default-switch-domain when unset

Response: BatchCollectSwitchSpdmAttestationEvidenceResponse

FieldTypeDescription
statusReturnCodeSUCCESS only when every target and component succeeded
messagestringBatch collection summary
resultsrepeated SwitchSpdmAttestationTargetResultOne entry per requested switch tray

Errors: Refer to Conventions for how RMS reports failures.

Replace each <placeholder> with a real value. Define RMS_GRPCURL_FLAGS and RMS_ADDR as described in Getting started.

grpcurl $RMS_GRPCURL_FLAGS \
-d '{
"targets": [
{
"node_id": "<node_id>",
"rack_id": "<rack_id>",
"type": "COMPUTE_GB200_NVIDIA",
"bmc_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"host_endpoint": {
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
},
"node_descriptor": {
"attributes": {
"<key>": "<attributes>"
}
},
"additional_host_endpoints": [
{
"interface": {
"ip_address": "<ip_address>",
"mac_address": "<mac_address>",
"host_name": "<host_name>"
},
"port": 0,
"credentials": {
"user_pass": {
"username": "<username>",
"password": "<password>"
}
}
}
]
}
],
"nonce": "",
"domain": "<domain>"
}' \
"$RMS_ADDR" rack_manager.RackManager/BatchCollectSwitchSpdmAttestationEvidence