Configuration
SHC configuration comes from two sources:
- Config files: static file-based config loaded at startup (server definitions, pre-DB settings)
- Database: user-managed scoped config (runtime settings, feature flags)
Config Files
Section titled “Config Files”Config files are loaded and merged in this order (lowest to highest priority):
default.yaml: bundled vendor defaults (in the package)/etc/shc/config.yaml: system-wide config/etc/shc/config.d/*.yaml: system drop-ins (alphabetical order)~/.config/shc/config.yaml: user-specific config (non-root only)dev.yaml: developer overrides (dev mode only)
Server Definitions
Section titled “Server Definitions”Config files define named server profiles for the CLI client:
servers: local: url: unix:///run/shc/shc.sock prod: url: https://prod.example.com token: ${SHC_PROD_TOKEN} timeout: 60 tls: ca: /etc/shc/ca.pem insecure: false staging: url: https://staging.local tokenExec: pass shc/staging-tokenValue Resolution
Section titled “Value Resolution”${ENV_VAR}: expands environment variables in string valuestokenExec: executes a shell command, uses stdout as the auth token
Switching Servers
Section titled “Switching Servers”# Set active server (stored in context.json)shc ctx --server prod
# Show current context (includes server)shc ctxPriority
Section titled “Priority”For overlapping keys, the cascade is: CLI flags > env vars > DB config > config files > defaults.
Config files define things needed before the database is available (server URLs, listen address, TLS). Database config handles runtime settings that benefit from scoped inheritance.
Scope Hierarchy
Section titled “Scope Hierarchy”Database-backed config resolves through the one SHC scope ladder
(core/scope). The most specific wins, always ending at Global:
flowchart TB G["Global (base)"] --> T["Tenant (tenant)"] T --> E["Environment (tenant + environment)"] T --> S["Stack (tenant + stack)"] S --> D["Deployment (tenant + stack + environment)"]Stack outranks Environment. Deployment = Stack + Environment together. The same ladder orders vault secret resolution. See config-keys.md § Precedence for the CLI flags that target each tier.
Setting Values
Section titled “Setting Values”# Global configurationshc config set backup.retention.daily 7 --scope global
# Tenant-specificshc config set backup.retention.daily 14 --scope tenant --tenant acme
# Environment-specificshc config set launcher false --scope environment --tenant acme --environment prod
# Stack-specificshc config set concurrency.queue_max_depth 2000 --scope stack --tenant acme --stack nextcloud
# Deployment-specific (most specific: tenant + stack + environment)shc config set launcher false --scope deployment -t acme -s nextcloud -e prodReading Values
Section titled “Reading Values”# Get effective value (with cascade)shc config get backup.retention.daily
# Get from a specific scope onlyshc config get backup.retention.daily --scope tenant --tenant acme
# List all configshc config lsshc config ls --scope globalCommon Settings
Section titled “Common Settings”# Backup retention (restic forget policy)shc config set backup.retention.daily 7 --scope globalshc config set backup.retention.weekly 4 --scope global
# Launcher button (per-app default overridable per scope)shc config set launcher false --scope tenant --tenant acme
# DNS provider selectionshc config set dns.provider cloudflare --scope globalRate limits are yaml-only
Section titled “Rate limits are yaml-only”rate_limit.* cannot be set in the database. shc config set refuses every
key under it:
shc config set rate_limit.requests 200 --scope global# shc: [X400050CFGSTP] config key rate_limit.requests can only be set in yaml config filesSet the block in a drop-in file instead. Each node’s daemon reads its own files and limits its own TCP listener, so write the file on every node:
rate_limit: requests: 200 window: 30The daemon watches its config files and applies a changed rate_limit block
without a restart. The keys and their defaults are in
config-keys.md § rate_limit.
Hot-Reloadable Settings
Section titled “Hot-Reloadable Settings”A few keys apply without a daemon restart; most operational changes take effect on the next reconcile / scheduler cycle.
| Setting | Behavior |
|---|---|
rate_limit.* | Set in yaml config files only, and on outside dev mode. The daemon reloads the block when those files change; the database store holds no rate_limit value, so it is never consulted. |
concurrency.queue_max_depth | Hot-reloadable. |
launcher | Resolved per request through the scope cascade. |
backup.retention.* | Applied on the next retention run. |
crons.* | Applied on the next scheduler cycle. |
Restart Required
Section titled “Restart Required”| Setting | Reason |
|---|---|
keycloak.* | Auth client wired at startup. |
otel.* | OTLP exporter (incl. the managed default’s auth) engages on next restart. |
Secret References
Section titled “Secret References”Config values can reference vault secrets:
shc config set backup.password 'ref+vault://backup/password' --scope globalshc config set keycloak.client_secret 'ref+vault://keycloak_client_secret' --scope globalA reference is dereferenced when the value is read. For
backup.password a reference that cannot resolve (locked vault, absent
key) refuses rather than falling back to the literal string, so store
the secret first (shc vault set backup/password) and set
backup.repo in the same pass: the two are required together.
On a cluster bootstrapped after the backup-key lane you do not do this
by hand. shc init seals a generated key (or the one you supplied with
--backup-password / --backup-password-file) into the vault at
backup/password and points backup.password at it. backup.repo still
has no default and is yours to set.
Never edit backup.password to change an in-use key. The row and the
repository must change together; editing only the row leaves a repository
that opens under a key SHC no longer presents, and every backup fails.
Use shc backup key rotate, which does both in one operation and adds
the new key before removing the old, so an interruption leaves the
repository openable by both rather than neither.
See Also
Section titled “See Also”configmodule: cascade, scopes, secret references, system vs scoped keys- Environment Variables
- Vault System