SambaRack Manager Rack Administration - SambaNova Documentation

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:

Install SambaRack Manager software
Initial setup and verification
Add SambaRack to the SambaRack Manager inventory (this page)
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_id>/<type>/<index>`	`Rack/001/pdu/1`
`access_switch`, `data_switch`, `serial_terminal`	Yes	0+ (0-indexed)	`Rack/<rack_id>/<type>/<index>`	`Rack/001/data_switch/0`
`xrdu`	Yes	0–7 (0-indexed)	`Rack/<rack_id>/Node/<node_index>/<type>/<index>`	`Rack/001/Node/0/xrdu/1`
`host`, `bmc`	No	—	`Rack/<rack_id>/Node/<node_index>/<type>`	`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 (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 as reference
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)

snctl rack import <file> [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. Pass - to read from stdin. See 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.

# Preview
snctl rack import racks.json --dry-run

#Expected Output
✓ [dry-run] Rack XXX added
[dry-run]   nodes added: <Node Name>

# Import
snctl rack import racks.json

#Expected Output
✓ Rack XXX added
  nodes added: <Node Name>

#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:

⚠ Rack 001 skipped (already exists; use --overwrite to replace)

Option 2 — Add manually

Step 1 — Add the rack

snctl rack add <rack_id> --partnumber <partnumber>

Parameter	Description
`<rack_id>`	Numeric ID of the rack (e.g. `001`)
`--partnumber`	Part number of the installed SambaRack — required

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

snctl rack add-device <device_path> \
  --ip <ip_address> \
  --user <username> \
  --hostname <hostname> \
  [--port <port>]

Parameter	Description
`<device_path>`	Path to the device — see 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.

# Node-level, non-slotted (host, bmc)
snctl rack add-device Rack/001/Node/0/host --ip <host-ip> --user root  --hostname SFT-SN40L-16-H-1
snctl rack add-device Rack/001/Node/0/bmc  --ip <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 <xrdu0-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 <pdu1-ip> --user admin --hostname SN40L-16-PDU1 --port 3003

Expected output, per device:

✓ 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. 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 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

snctl rack list

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:

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:

[
  {
    "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

snctl rack show <rack_id>

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:

snctl rack show 001 -o wide

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.

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 <path>`	Output file path (default: stdout)
`-o, --output <format>`	`json` or `yaml`. Inferred from the `--file` extension; defaults to `json` when writing to stdout.

# 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

✓ 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

snctl rack delete-device <target_id> \
  --device-type <device_type> \
  [--index <index>]

Parameter	Description
`<target_id>`	Rack ID or node name
`--device-type`	Type of device to delete — see Device types
`--index`	Device index — required for slotted types, omitted for `host` and `bmc`. See Device paths and indexing.

# 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.

snctl rack delete <rack_id>

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 <rack_id> --partnumber <part>.

snctl rack delete 002

#Expected output
✓ Rack 002 deleted

Confirm with snctl rack list.

Next step

Configure your device credentials.

Get started

Models

Features

Build

Resources

Rack administration

Key concepts

Rack IDs

Part numbers

Device types

Device paths and indexing

Populate the inventory

Option 1 — Import from a file (recommended)

Option 2 — Add manually

Step 1 — Add the rack

Step 2 — Register each device’s connection details

Next step

View the inventory

List racks

Show rack details

Maintain the inventory

Export racks

Delete a device

Delete a rack

Next step

​Key concepts

​Rack IDs

​Part numbers

​Device types

​Device paths and indexing

​Populate the inventory

​Option 1 — Import from a file (recommended)

​Option 2 — Add manually

​Step 1 — Add the rack

​Step 2 — Register each device’s connection details

​Next step

​View the inventory

​List racks

​Show rack details

​Maintain the inventory

​Export racks

​Delete a device

​Delete a rack

​Next step

Key concepts

Rack IDs

Part numbers

Device types

Device paths and indexing

Populate the inventory

Option 1 — Import from a file (recommended)

Option 2 — Add manually

Step 1 — Add the rack

Step 2 — Register each device’s connection details

Next step

View the inventory

List racks

Show rack details

Maintain the inventory

Export racks

Delete a device

Delete a rack

Next step