SambaRack Manager Initial Setup - SambaNova Documentation

Initialize your configuration directory, generate an encryption key, and verify the environment. This is step 2 of the setup process:

Install SambaRack Manager software
Initial setup and verification — this page
Add SambaRack to the inventory
Configure device credentials

Global flags

These work with any snctl command and are useful throughout setup and daily use.

Flag	Description
`--snctl-dir <path>`	Directory holding the configuration, inventory, and credentials (default `$HOME/.snctl`). Used verbatim — no `.snctl` segment is appended. Env: `SNCTL_DIR`
`-o, --output <format>`	Output format: `text` (default), `wide`, or `json`
`--log-level <level>`	Log level: `debug`, `info`, `warn`, or `error`. Env: `SNCTL_LOG_LEVEL`

Step 1. Initialize configuration

Initialize SambaRack Manager with a single command:

snctl config init --defaults --service-account <path>

This is the recommended way to initialize. --defaults accepts every default path without prompting, and passing --service-account up front means you won’t need to run snctl config update later to add it. The default config, log, and cache locations follow standard Linux (XDG) conventions, so most deployments need no path overrides.

Expected output:

Initializing new configuration...
✓ Generated new encryption key at /path/.snctl/encryption.key
✓ Created credentials file at /path/.snctl/credentials.json.enc
Creating new empty inventory...
✓ Created empty inventory at /path/.snctl/inventory.json
✓ Created logs directory at /path/.snctl/logs
✓ Configuration updated at /path/.snctl/config.yaml

Initialization complete!

Configuration Summary

Setting           Value
----------------  -----------------------------------------------
Config Directory  /path/.snctl
Config File       /path/.snctl/config.yaml
Inventory         /path/.snctl/inventory.json
Encryption Key    /path/.snctl/encryption.key
Credentials       /path/.snctl/credentials.json.enc
Logs              /path/.snctl/logs
Service Account   /path/sambanova-sa.json
Cache Location    /path/.cache/snctl/firmware
Version           1.0.0
Last Updated      2026-08-19T12:36:26Z

Initialization aborts if the folder already contains configuration files. For example:

files already exist in /home/user1/.snctl: encryption.key, inventory.json, credentials.json.enc, config.yaml

Either point config init at an empty directory, or remove the existing files first.

What gets created

.snctl/
  ├── config.yaml                 # Main configuration file
  ├── credentials.json.enc        # Encrypted credentials (created with blank placeholders)
  ├── encryption.key              # AES-GCM encryption key used to encrypt credentials
  └── inventory.json              # Your infrastructure inventory (empty initially)

Logs are written outside this directory, to $XDG_STATE_HOME/snctl/logs — falling back to ~/.local/state/snctl/logs when XDG_STATE_HOME is unset.

Initialization flags

One flag is worth setting explicitly; everything else defaults to a standard Linux location.

Flag	Description
`--service-account <path>`	Path to a GCS service account JSON file

# Recommended
snctl config init --defaults --service-account /etc/snctl/sambanova-sa.json

This setting can also be changed after initialization — see Updating configuration.

(Optional) Using a custom configuration directory

If you need the configuration somewhere other than ~/.snctl, pass --config-dir during initialization. config init then ends with this note:

Note: Configuration created at /path/to/custom/.snctl/config.yaml
To use this configuration, run 'export SNCTL_DIR=/path/to/custom/.snctl' or use --snctl-dir

Every later command needs to know where the configuration lives. Choose one of the following. Option 1 — set the environment variable (recommended):

export SNCTL_DIR=/path/to/custom/.snctl

For persistence, add this line to your shell rc file (~/.bashrc or ~/.zshrc). Option 2 — pass --snctl-dir with each command:

snctl --snctl-dir /path/to/custom/.snctl node list

Both options take the path exactly as given — the CLI does not append a .snctl segment. Use the same path you gave snctl config init.

Step 2. Verify the setup

Run all three checks below before continuing. Confirm snctl is working:

snctl version

version:      1.0.0      # Exact version may vary
commit:       2c82328
build_time:   2026-07-14T08:05:35Z
go_version:   go1.25.11
os_arch:      linux/amd64

Display the current configuration:

snctl config show

Configuration Summary
Setting           Value
----------------  -------------------------------------------
Config Directory  /home/user1/.snctl
Config File       /home/user1/.snctl/config.yaml
Inventory         /home/user1/.snctl/inventory.json
Encryption Key    /home/user1/.snctl/encryption.key
Credentials       /home/user1/.snctl/credentials.json.enc
Logs              /home/user1/.local/state/snctl/logs
Service Account   /home/user1/ss-svcops-artifacts-reader.json
Cache Location    /home/user1/.cache/snctl/firmware
Version           1.0.0
Last Updated      2026-07-14T08:38:32.111853Z

Confirm Config Directory is the path you expect — every later command reads from this location.

Running snctl config show after upgrading SambaRack Manager updates config.yaml to the currently running version if the versions don’t match.

Step 3. Verify required dependencies

snctl diag doctor

Expected output when all dependencies are met:

Checking system dependencies...

Dependency         Status  Path                              Description
-----------------  ------  --------------------------------  -------------------------
ipmitool           OK      /usr/bin/ipmitool                 IPMI interface tool
gbtipmitool-linux  OK      /usr/local/bin/gbtipmitool-linux  IPMI interface tool
ssh                OK      /usr/bin/ssh                      Secure shell client
sshpass            OK      /usr/bin/sshpass                  SSH password provider
ping               OK      /usr/bin/ping                     Network connectivity test
curl               OK      /usr/bin/curl                     HTTP client
in.tftpd           OK      /usr/sbin/in.tftpd                TFTP daemon
jq                 OK      /usr/bin/jq                       JSON processor
sed                OK      /usr/bin/sed                      Stream editor
grep               OK      /usr/bin/grep                     Pattern search
awk                OK      /usr/bin/awk                      Text processor
bc                 OK      /usr/bin/bc                       Calculator
screen             OK      /usr/bin/screen                   Terminal multiplexer

✓ Your system is ready to use snctl!

When something is missing, the output ends with:

Some dependencies are missing. Please install them and try again.

Install anything reported MISSING and re-run snctl diag doctor before continuing. If the problem persists, contact SambaNova Support.

Do not skip this step. snctl does not re-check dependencies at the point of use, so a missing tool surfaces later as a failed power or firmware operation — and the error often points at the device or the credential rather than at the missing tool.

Step 4. Secure your encryption key

Your encryption key is at <config-directory>/encryption.key. It is generated once, during config init, and it is the only thing that can decrypt the device credentials you store. You need it to:

Decrypt your secrets
Run commands on your infrastructure

Anyone with access to your encryption key can decrypt all stored secrets. Protect this file accordingly — do not copy it to shared storage, commit it to version control, or include it in support bundles.

Updating configuration (optional)

Both settings below are optional and can be changed at any time after initialization. If you passed --service-account during Step 1, you do not need this section.

GCS service account

snctl config update --service-account /path/to/service-account.json

Pass an empty string to clear it:

snctl config update --service-account ""

The active path is shown as Service Account in snctl config show.

Firmware cache location

Firmware images that snctl downloads on your behalf are cached locally, by default under your system’s standard cache directory. Override it if you need the cache on a larger or shared volume:

snctl config update --cache-location /data/snctl-cache

Pass an empty string to reset to the default:

snctl config update --cache-location ""

The active location is shown as Cache Location in snctl config show.

Security considerations

Be aware of the following current limitations. See also Step 4 on protecting your encryption key.

Access control

Anyone with access to snctl has full permissions to manage all infrastructure.

snctl does not currently support role-based access control (RBAC). This means:

All users with snctl access can perform all operations
No separation between read-only and write permissions
No distinction between monitoring and power operations
Network administrators and system administrators cannot be separated

Audit and logging

snctl does not currently maintain an audit log of who performed which operations.

Next step

Add your racks to the inventory. See Rack administration.

Getting Started

Service Administration

Hardware Administration

Reference Architecture

Resources

Initial setup

Global flags

Step 1. Initialize configuration

What gets created

Initialization flags

(Optional) Using a custom configuration directory

Step 2. Verify the setup

Step 3. Verify required dependencies

Step 4. Secure your encryption key

Updating configuration (optional)

GCS service account

Firmware cache location

Security considerations

Access control

Audit and logging

Next step

​Global flags

​Step 1. Initialize configuration

​What gets created

​Initialization flags

​(Optional) Using a custom configuration directory

​Step 2. Verify the setup

​Step 3. Verify required dependencies

​Step 4. Secure your encryption key

​Updating configuration (optional)

​GCS service account

​Firmware cache location

​Security considerations

​Access control

​Audit and logging

​Next step

Global flags

Step 1. Initialize configuration

What gets created

Initialization flags

(Optional) Using a custom configuration directory

Step 2. Verify the setup

Step 3. Verify required dependencies

Step 4. Secure your encryption key

Updating configuration (optional)

GCS service account

Firmware cache location

Security considerations

Access control

Audit and logging

Next step