The RMA process replaces a faulty switch, so that the replacement hardware takes over the identity, intended configuration and topology position of the device it replaces. This page covers the complete flow, including the credential handling that is specific to replaced hardware.

A configuration backup must exist. The replacement is restored from a device configuration snapshot taken while the original switch was healthy. Snapshots are produced by the periodic system backup, which covers devices in the MANAGED stage, and can also be created on demand from the device's Configuration Snapshots tab. Verify the snapshot before you begin — once the old switch is removed you can no longer take one from it.

The replacement hardware must match. In this context, “replacement” means hardware of the same model as the faulty switch, using the same device profile and hardware layout. Hardware with a different layout is not supported as part of the RMA process. Before you run Finish RMA, the replacement must also be reachable by SandWork over management connectivity, gNMI and SSH.

Record the replacement's MAC address. You will need it at Finish RMA. See Why the MAC address matters — omitting it causes a failure mode that is not obvious afterwards.

Two default roles can run the whole procedure end to end:

• DC Admin (dc-admin)

• DC Super Admin (dc-super-admin)

DC Admin is sufficient. No step of an RMA needs escalation to DC Super Admin, and none of it requires changing Global Fabric Settings.

The read-only DC Viewer (dc-viewer) role cannot perform any part of the process, and Administrative Admin (administrative-admin) covers only user and role management. For the permissions behind each role, see Default RBAC Roles and Permissions.

Open the device and choose Start RMA.

Open

Start RMA is permitted from any stage except BLUEPRINT. If the device is in MANAGED, MANAGED_CONFLICT or OS_INSTALL_FAILURE, SandWork first drains traffic away from it by configuring the BGP max-med value on each VRF, then moves it to the RMA stage. From any other stage the device is moved to RMA directly, with no traffic-drain attempt. Under Use optional values you can override the max-med value and the drain timeout.

If the device was in OS_INSTALL or OS_INSTALL_FAILURE, its OS upgrade status and any recorded upgrade failure are cleared as part of this step.

Note: the device is moved to RMA whether or not the traffic drain succeeds. A switch that has already failed may be unreachable, and that must not block the replacement.

While a device is in the RMA stage, service intents for it can still be stored in the inventory, but no configuration is pushed to it outside the RMA process. The rest of the fabric can be operated normally while the switch is physically absent.

Swap the switch and bring the replacement up with management connectivity so SandWork can reach it. Note its MAC address. This step happens entirely outside SandWork.

Open the device and choose Finish RMA. The dialog takes two inputs:

• MAC Address — the replacement switch's MAC address.

• Reset Greenfield setup passed device flag — unless required otherwise leave unticked.

Finish RMA requires the device to be in the RMA stage, and moves it to CONNECTED on success.

Note: always enter the MAC address, even though the field is optional in the form. See Why the MAC address matters.

On the device's Configuration Snapshots tab, select the snapshot to restore and push it to the device.

The confirmation dialog warns when the snapshot was taken in a different stage than the device is currently in, and when applying it will enable or disable traffic. For an RMA these warnings are expected: the snapshot was taken while the device was MANAGED, and the device is now CONNECTED.

Note: push the snapshot while the device is still in CONNECTED, before advancing it. Pushing a snapshot onto a device that has already been promoted moves it backwards — a device in CONFIG_READY returns to CONFIG_PENDING, and a device in MANAGED moves to MANAGED_CONFLICT.

Advance the device through the staging transitions:

DC Lifecycle >> Staging >>

1. Connected → Onboarded

2. Onboarded → Config Pending

3. Config Pending → Config Ready

4. Config Ready → Managed

Config Pending → Config Ready runs a full reconciliation and promotes the device only if it reports no conflicts. The other three transitions do not reconcile.

For a replaced switch this transition will normally fail on its first attempt, reporting conflicts on TACACS, RADIUS and SNMP. This is expected — see the next section.

SONiC stores the TACACS passkey encrypted with a key derived from the switch's own hardware MAC address. The SNMPv3 authentication and privacy keys and the RADIUS shared secret behave the same way.

A replacement switch has a different MAC, so those secrets as captured in the configuration snapshot cannot be decrypted by the new hardware. Restoring the backup therefore leaves unusable credentials on the replacement — the configuration is present but does not work.

SandWork handles this. When Finish RMA records a new MAC address, it marks TACACS, RADIUS and SNMP on that device as desynchronized: the intent is correct, but the secret on the device cannot be trusted. Reconciliation reports each of them as a conflict until the secret has been re-sent from SandWork's own store, which SandWork can decrypt — unlike the copy held on the device.

1. Open the failed Config Pending → Config Ready workflow in the Workflow Queue.

2. Its results include the reconciliation output, with a tab per Global Fabric Setting.

3. On the TACACS tab, select the device and push.

4. Repeat on the RADIUS and SNMP tabs for whichever your fabric uses.

5. Re-run Config Pending → Config Ready. Reconciliation now passes and the device is promoted.

6. Finish with Config Ready → Managed.

The same push controls are reachable from a standalone reconciliation run on the device, if you would rather not leave a failed transition in the queue.

Note: this does not require editing the pod or data centre TACACS configuration, and does not require the DC Super Admin role. Changing the Global Fabric Settings intent to force a re-push is not the intended route and will change the setting for every device in that scope.

SandWork uses the change of MAC address at Finish RMA to detect that the hardware is genuinely new. If the MAC field is left blank, the device is not flagged, reconciliation reports TACACS, RADIUS and SNMP as being in order, and no push is offered — while the switch is in fact holding credentials it cannot use. Nothing surfaces the problem until the affected service fails.

If Finish RMA was already completed without the MAC address, re-run it with the correct MAC once the device is back in the RMA stage, or push the TACACS, RADIUS and SNMP settings to the device explicitly.

Config Pending → Config Ready fails on TACACS, RADIUS or SNMP. Expected after a replacement. Re-push the secrets as described above, then re-run the transition.

Config Pending → Config Ready fails on other intents. Open the failed workflow in the Workflow Queue and review the reconciliation results per intent. Each intent type offers its own push action to bring the device back in line with the inventory.

Finish RMA is rejected because the device is not in the RMA stage. Finish RMA applies only to devices in RMA. Run Start RMA first.

The replacement is unreachable at Finish RMA. Confirm management connectivity, gNMI and SSH reachability before retrying.

No usable configuration snapshot exists. The replacement has to be configured through the normal setup path instead. Tick Reset Greenfield setup passed device flag at Finish RMA so the initial setup is applied again.