SambaRack Manager Initial Setup - SambaNova Documentation

This guide covers the initial setup and verification of SambaRack Manager software, which initializes your configuration directory, generates encryption keys, and creates the necessary files. The complete setup process is:

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

Initial setup

Follow these steps to initialize and verify your SambaRack Manager configuration.

Step 1. Initialize configuration

Run the initialization command to set up snctl:

snctl config init

This interactive wizard prompts you for:

Folder location (default: ~/.snctl): Where to store configuration files. This directory is created if it doesn’t exist.
Service account (optional): Service account for GCS access.
Logs location (optional): Where to store logs.

The initialization aborts if the provided folder location already contains configuration files.

After completion, your configuration directory contains:

.snctl/
  ├── config.yaml                 # Main configuration file
  ├── encryption.key              # AES-GCM encryption key to encrypt secrets.json.enc
  ├── inventory.json              # Your infrastructure inventory (empty initially)
  ├── logs/                       # Logs directory
  ├── private_key.json            # Private key for encrypting secrets during CLI operations
  ├── public_key.key              # Public key for encrypting secrets during CLI operations
  ├── secrets.json.enc            # Encrypted credentials (created with blank placeholders)
  └── secrets.json.enc.lock       # File lock for secrets file (created when accessing/updating secrets)

Step 2. Set environment variable (if using custom location)

If you chose a custom folder location during snctl config init (different from ~/.snctl), you see the following note at the end:

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=/path/to/custom/.snctl

Choose one of the following options: Option 1 - Set environment variable (recommended):

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

Option 2 - Use —snctl-dir flag with each command:

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

If the path used with either option doesn’t end with .snctl, the CLI automatically appends .snctl to it. For example, SNCTL_DIR=/home/user/myconfig uses /home/user/myconfig/.snctl.

Step 3. Verify the setup

After initialization, verify that everything is properly configured: Verify snctl is working:

snctl --version

Expected output:

0.0.5 # Exact version may vary

Display current configuration:

snctl config show

This command displays key information from your .snctl/config.yaml. Expected output:

                       Current Configuration
+---------------------+-------------------------------------------+
| Setting             | Value                                     |
+---------------------+-------------------------------------------+
| Folder Location     | /home/user1/.snctl                        |
| Encryption Key File | /home/user1/.snctl/encryption.key         |
| Inventory File      | /home/user1/.snctl/inventory.json         |
| Service Account     | None                                      |
| Logs Location       | /home/user1/.snctl/logs                   |
| Version             | 0.0.5                                     |
| Last Updated        | 2025-12-08T11:19:27.403696Z               |
+---------------------+-------------------------------------------+

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

Check created files:

# Replace ~/.snctl with your actual path if using a custom location
ls -l ~/.snctl

Expected output:

total 48
-rw-r--r--  1 user1 user1   234 Dec  8 11:19 config.yaml
-rw-------  1 user1 user1    32 Dec  8 11:19 encryption.key
-rw-r--r--  1 user1 user1     2 Dec  8 11:19 inventory.json
-rw-r--r--  1 user1 user1   128 Dec  8 11:19 secrets.json.enc
-rw-r--r--  1 user1 user1     0 Dec  8 11:19 secrets.json.enc.lock
-rw-r--r--  1 user1 user1  1674 Dec  8 11:19 private_key.json
-rw-r--r--  1 user1 user1   451 Dec  8 11:19 public_key.key
drwxr-xr-x  2 user1 user1  4096 Dec  8 11:19 logs

Step 4. Verify required dependencies

Verify that all required dependencies are installed:

snctl doctor

For more information, see snctl doctor.

Step 5. Secure your encryption key

Store your encryption key securely. The encryption key is required 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.

Security considerations

SambaRack Manager currently has the following security limitations that you should be aware of.

Access control

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

Currently, snctl does not 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 admins and SysAdmins cannot be separated

Audit and logging

Currently, snctl does not maintain an audit log of who performed what operations.

Next step

After completing the initial setup, add your racks to the SambaRack Manager inventory. See Rack Administration.

Getting Started

Service Administration

Hardware Administration

Reference Architecture

Resources

Initial setup

Initial setup

Step 1. Initialize configuration

Step 2. Set environment variable (if using custom location)

Step 3. Verify the setup

Step 4. Verify required dependencies

Step 5. Secure your encryption key

Security considerations

Access control

Audit and logging

Next step

​Initial setup

​Step 1. Initialize configuration

​Step 2. Set environment variable (if using custom location)

​Step 3. Verify the setup

​Step 4. Verify required dependencies

​Step 5. Secure your encryption key

​Security considerations

​Access control

​Audit and logging

​Next step

Initial setup

Step 1. Initialize configuration

Step 2. Set environment variable (if using custom location)

Step 3. Verify the setup

Step 4. Verify required dependencies

Step 5. Secure your encryption key

Security considerations

Access control

Audit and logging

Next step