Environment variables
Environment variables the Go daemon and CLI actually read. Precedence: env var > config file > default.
Two read paths exist:
- Direct reads:
os.Getenv/os.LookupEnvat specific call sites (most rows below). - Koanf env mapping: the config loader additionally maps
SHC_*vars onto dotted config keys (SHC_FOO_BAR→foo.bar), with an explicit override table for keys whose names contain underscores (envOverrideMap,core/config/config.go):SHC_KEYCLOAK_REALM→keycloak.realm,SHC_KEYCLOAK_CLIENT_ID→keycloak.client_id,SHC_KEYCLOAK_CLIENT_SECRET→keycloak.client_secret(plusSHC_LOG_LEVEL/SHC_LOG_FORMATbelow). A grep foros.Getenvalone misses these.
Path Overrides
Section titled “Path Overrides”| Variable | Purpose | Default |
|---|---|---|
SHC_BASE_DIR | Base directory (root of all SHC paths) | auto |
SHC_STATE_HOME | State directory | XDG default |
SHC_CACHE_HOME | Cache directory | XDG default |
SHC_RUNTIME_DIR | Runtime directory | XDG default |
SHC_LOGS_DIR | Logs directory | XDG default |
SHC_TMP_DIR | Temp directory | <state home>/tmp |
SHC_STAGING_DIR | Scratch area for large operations: each backup run’s tree (<staging_dir>/backup/<id>), including converter output, the staged snapshot manifest, component tars, and the master archive, and each backup create --file archive until the CLI takes it (<staging_dir>/export/<id>.bak) | <state home>/staging |
SHC_DATABASE_PATH | Database path | auto |
SHC_SOCKET_PATH | Unix socket path | auto |
SHC_PID_PATH | PID file path | auto |
One staging dir per node
Section titled “One staging dir per node”SHC_STAGING_DIR must be node-local. Every node’s export sweep deletes each
archive under <staging_dir>/export that its own daemon doesn’t hold, so a
staging dir shared between nodes loses the backup create --file exports
other nodes hold.
Keeping a large capture off the root volume
Section titled “Keeping a large capture off the root volume”A scheduled backup’s peak disk footprint is not bounded by the size of
the deployment on disk. A source-less converter fetches from somewhere
else entirely (apps/standalone/external-s3 runs aws s3 sync against
a bucket), and the run then builds a component tar from that output and a
master archive from the tar, dropping the tar only once the master
exists. For a 55.7 GiB bucket the peak approaches three times the corpus.
By default all of it lands under the state home, beside the retained archives and the control-plane database, so a capture that outgrows the volume takes the node’s other deployments down with it. The two knobs split that peak onto filesystems with headroom:
SHC_STAGING_DIR=/mnt/big/shc-staging # run trees: converter corpus, staged manifest, tars, master archiveSHC_TMP_DIR=/mnt/big/shc-tmp # other short-lived temp (not the converter corpus)The headroom a converter needs (an external-s3 bucket sync can be tens
of GiB) is SHC_STAGING_DIR’s: converter output and the staged manifest
live under each run’s tree at <staging_dir>/backup/<id>. Set the knobs
in the daemon unit’s environment and restart shcd. Neither moves any
existing archive: retained backups stay where backup.repo puts them,
and retention is untouched.
Context Variables
Section titled “Context Variables”Default resolution context for CLI commands.
| Variable | Purpose | Default |
|---|---|---|
SHC_TENANT | Default tenant | default |
SHC_ENVIRONMENT | Default environment | prod (Community: default) |
SHC_STACK | Default stack | none |
SHC_ENVIRONMENT is consulted by every verb that addresses a single
deployment, below an explicit -e/--environment and above the edition
default. Unset, verbs resolve the edition default: prod on SHC
Enterprise, default on Community. The master tenant is reserved to
default regardless, and the listing verbs (shc ls, shc status,
shc backup ls) treat an unset value as “every environment” rather than
defaulting it. See the glossary.
Server / Networking
Section titled “Server / Networking”| Variable | Purpose |
|---|---|
SHC_HOST | Public host of this SHC install; keycloak/OTEL URLs derive from it. |
SHC_PORT | Public listener port. |
SHC_URL | Server URL the CLI client connects to. |
SHC_ADVERTISE_ADDR | Address this node advertises to cluster peers. |
SHC_INTERNAL_TOKEN | Shared token for the internal (peer/LAN) API listener. |
SHC_UDS_GROUP | Unix-domain-socket owning group (who may talk to the daemon locally). |
SHC_RQLITE_BIND_ADDR | IPv4 the raft engine (rqlited) binds and advertises (cluster mode). |
SHC_RQLITE_HTTP_ADDR | rqlited HTTP API bind address override (cluster mode). |
SHC_RQLITE_RAFT_ADDR | rqlited raft bind address override (cluster mode). |
SHC_RQLITED_BIN | Path to the rqlited binary (else PATH, then the packaged path). |
SHC_NODE_PUBLIC_ADDRESS | Operator override for this node’s detected public address (recorded on the node row; wins over cloud-metadata detection). |
Behavior / Logging
Section titled “Behavior / Logging”| Variable | Purpose | Default |
|---|---|---|
SHC_DEV | Dev mode when 1 (also SHC_MODE=dev). | off |
SHC_MODE | dev enables dev mode. | none |
SHC_LOG_LEVEL | Log level (debug/info/warn/error). | info |
SHC_LOG_FORMAT | Log format (e.g. json, text). | auto |
SHC_OUTPUT | CLI output format (tty, json, …). | tty |
SHC_FIELDS / SHC_FILTER / SHC_EXCLUDE | CLI output field shaping / row filtering. | none |
SHC_DEBUG | CLI debug mode (same as --debug/-d). | off |
SHC_VERBOSE | CLI verbose output (same as --verbose/-v). | off |
SHC_STORE_LEADER_REPORT | A duration, such as 60s. shcd logs, once per duration, the store reads and writes it sent to the raft leader, by the call site that made each. | off |
Secrets / Backends
Section titled “Secrets / Backends”All vault-resolvable; these seed the value when set directly.
| Variable | Config equivalent | Purpose |
|---|---|---|
SHC_VAULT_PASSWORD | none | CLI only (shc init, shc vault). Setting it in shcd’s environment is refused at start (X400975VLTRFE). shcd reads a credential file: systemd LoadCredential=vault-unlock ($CREDENTIALS_DIRECTORY/vault-unlock), or /etc/shc/vault-unlock mode 0600 on launchd. |
SHC_BACKUP_REPO | backup.repo | Restic repository. |
SHC_BACKUP_PASSWORD | backup.password | Restic repository password. |
SHC_KEYCLOAK_REALM | keycloak.realm | Keycloak realm override (koanf mapping). |
SHC_KEYCLOAK_CLIENT_ID | keycloak.client_id | Keycloak admin client id (koanf mapping). |
SHC_KEYCLOAK_CLIENT_SECRET | keycloak.client_secret | Keycloak admin client secret (koanf mapping). |
SHC_CLIENT_ID | none | CLI-only: confidential client id for shc auth --client-credentials (with SHC_CLIENT_SECRET). Not a config override; use SHC_KEYCLOAK_CLIENT_ID for that. |
SHC_CLIENT_SECRET | none | CLI-only: confidential client secret for the --client-credentials grant. |
Deployment / Apps
Section titled “Deployment / Apps”| Variable | Purpose |
|---|---|
SHC_MODULES | Override the set of modules deployed at init; empty means none. |
SHC_BUNDLED_APPS_DIRS | Extra directories scanned for bundled app definitions. |
SHC_NODE_LOCATION | This node’s location, used at boot only while its row has none (no --location at init or join, none set by shc node update); ahead of cloud metadata. Lowercase letters, digits, ., _, -. |
SHC_NODE_CLOUD | Who runs this node, on the same terms as SHC_NODE_LOCATION, ahead of the metadata probe that answered. |
SHC_COMPOSE_NO_WAIT / SHC_STACK_NO_WAIT | Skip --wait convergence on compose/stack ops. |
SHC_INSTALL_POLL_MS | Install progress poll interval (ms). |
SHC_DEPLOY_IMAGE_KEEP | Superseded images each service keeps for rollback after a compose deploy (default 1, 0 keeps none, off disables the removal). Any other value also disables it and logs X500122DEPIMU. Podman runs no pass. On a docker engine with the containerd image store the deploy records the reserve and removes nothing, and the node’s image prune removes what falls off it. The node’s image prunes (image_prune_cron and the leader’s hourly cleanup) never remove an image in any deployment’s reserve. |
SHC_HOSTRUN | always / never: override the host-run probe for storage host commands (tests, unusual hosts). |
shc hud is x9s with the SHC provider. It inherits the same endpoint
vars as every other command (SHC_URL, SHC_SOCKET_PATH,
SHC_AUTHORIZATION / SHC_TOKEN). Config lives under
<user-config-dir>/shc9s unless $K9S_CONFIG_DIR is set. The retired
bubbletea HUD’s SHC_HUD_* vars are gone with it.
Test-only
Section titled “Test-only”SHC_TEST_DB_URL, SHC_TEST_LIB, SHC_TEST_TMP_ROOT,
SHC_SYSTEM_RUN (hermetic override for the system runtime dir),
SHC_COMPLETION_DEBUG, SHC_COMPLETION_TIMEOUT are used by the test/dev
harness and shell completion.
These govern shc test run on a node. The run sets the last two for its
suite; nothing else should.
| Variable | Purpose |
|---|---|
SHC_TEST_RUN_DIR | Directory holding one lock file per shc test run started on this node (default /tmp/shc-test-runs). A run holds its lock while it runs; a lock nobody holds is a run that ended without its teardown, and the next run on the node, or shc test cleanup, removes what it made. Deliberately not derived from $TMPDIR, because each concurrent run gets a TMPDIR of its own and a sweep has to see every run. |
SHC_TEST_RUN | The run the suite belongs to (shctest-<8 hex>). Every shc install the suite runs labels its deployment test-run=<run>, which is how the run’s teardown and the sweep find them, in the run’s tenant or, where tenancy is not licensed, in the node’s own. |
SHC_TEST_APP | The app under test, <name>=<absolute directory>. An unpinned shc install <name> installs that directory instead of the catalogue’s package of the same name, and an unpinned shc install <name>/<member> (a vapp or add-on, such as postgres/database) installs that member of the directory. |
SHC_TEST_GRANTS | The run’s grant ledger, <SHC_TEST_RUN_DIR>/<run>.grants. A run’s deployments carry its name, so no operator can grant them ahead: shc_run gives the run’s own deployment the socket class shc run needs, when it holds no grant row yet, and writes the key here first. The run’s teardown, the sweep and shc test cleanup revoke every key the ledger names. |
XDG Variables
Section titled “XDG Variables”SHC respects the XDG Base Directory Specification for non-root path defaults:
XDG_CONFIG_HOME(default:~/.config): config file directoryXDG_DATA_HOME(default:~/.local/share): state directoryXDG_CACHE_HOME(default:~/.cache): cache directoryXDG_RUNTIME_DIR(no default): runtime directory