> ## 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. # Initial setup Initialize your configuration directory, generate an encryption key, and verify the environment. This is **step 2** of the setup process: 1. Install SambaRack Manager software 2. **Initial setup and verification** — this page 3. [Add SambaRack to the inventory](srm-rack-admin) 4. [Configure device credentials](srm-device-credentials) *** ## Global flags These work with any `snctl` command and are useful throughout setup and daily use. | Flag | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--snctl-dir ` | Directory holding the configuration, inventory, and credentials (default `$HOME/.snctl`). Used verbatim — no `.snctl` segment is appended. Env: `SNCTL_DIR` | | `-o, --output ` | Output format: `text` (default), `wide`, or `json` | | `--log-level ` | Log level: `debug`, `info`, `warn`, or `error`. Env: `SNCTL_LOG_LEVEL` | *** ## Step 1. Initialize configuration Initialize SambaRack Manager with a single command: ```bash theme={} snctl config init --defaults --service-account ``` **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: ```text theme={} 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: ```text theme={} 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 ```text theme={} .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 to a GCS service account JSON file | ```bash theme={} # Recommended snctl config init --defaults --service-account /etc/snctl/sambanova-sa.json ``` This setting can also be changed after initialization — see [Updating configuration](#updating-configuration-optional). ### (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: ```text theme={} 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):** ```bash theme={} 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:** ```bash theme={} 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:** ```bash theme={} snctl version ``` ```text theme={} 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:** ```bash theme={} snctl config show ``` ```powershell theme={} 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 ```bash theme={} snctl diag doctor ``` Expected output when all dependencies are met: ```shellscript theme={} 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: ```shellscript theme={} 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 `/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](#step-1-initialize-configuration), you do not need this section. ### GCS service account ```bash theme={} snctl config update --service-account /path/to/service-account.json ``` Pass an empty string to clear it: ```bash theme={} 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: ```bash theme={} snctl config update --cache-location /data/snctl-cache ``` Pass an empty string to reset to the default: ```bash theme={} 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](#step-4-secure-your-encryption-key) 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](srm-rack-admin).