> ## Documentation Index > Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Rack administration This guide covers adding, viewing, exporting, and managing racks and their devices using SambaRack Manager. It includes tasks for both new installations and ongoing management. The complete setup process is: 1. Install SambaRack Manager software 2. Initial setup and verification 3. **Add SambaRack to the SambaRack Manager inventory** (this page) 4. Configure device credentials in SambaRack Manager ## Key concepts Read this section once. Everything after it depends on these four things. ### Rack IDs **Rack IDs must always be numeric, from 001 to 4096.** ### Part numbers The part number determines which components are scaffolded when you add a rack. | Part number | Configuration | | :---------- | :----------------------------- | | `1001934` | SambaRack SN40L-16 with 4 PDUs | | `1002331` | SambaRack SN40L-16 with 2 PDUs | To identify the part number for your installed SambaRack, refer to the relevant knowledge base article on the SambaNova Support Portal. ### Device types **Rack-level:** | Type | Description | | ----------------- | --------------------------- | | `access_switch` | Access switch | | `data_switch` | Data switch | | `pdu` | Power Distribution Unit | | `serial_terminal` | Serial console server (SCS) | **Node-level:** | Type | Description | | ------ | ------------------------------------------------------------- | | `host` | Host module | | `bmc` | Baseboard Management Controller | | `xrdu` | Accelerator module with two Reconfigurable Data Units™ (RDUs) | Nodes themselves are scaffolded automatically from the part number — there is no separate command to add a node. ### Device paths and indexing Commands that act on a single device take a path. Whether that path ends in an index depends on the device type. | Device type | Slotted? | Index range | Path format | Example | | ------------------------------------------------- | -------- | ------------------- | ------------------------------------------------- | ------------------------ | | `pdu` | Yes | **1–4** (1-indexed) | `Rack///` | `Rack/001/pdu/1` | | `access_switch`, `data_switch`, `serial_terminal` | Yes | **0+** (0-indexed) | `Rack///` | `Rack/001/data_switch/0` | | `xrdu` | Yes | **0–7** (0-indexed) | `Rack//Node///` | `Rack/001/Node/0/xrdu/1` | | `host`, `bmc` | **No** | — | `Rack//Node//` | `Rack/001/Node/0/bmc` | PDUs start at 1 while everything else starts at 0. This matches how the hardware is physically labelled. ## Populate the inventory Racks must be powered on and fully functional before you add them to the inventory. Choose one of two paths: | Method | Effort per rack | Scales to | Best for | | ----------------------------------------------------------------------------------- | --------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Import from a file**](#option-1--import-from-a-file-recommended) *(recommended)* | 1 command | Single rack → multi-rack, bulk inventory | Any scale — from one rack to entire fleets; generate the file using the [Inventory file schema](/docs/en/sambastack/hardware-admin/sambarack-manager/srm-inventory-file-schema) as reference | | [**Add manually**](#option-2--add-manually) | \~18 commands | 1–2 racks only | Small, one-off setups when customization is required; acts as a fail-safe fallback | A single SN40L-16 rack scaffolds around 17 devices, each needing its own `rack add-device` call — so prefer the import path whenever a file exists. ### Option 1 — Import from a file (recommended) ```bash theme={} snctl rack import [flags] ``` The file is a native `snctl` inventory in JSON or YAML. It may contain a subset of racks, groups, or both — including a file produced by [`rack export`](#export-racks). Pass `-` to read from stdin. See [Inventory file schema](/docs/en/sambastack/hardware-admin/sambarack-manager/srm-inventory-file-schema) for the format. **Flags:** | Flag | Description | | ------------- | ----------------------------------------------------------------------------------------- | | `--dry-run` | Preview the changes without modifying the inventory | | `--overwrite` | Replace existing racks and groups. Without it, existing entries are skipped and reported. | **Always run with `--dry-run` first.** It reports exactly which racks would be added, updated, or skipped — and how many credentials would be imported — without writing anything. ```powershell theme={} # Preview snctl rack import racks.json --dry-run #Expected Output ✓ [dry-run] Rack XXX added [dry-run] nodes added: # Import snctl rack import racks.json #Expected Output ✓ Rack XXX added nodes added: #Verify if import commands worked snctl rack list Rack ID Part Number Nodes PDUs XRDUs Acc Switch Data Switch SCS ------- ----------- ----- ---- ----- ---------- ----------- --- 001 1001934 1 4 8 1 1 1 002 1001934 1 4 8 1 1 1 # Replace racks and groups that already exist snctl rack import racks.json --overwrite ``` If a rack already exists and `--overwrite` was not passed: ```text theme={} ⚠ Rack 001 skipped (already exists; use --overwrite to replace) ``` ### Option 2 — Add manually #### Step 1 — Add the rack ```bash theme={} snctl rack add --partnumber ``` | Parameter | Description | | -------------- | ----------------------------------------------------- | | `` | Numeric ID of the rack (e.g. `001`) | | `--partnumber` | Part number of the installed SambaRack — **required** | ```bash theme={} snctl rack add 001 --partnumber 1001934 #Expected output ✓ Rack 001 (1001934) added ``` This scaffolds the rack's full component layout from the part number: nodes, PDUs, XRDUs per node, access switches, data switches, and serial terminals. **The scaffolded devices carry placeholder connection details.** Register the real values in step 2. #### Step 2 — Register each device's connection details ```bash theme={} snctl rack add-device \ --ip \ --user \ --hostname \ [--port ] ``` | Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------- | | `` | Path to the device — see [Device paths and indexing](#device-paths-and-indexing) | | `--ip` | Device IP address (optional) | | `--user` | Username for the device (optional) | | `--hostname` | Device hostname (optional) | | `--port` | Connection port (optional). Left unset when adding a new device without it; preserved when updating. | Every field is optional, so you can configure a device incrementally across several calls — omitting a field preserves its current value. The device must end up with an address, though: supply at least one of `--ip` or `--hostname`. Device IP details and credentials for each device type are shared with customers by SambaNova. Refer to it for the parameter values below. ```bash theme={} # Node-level, non-slotted (host, bmc) snctl rack add-device Rack/001/Node/0/host --ip --user root --hostname SFT-SN40L-16-H-1 snctl rack add-device Rack/001/Node/0/bmc --ip --user admin --hostname SN40L-16-H-1-SP # Node-level, slotted (xrdu, index 0–7) snctl rack add-device Rack/001/Node/0/xrdu/0 --ip --user root --hostname SN40L-16-H-1-XRDU0 # Rack-level, slotted (pdu, index 1–4) snctl rack add-device Rack/001/pdu/1 --ip --user admin --hostname SN40L-16-PDU1 --port 3003 ``` Expected output, per device: ```text theme={} ✓ Device host added/updated in rack 001 Password set to placeholder. Use 'snctl secret set --device-type host' to store credentials. ``` ### Next step Configure your [device credentials](/docs/en/sambastack/hardware-admin/sambarack-manager/srm-device-credentials). Adding a device stores a placeholder password, so set the real credentials for each device type with `snctl secret set` before you run any operations against it. If you used `rack import` and the source file contained real passwords, those are imported into the encrypted credential store and no longer need setting. The [inventory file schema](/docs/en/sambastack/hardware-admin/sambarack-manager/srm-inventory-file-schema) has no password field, so most import files carry placeholders instead. Verify either way with `snctl secret get --device-type bmc`. *** ## View the inventory ### List racks ```bash theme={} snctl rack list ``` ```powershell theme={} Rack ID Part Number Nodes PDUs XRDUs Acc Switch Data Switch SCS ------- ----------- ----- ---- ----- ---------- ----------- --- 001 1001934 1 4 8 1 1 1 002 1002331 1 2 8 1 1 1 ``` **`snctl rack list -o wide`** adds a **Type** column with the human-readable rack model: ```powershell theme={} Rack ID Part Number Nodes PDUs XRDUs Acc Switch Data Switch SCS Type ------- ----------- ----- ---- ----- ---------- ----------- --- -------- 001 1001934 1 4 8 1 1 1 SN40L-16 ``` **`snctl rack list -o json`** for machine-readable output: ```json theme={} [ { "rack_id": "001", "part_number": "1001934", "type": "SN40L-16", "nodes": 1, "pdus": 4, "xrdus": 8, "access_switches": 1, "data_switches": 1, "scs": 1 } ] ``` ### Show rack details ```bash theme={} snctl rack show ``` ```powershell theme={} Rack 001 (Part Number: 1001934, Type: SN40L-16) Component Hostname IP Port Username -------------------------- ------------------ ------------ ---- -------- Rack/001/serial_terminal/0 SN40L-16-SCS 172.19.11.61 sysadmin Rack/001/access_switch/0 SN40L-16-ASW0 172.19.11.60 admin Rack/001/data_switch/0 SN40L-16-DSW0 172.19.11.59 admin Rack/001/pdu/1 SN40L-16-PDU1 172.19.11.55 admin Rack/001/pdu/2 SN40L-16-PDU2 172.19.11.56 admin Rack/001/pdu/3 SN40L-16-PDU3 172.19.11.57 admin Rack/001/pdu/4 SN40L-16-PDU4 172.19.11.58 admin Rack/001/Node/0/host SFT-SN40L-16-H-1 172.19.11.45 root Rack/001/Node/0/bmc SN40L-16-H-1-SP 172.19.11.46 admin Rack/001/Node/0/xrdu/0 SN40L-16-H-1-XRDU0 172.19.11.47 root ... Rack/001/Node/0/xrdu/7 SN40L-16-H-1-XRDU7 172.19.11.54 root ``` Use this to confirm an import or a series of `add-device` calls produced the values you expected. | Variant | Adds | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-o wide` | A **Node** column showing which node each node-level device belongs to | | `-o json` | Structured output with `rack_id`, `part_number`, `type`, and a `devices` array — each entry includes `component`, `hostname`, `ip`, `username`, and `node_name` for node-level devices | **Example – show the node each device belongs to:** ```bash theme={} snctl rack show 001 -o wide ``` ```powershell theme={} Rack 001 (Part Number: 1001934, Type: SN40L-16) Component Node Hostname IP Port Username -------------------------- --------------- ------------------ ------------ ---- -------- Rack/001/serial_terminal/0 SN40L-16-SCS 172.19.11.61 sysadmin Rack/001/access_switch/0 SN40L-16-ASW0 172.19.11.60 admin Rack/001/pdu/1 SN40L-16-PDU1 172.19.11.55 admin Rack/001/Node/0/host sn40l-16-001-n1 SFT-SN40L-16-H-1 172.19.11.45 root Rack/001/Node/0/bmc sn40l-16-001-n1 SN40L-16-H-1-SP 172.19.11.46 admin Rack/001/Node/0/xrdu/0 sn40l-16-001-n1 SN40L-16-H-1-XRDU0 172.19.11.47 root ``` The **Node** column carries the node name that `snctl node` and `snctl power` commands take. Rack-level devices — PDUs, switches, and serial terminals — leave it empty. *** ## Maintain the inventory ### Export racks Export racks to a file or stdout, for backups, sharing, or review. ```bash theme={} snctl rack export [rack_id...] [flags] ``` With no rack IDs, all racks are exported. **Passwords are always replaced with placeholders** (`${BMC_SECRET}`, `${PDU_SECRET}`, and so on), so the export file is safe to share. | Flag | Description | | ----------------------- | -------------------------------------------------------------------------------------------------- | | `--file ` | Output file path (default: stdout) | | `-o, --output ` | `json` or `yaml`. Inferred from the `--file` extension; defaults to `json` when writing to stdout. | ```bash theme={} # All racks to stdout as JSON snctl rack export # Specific racks to a YAML file snctl rack export 001 002 --file racks.yaml # As YAML to stdout snctl rack export --output yaml # A single rack to a JSON file snctl rack export 001 --file rack-001.json ``` ```text theme={} ✓ 1 rack(s) exported to rack-001.json ``` The exported file contains the full rack structure — serial terminals, switches, PDUs, and nodes with their host, BMC, and XRDU components — with all connection details except passwords. ### Delete a device ```bash theme={} snctl rack delete-device \ --device-type \ [--index ] ``` | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `` | Rack ID or node name | | `--device-type` | Type of device to delete — see [Device types](#device-types) | | `--index` | Device index — required for slotted types, omitted for `host` and `bmc`. See [Device paths and indexing](#device-paths-and-indexing). | ```bash theme={} # Remove a PDU (1-indexed) snctl rack delete-device 001 --device-type pdu --index 1 # Remove an XRDU (0-indexed) snctl rack delete-device 001 --device-type xrdu --index 0 # Remove a non-slotted device snctl rack delete-device 001 --device-type bmc ``` ### Delete a rack Removes a SambaRack and all its associated SN40L nodes from the inventory. ```bash theme={} snctl rack delete ``` This affects only the local inventory. It does not power off or modify the physical hardware, and it does not remove the rack from your SambaStack cluster. If removed in error, re-register with `snctl rack add --partnumber `. ```bash theme={} snctl rack delete 002 #Expected output ✓ Rack 002 deleted ``` Confirm with `snctl rack list`. *** ## Next step Configure your [device credentials](srm-device-credentials).