Skip to content
SHC Docs

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.LookupEnv at 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 (plus SHC_LOG_LEVEL/SHC_LOG_FORMAT below). A grep for os.Getenv alone misses these.
VariablePurposeDefault
SHC_BASE_DIRBase directory (root of all SHC paths)auto
SHC_STATE_HOMEState directoryXDG default
SHC_CACHE_HOMECache directoryXDG default
SHC_RUNTIME_DIRRuntime directoryXDG default
SHC_LOGS_DIRLogs directoryXDG default
SHC_TMP_DIRTemp directory<state home>/tmp
SHC_STAGING_DIRScratch 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_PATHDatabase pathauto
SHC_SOCKET_PATHUnix socket pathauto
SHC_PID_PATHPID file pathauto

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 archive
SHC_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.

Default resolution context for CLI commands.

VariablePurposeDefault
SHC_TENANTDefault tenantdefault
SHC_ENVIRONMENTDefault environmentprod (Community: default)
SHC_STACKDefault stacknone

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.

VariablePurpose
SHC_HOSTPublic host of this SHC install; keycloak/OTEL URLs derive from it.
SHC_PORTPublic listener port.
SHC_URLServer URL the CLI client connects to.
SHC_ADVERTISE_ADDRAddress this node advertises to cluster peers.
SHC_INTERNAL_TOKENShared token for the internal (peer/LAN) API listener.
SHC_UDS_GROUPUnix-domain-socket owning group (who may talk to the daemon locally).
SHC_RQLITE_BIND_ADDRIPv4 the raft engine (rqlited) binds and advertises (cluster mode).
SHC_RQLITE_HTTP_ADDRrqlited HTTP API bind address override (cluster mode).
SHC_RQLITE_RAFT_ADDRrqlited raft bind address override (cluster mode).
SHC_RQLITED_BINPath to the rqlited binary (else PATH, then the packaged path).
SHC_NODE_PUBLIC_ADDRESSOperator override for this node’s detected public address (recorded on the node row; wins over cloud-metadata detection).
VariablePurposeDefault
SHC_DEVDev mode when 1 (also SHC_MODE=dev).off
SHC_MODEdev enables dev mode.none
SHC_LOG_LEVELLog level (debug/info/warn/error).info
SHC_LOG_FORMATLog format (e.g. json, text).auto
SHC_OUTPUTCLI output format (tty, json, …).tty
SHC_FIELDS / SHC_FILTER / SHC_EXCLUDECLI output field shaping / row filtering.none
SHC_DEBUGCLI debug mode (same as --debug/-d).off
SHC_VERBOSECLI verbose output (same as --verbose/-v).off
SHC_STORE_LEADER_REPORTA 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

All vault-resolvable; these seed the value when set directly.

VariableConfig equivalentPurpose
SHC_VAULT_PASSWORDnoneCLI 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_REPObackup.repoRestic repository.
SHC_BACKUP_PASSWORDbackup.passwordRestic repository password.
SHC_KEYCLOAK_REALMkeycloak.realmKeycloak realm override (koanf mapping).
SHC_KEYCLOAK_CLIENT_IDkeycloak.client_idKeycloak admin client id (koanf mapping).
SHC_KEYCLOAK_CLIENT_SECRETkeycloak.client_secretKeycloak admin client secret (koanf mapping).
SHC_CLIENT_IDnoneCLI-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_SECRETnoneCLI-only: confidential client secret for the --client-credentials grant.
VariablePurpose
SHC_MODULESOverride the set of modules deployed at init; empty means none.
SHC_BUNDLED_APPS_DIRSExtra directories scanned for bundled app definitions.
SHC_NODE_LOCATIONThis 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_CLOUDWho 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_WAITSkip --wait convergence on compose/stack ops.
SHC_INSTALL_POLL_MSInstall progress poll interval (ms).
SHC_DEPLOY_IMAGE_KEEPSuperseded 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_HOSTRUNalways / 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.

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.

VariablePurpose
SHC_TEST_RUN_DIRDirectory 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_RUNThe 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_APPThe 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_GRANTSThe 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.

SHC respects the XDG Base Directory Specification for non-root path defaults:

  • XDG_CONFIG_HOME (default: ~/.config): config file directory
  • XDG_DATA_HOME (default: ~/.local/share): state directory
  • XDG_CACHE_HOME (default: ~/.cache): cache directory
  • XDG_RUNTIME_DIR (no default): runtime directory