Config keys reference
Every configuration key recognized by the Go daemon, with its default. Keys
resolve through the scoped cascade (deployment → stack → environment → tenant
→ global). Set any key via shc config set <key> <value> (add --scope and
context flags to target a tier) or, for a subset, an environment variable
(see environment-variables.md).
A key is not writable at every scope. Since v0.0.27 the keyspace records
where each key is read and when a write takes effect, and a write to a
scope no reader would ever consult is refused rather than stored:
X400066CFGSCP names the scopes the key is read at. A neighbouring refusal
comes from the same registry: X409072CFGOWN (the key is state owned by a
command, so --config-set will not write it). A row that is stored but whose
effect is deferred reports X400037CFGINR, and one whose read sites SHC
cannot determine reports X400043CFGUND. Writes that previously returned
success while being permanently inert now fail loudly; see the v0.0.27
upgrade note in CHANGELOG.md.
Mirrors core/config/default.yaml.
Every key below traces to a real read site in the Go daemon; the Python-era
sections (api, limits, sse, websocket, collector, logs,
database, deploy, mounts, the old flat timeout, and keycloak.url /
keycloak.realm) were removed: they have zero readers in the Go port.
keycloak.client_secret and keycloak.swagger_client_id were listed here
until 2026-08-07 and were removed for the same reason, late: neither ever had
a reader. client_secret was the more misleading of the two: this page told
operators to point it at a vault ref, which left them believing the daemon
authenticated as a confidential OIDC client when it stayed a public
one. The keys are gone from ce’s default.yaml.
This page is now checked. make lint runs lint/config-keys-doc
(scripts/check-config-keys-doc.go), which fails the build when a key
documented here is one ce does not declare, and reports (under a ceiling that
may only fall) the declared keys this page never names. The declared set is
derived from ce at the pin in go.mod: the embedded default.yaml, the
code-owned section claims, the readerscan reader index, and the key names
written into ce/shc source. Two consequences worth knowing. A ce-side key
change is invisible to that check until the pin moves, so this page can be
stale in ce’s favour without going red, and the check prints the pin it
measured so you can tell. And a row is still only as strong as the evidence
behind it: default.yaml declaring a key is not proof that anything reads it,
which is exactly how keycloak.client_secret survived. The check names the
rows resting on that weakest evidence rather than passing them silently.
Sections
Section titled “Sections”- Top-level scalars
keycloakrate_limittimingcronstimeoutsmaintenancebackupconcurrencydeployacmednsvaultotelnotificationstorageschedulerhealthclusterstoreconsolerepos/clusters
Top-level scalars
Section titled “Top-level scalars”| Key | Type | Default | Notes |
|---|---|---|---|
dev | bool | false | Development mode. |
launcher | bool | true | Inject the SHC launcher button into gated apps’ HTML. Resolved through the scope cascade; global kill-switch is shc config set launcher false. |
launcherGzip | bool | true | Whether the launcher injector may rewrite a compressed HTML response. Off, a backend that answers Content-Encoding: gzip streams through untouched, so the button is absent for every browser and present for every curl-shaped check. On, the document is decompressed, injected and re-compressed on navigations only (assets, JSON, images, redirects and streams are rejected before any gzip work), roughly 3–4× the identity path per document. shc config set launcherGzip false buys that back at the cost of the button on gzip-serving apps; shc config set launcher false removes the middleware entirely. Same scope cascade as launcher, re-resolved by the ingress sweep. |
ssoAutoRedirect | bool | false | Whether a logged-out browser asking for an app’s login page is sent straight into that app’s own OIDC flow instead of being shown the login form with a “Sign in with SSO” button on it. Same scope cascade as launcher. UX sugar, never enforcement: access stays open and nothing is blocked. Reaches an app two ways: an app declaring sso_redirect: in its app.yaml gets a sibling Traefik router (escape hatch <login page>?sso=false, which rides the router rule, so a broken IdP cannot lock out a local admin), but only while the deployment holds a connected or post_deployed oidc or saml edge (shc integration ls), since an app never bound to an IdP serves no SSO entry to redirect to; an app with a native auto-login knob has the resolved value published into its render context as sso_auto_redirect and gates on vars.<knob> or sso_auto_redirect, so either this key or the app’s own --var arms it. The two are additive: a false var cannot be told apart from an unset one, so exempt one deployment with shc config set --deployment <d> ssoAutoRedirect false, not with a var. It deliberately does not arm six apps whose knob removes the credential login form rather than redirecting to it: gitea, matrix, wazuh (oidc.autoRedirect), journiv (oidcOnly), vaultwarden and penpot (ssoOnly). Each declares that in app.yaml’s local_login.closed_by:, and a fleet-wide redirect preference must never take a lockout decision. Those six stay on an explicit per-app --var. |
launcherPlaced | bool | true | Whether a deployment is a launcher DESTINATION at all, that is, whether it gets a TILE. The three launcher keys divide cleanly: launcher decides whether a page CARRIES the button, launcherEnvironment decides what the list SHOWS, and this one decides whether a deployment is IN the list. It exists for the app whose routed host is meant to be embedded rather than opened (an iframe sidecar still needs a URL like any other app), which declares launcher_placed: false in its app.yaml; this key is the operator’s override over that per-app default, in both directions, so shc config set launcherPlaced true --scope deployment -t corp -s tool -e prod places an app the catalogue opted out. Bool grammar, same scope cascade as launcher: a row at any tier wins outright; otherwise the app.yaml default decides; absent everywhere means placed. Anything outside the bool grammar is refused rather than stored, because a value that cannot be resolved is indistinguishable from no row. Resolved PER DEPLOYMENT by the clusterfs licence section (within a minute), which stamps "placed": false on the deployment’s apps.json entries; the entries are never dropped, because that same file is the plugin’s authority for which tenant owns a host. So an unplaced host keeps its tenant resolution and keeps the launcher on its own pages; only the LIST loses the tile. Two sweeps deep before a browser sees a write: the daemon’s 60 s apps-menu tick, then the proxy’s own 30 s apps.json cache TTL. |
launcherEnvironment | str | auto | Which environment’s deployments the launcher LISTS. auto now lists EVERY environment: it is an alias for all. Owner ruling of 2026-08-16, retracting his own environment scoping: “Take that back. No. My default, just everything. Like, actually, everything, everything. That’s the default, and that’s what I want.” auto used to list only the environment of the host the page was served from, and because it is also the shipped value that scoping WAS the default, so the retraction had to land on this value, not merely on the empty one. This does not multiply icons: the launcher draws one tile per STACK, pointing at the deployment the tenant’s environmentPrecedence order ranks first, and the other environments ride that tile’s right-click / long-press menu. Widening here is what FEEDS that menu. Name an environment (prod, staging, …) to pin the list regardless of where it is viewed from: an explicitly named environment is the only value that still filters; all (or *) lists every environment and is how a lower scope climbs back out from under a higher one, the cascade having no “unset me” value. default and the empty environment are the same environment; matching is case-insensitive. Resolved through the scope cascade PER DEPLOYMENT by the clusterfs licence section (within a minute) and evaluated by the Traefik plugin, because auto depends on the request host and one apps.json serves every host. It filters the LIST only: it never takes the launcher off a host, and a host in an unlisted environment still gets the switcher, showing it the listed environment’s apps. |
lanEnforcement | str | allowlist | Whether exposure: lan blocks anything. Until this key existed it did not: exposure only chose which address managed DNS publishes, while Traefik still answered the deployment’s hostname on the node’s public IP, as measured on a live estate, where a lan deployment answered 401 to a request from the open internet, and a 401 is the gate answering, which means the packet arrived. allowlist chains a per-deployment ipAllowList middleware in front of every router the deployment renders, including the ungated carve-outs, the auth callback/logout routers and the SSO-redirect routers, which are the ones with no gate behind them. Only off (any case) disarms. Anything else, including a typo, the empty string and no row at all, reads as allowlist (SHC-161): a LAN deployment must never answer the internet because its row was absent or malformed. The router reads config rows only, so a value in a config file or SHC_* env is never enforced; set it with shc config set. With no row, shc config get lanEnforcement prints allowlist, adds a “shipped default” note on a terminal, and --show-origin gives source: default versus source: row (SHC-1066). The axis it reads is exposure != internet: an unset exposure is restricted, matching the install-time default. Scoped through the ordinary 5-level cascade and re-read by the 60 s ingress sweep, so arming and disarming are one config write and one sweep with no reinstall. ★ Arming this can lock an operator out of the estate he would use to fix it: confirm you reach the estate from inside the derived set (shc config get lanAllowlistCidrs, plus the node addresses) before turning it on. |
lanAllowlistCidrs | str | unset | Extra source CIDRs admitted when lanEnforcement is allowlist, comma- or whitespace-separated. It is added to the derived set, never a substitute, so naming your laptop’s VPN pool cannot amputate the estate’s own container plane. The derived half is the Traefik host’s own non-public interface networks plus every cluster node’s internal address (a /32 per node on most providers, so the host’s own prefix does not cover its siblings). The fabric range is carved out of it and three kinds of fabric address go back: the pins of the route’s own tenant and of the system tier, on every node, and the Traefik node’s own fabric address (shc0’s), which a request typed on that node wears. Another node’s fabric address never does: every client that node forwards wears it, an internet client’s included. This key is the only way to admit a path the estate cannot see for itself: a WireGuard transit, an OpenVPN pool, a netbird network the nodes have not joined. Not an RFC1918 constant: 10.0.0.0/8 on a shared provider private network would admit any neighbour who can route. Same scope cascade and same 60 s sweep as lanEnforcement. Arming lanEnforcement also makes the launcher and the console grey a deployment a viewer’s network cannot reach (the derived ranges are published onto apps.json as lan/lanset; see the launcher flow doc §29). That is presentation only. The ipAllowList middleware is still the only thing that refuses anything, and it discloses which hosts are private to a viewer who could already learn it by clicking. |
keycloak
Section titled “keycloak”Managed-only. The Keycloak URL is derived from the system Keycloak’s host,
modules.keycloak.host or else SHC_HOST, and its path: /auth on the
shared SHC_HOST, the root on a dedicated host (ce
modules/app/system_apps.go). There is no url, realm or internal_url
key. keycloak.base_path below only moves where the daemon looks.
| Key | Type | Default |
|---|---|---|
keycloak.client_id | str | shc-api |
keycloak.base_path | null | str | null: the path the daemon’s own auth client puts in front of /realms/<realm>: the issuer it checks tokens against and the Keycloak endpoints it calls. Null follows the path the system Keycloak serves under (modules.keycloak.base_path when set, else /auth on the shared host or the root on a dedicated one). Setting it moves the daemon’s side only, never the container or its route, so any value other than the served path sends every token check to a path Keycloak does not answer. Leave it unset. To move Keycloak, set modules.keycloak.base_path, which moves the container, the route and the daemon together. Global scope, read on every call (ce daemon/services.go). |
keycloak.tls_verify | bool | true (set false only for self-signed dev stacks) |
keycloak.access_token_lifespan | int (seconds) | 14400 (4 h), seeded on every realm SHC provisions, overriding Keycloak’s own 300 s. Global scope, live activation: the leader writes a change onto every realm on its next reconcile pass. See token lifespans. |
keycloak.sso_session_idle_timeout | null | int (seconds) | null: SHC asserts nothing, so the realm keeps whatever it has (Keycloak ships 1800 s). Set it to make the provisioner enforce a value. Global scope, live activation: the leader writes a change onto every realm on its next reconcile pass. See token lifespans. |
keycloak.sso_session_max_lifespan | null | int (seconds) | null: SHC asserts nothing, so the realm keeps whatever it has (Keycloak ships 36000 s, 10 h). Every SSO session ends at it however active it is, so an idle timeout above it is cut short. shc config set refuses a value below keycloak.sso_session_idle_timeout (X400068CFGMIN). Global scope, live activation. See token lifespans. |
keycloak.offline_session_idle_timeout | null | int (seconds) | null: the realm keeps whatever it has (Keycloak ships 2592000 s, 30 days). How long an offline session, the refresh token shc auth login gets with offline_access, may go unused. Global scope, live activation. |
keycloak.login_theme | null | str | null means shc, shc’s own login theme, which ships in SHC’s Keycloak image. It is Keycloak’s keycloak.v2 page with Remember me ticked on a fresh sign-in, and after a failed sign-in the box keeps what the person chose. Every cluster wears it unless it names another theme (Clay’s ruling rv_b9cce3467c0cd454, FZ-8490). A named theme wins: shc-springboard for the SHC springboard skin (the launcher’s navy wallpaper, glass plate and per-realm glyph) or platform-keycloak for the house look, both in the theme jar inherited from the multiplatform Keycloak base image, or keycloak.v2 for the stock page. Asserted on master and every tenant realm on each reconcile pass. Global scope, live activation. Keycloak resolves a theme name when it renders, not when it is stored: a name the running image does not carry does not error; Keycloak logs Failed to find LOGIN theme <name>, using built-in themes and serves its built-in keycloak.v2 login page (HTTP 200). So an image older than the theme serves the stock page, never an outage. (Measured on Keycloak 26.7.0, 2026-08-23.) Names outside [A-Za-z0-9._-] are dropped rather than escaped, and nothing is stamped in their place. The admin API cannot clear loginTheme back to absent; to move a realm to another theme, set the key to it. |
keycloak.remember_me | bool | true: show Keycloak’s Remember me checkbox on the login form of every realm SHC provisions, so a user can opt into a persistent SSO session. Global scope, live activation. It is what makes the floating apps menu’s silent identity check (prompt=none in a hidden iframe) survive a browser restart: Keycloak’s SSO cookies are non-persistent by default, so the browser drops them on exit while the app underneath keeps its own long-lived cookie, so the menu then offers “sign in” to somebody who is plainly logged in, and every press costs a round trip. On by default because it changes no authorization behaviour and can regress nobody: an untouched checkbox leaves the session exactly as non-persistent as it is today, and the flag only makes the choice exist. Set false on an estate whose policy forbids persistent browser sessions. |
keycloak.brute_force_detection | bool | true: Keycloak’s brute force detection with a temporary lockout on every realm SHC provisions but master. Asserted in both directions, so false turns it off on each of those realms. Thresholds are Keycloak’s own: thirty wrong passwords in a row, or two inside a second, lock the account for a minute, so anyone who knows a username can keep it locked through any login page in front of the realm. Global scope, live activation. |
keycloak.admin_events_enabled | bool | true: record Keycloak admin events on master and every tenant realm SHC provisions, asserted on each reconcile pass in both directions (setting false writes false, so the off switch is a real one). Global scope, live activation. Keycloak ships this off, and off is invisible: a realm that is not recording answers the admin-events query with the same empty list a realm where nothing happened answers. The identity-broker’s outbox poller is the estate’s fast lifecycle path and reads exactly that endpoint, so with recording off it polls forever, never errors, and never sees a user disabled. The slow reconcile sweep still converges, leaving a ~15-minute lag and no signal anywhere. That silence is why it defaults on. It changes no auth behaviour (token issuance, sessions and authorization are untouched); the cost is event rows proportional to admin-API write volume, which is provisioning traffic, not login traffic. Set false only if you run your own audit pipeline and accept reconcile-only lifecycle propagation. |
keycloak.admin_events_details_enabled | bool | false: store the full JSON representation of each admin write alongside its event. Global scope, live activation, asserted in both directions like its sibling. Off is enough for the outbox consumer: an admin event already carries operationType, resourceType, resourcePath and authDetails, so it learns that users/<id> was written and by whom. Details adds the written representation itself (for a user write that is the user representation, attributes included), so leaving it off keeps personal data out of the event store. Set true if your compliance posture wants the payload; it costs storage in proportion to write size, not count. |
| Key | Type | Default & notes |
|---|---|---|
auth.gate_cookie_domain | enum (host | estate) | host: the Domain= scope of the forward-auth / plugin gate’s session cookie (shc_access_token). Global scope, daemon-restart activation; an unknown value is refused at set time (X400002VALINP names the accepted set). host (default) keeps the cookie host-only, one gate session per gated host: logging into twenty gated apps is twenty OIDC round trips and the floating apps menu re-authenticates across hosts. estate widens the cookie to a Domain= the daemon derives from the estate’s own ingress hosts (their shared registrable suffix, via the real Public Suffix List), so one login covers every gated host under it. The disclosure tradeoff, because estate is a real change: a Domain=-scoped cookie is sent by the browser to every host under the derived suffix, including hosts the estate does not itself serve (a parked name, a delegated subdomain). To make it safe the SHC edge strips the cookie before any app sees it, and the forward-auth sidecar refuses to widen unless it can prove the paired Traefik image carries that strip, falling back to host-only otherwise (the proof is SHC_FORWARD_AUTH_COOKIE_STRIP, set by the modules/traefik render from the gateCookieStrip image capability; an operator who repins images.traefik to a proxy without the strip must set gateCookieStrip: false). Even with the strip, an estate whose apex or shared suffix hosts names outside SHC’s control should confirm it fully owns that suffix before turning this on. Ships host for exactly that reason: the widening is opt-in, per estate, taken deliberately. estate needs both gates (this key and the proven strip) to actually widen; either alone keeps host-only. |
auth.platform_admins | string | "": declared platform admins, <tenant>/<user-id> entries (comma- or whitespace-separated) where <user-id> is the user’s Keycloak id (the sub claim), e.g. corp/3f0e9a52-7c1d-4e8b-9a61-2b5c8d4e7f10. Every realm render grants each named user platform:manage on that realm’s shc-access client, so the grant converges instead of living as a one-off Keycloak write. It is also the runtime gate: a platform role on any realm but master is ignored unless its realm/user is declared here (SHC-902). The gate matches the user id. Username entries are refused; run shc user ls --tenant <tenant> to find the UUID to declare as <tenant>/<user-id>, or let shc user grant <user> platform:manage --tenant <tenant> (or People in the console) add the entry for you; shc user revoke takes it away. The community edition ignores the declaration; the licensed build performs it under the rbac entitlement. Adding or removing an entry reaches every realm on the leader’s next reconcile pass, about a minute later: a removed entry’s mapping is revoked (never on master), and shc user revoke <user> platform:manage --tenant <t> removes one a leader that started after the removal left behind. Global scope, applied live; a malformed entry is refused at set time. |
auth.forward_auth_hosts | string or list | "": hosts this estate does not route whose gate still signs in through this estate’s Keycloak with the shc-forward-auth client, for example another estate’s gated apps while they move here and the identity host has moved first (SHC-3710). Entries are plain host names, a yaml list or comma- or whitespace-separated. Each host’s https://<host>/.shc/auth/callback and https://<host>/* join the shc-forward-auth redirect URIs of every realm at the next ingress sweep, about a minute, and leave the same way when the host is removed. The restamp replaces that client’s whole redirect-URI list with the estate’s routed hosts plus these, so a callback added in the Keycloak console instead is dropped at the next routed-host change, leader change or realm reconcile. Applies only while the estate routes at least one host of its own; with nothing routed the client keeps its wildcard. An unreadable row fails the restamp rather than shortening the list. Global scope, applied live; an entry that is not a plain host name (a scheme, port, path or wildcard) is refused at set time. |
auth.trusted_realms | string | "": realms whose tenant-qualified SHC roles also count in other tenants, <realm>=<tenant>[:<verb>] entries, comma-separated, e.g. corp=master:read,public: realm corp’s master/<role> roles act in tenant master, capped at read, and its public/<role> roles in tenant public, all on one corp sign-in. A qualified role counts only while its tenant is mapped here, never grants platform, and is never read from the token. Without an entry a realm’s roles count only in the tenant of the same name. Only a platform admin can set it. Global scope, applied live; an entry that is not <realm>=<tenant>[:<verb>] naming another tenant is refused at set time (X400166TRSENT). Doctor’s keycloak.trusted-realms flags holders without OTP and qualified roles naming an unmapped tenant. |
rate_limit
Section titled “rate_limit”Yaml only. shc config set rate_limit.* is refused with X400050CFGSTP
at every scope: set the block in a config file on each node, as
config-files.md § Rate limits are yaml-only
shows. The daemon watches its config files and applies a changed block
without a restart.
Hot-reloadable, and on outside dev; this line said “off by default” and
had it backwards. config_loader calls api.SetRateLimitEnabled(!devMode),
so on any production estate the values below are in force per remote IP on
the TCP listener. The unix socket is exempt (a UDS caller is already
root-equivalent). A non-positive value for either key is ignored rather than
applied, so the limiter cannot be switched off through config.
The limiter is classed and sharded, not one global bucket. Each class
keeps its own registry keyed on (remote IP, Host), so one noisy host cannot
drain another’s budget; ip_ceiling_multiplier is what stops a client from
varying the Host header to mint unlimited buckets. Routes not named by a
class below fall in the default class.
The join route, POST /api/join/{function}, is a class with no keys here. The
limiter passes it through, because behind Traefik every client arrives from the
same address and would share one bucket. The route limits each joining source
itself: 5 requests a minute, burst 3. Only a function registered for joining is
in the class; a request to any other name under /api/join/ is in the default
class, like any other route.
A request the auth gate refuses (no session, or a credential that does not
verify) never reaches the classes below, because the gate runs first. The gate
keeps its own budget per client instead, with no keys here: 120 at once,
refilling at 2 a second. Every refusal spends one, and a bearer the gate has to
verify (which can cost a Keycloak call) spends one before it is verified and
gets it back when it authenticates. A client with none left is answered
429 X429001RATLMT with X-SHC-RateLimit-Class: refused, and its bearer is not
verified until the budget refills. A signed-in browser session (the gate’s
session handle) is looked up in memory and is never refused for it. The client
is the address Traefik saw (the last X-Forwarded-For entry, honoured only from
a loopback or private peer), counted under the peer that reported it, and each
peer also has a ceiling 32 times one client’s budget, so a peer cannot name
itself fresh clients. An IPv6 address counts by its /64. At most 10000 clients
and 10000 peers are tracked at once.
| Key | Type | Default |
|---|---|---|
rate_limit.requests | int | 1500 |
rate_limit.window | int (seconds) | 30 |
rate_limit.ip_ceiling_multiplier | int | 8 |
rate_limit.forward_auth.requests | int | 3000 |
rate_limit.forward_auth.window | int (seconds) | 10 |
rate_limit.auth.requests | int | 3000 |
rate_limit.auth.window | int (seconds) | 10 |
rate_limit.status.requests | int | 600 |
rate_limit.status.window | int (seconds) | 60 |
The default class covers the CLI over TCP, Console XHR and everything a
class does not name, and sharding does not rescue it, which is why the number
had to move rather than sit where the other classes left it. The (IP, Host)
key helps only where traffic spreads across hosts, and this class does not:
Console XHR is one origin, and every shc call proxied through Traefik arrives
on that same host from that same container IP. 1500 per 30s is a burst of
1500 refilling at 50/s. This page previously documented 100/60s, a refill
of 1.67/s, well inside what one dashboard render plus one shc command spend
between them, and 30x tighter than the compiled-in fallback in
core/api/rate_limit.go that a comment there claims is kept in step with it.
ip_ceiling_multiplier scales a class’s per-(IP, Host) budget into the
per-IP ceiling above it. The Host half of the key is client-supplied, so it
shards and does not authorise; 8 lets eight hosts burst at once from one
source IP and bounds a forger to 8x a single host’s budget.
forward_auth is the SSO gate’s decision route (GET /api/auth/forward-auth): one token per gated subrequest. Raise this first if
authenticated users see the gate slow down under load. auth is the gate’s
unauthenticated companion set, which fires roughly 1:1 with it on a cold
(pre-login) page load, hence the matching budget in a registry of its own so
neither can drain the other. status is daemon status / health, polled per
gated page rather than per asset.
timing
Section titled “timing”Polling intervals. Reader: core/timeouts / the loops that consume them.
| Key | Type | Default |
|---|---|---|
timing.slow_poll | float (seconds) | 1.0 |
timing.tick_interval | str | every 2 seconds |
Open map: override any registered cron’s schedule by name (crons.<cron_name>).
Every cron ships a default in code; the notable ones:
| Key | Default (in code) |
|---|---|
crons.image_prune_cron | every 6 hours |
crons.disk_auto_prune_cron | every 1 hour |
crons.cleanup_cron | every 1 hour |
crons.db_analyze_cron | every 6 hours |
crons.db_vacuum_cron | every 6 hours |
timeouts
Section titled “timeouts”Role-named operational deadlines, in SECONDS. A missing / non-positive value
falls back to the built-in default (the value shown). Reader:
core/timeouts (timeouts.Get(role)).
| Key | Default | Key | Default |
|---|---|---|---|
timeouts.keycloak | 10 | timeouts.compose_converge | 900 |
timeouts.db_connect | 10 | timeouts.container_stop | 10 |
timeouts.rqlite_ready | 60 | timeouts.exec_idle | 1800 |
timeouts.rqlite_shutdown | 10 | timeouts.exec_kill_wait | 5 |
timeouts.drain | 300 | timeouts.log_idle | 300 |
timeouts.mesh_ping | 10 | timeouts.enroll | 60 |
timeouts.quiesce | 30 | timeouts.git_clone | 600 |
timeouts.quiesce_hold | 300 | timeouts.git_fetch | 300 |
timeouts.backup | 1800 | timeouts.backup_converter | 7200 |
timeouts.backup_stack | 21600 |
Three backup budgets, and they are not interchangeable. timeouts.backup
(1800) bounds the restic shell-out alone. timeouts.backup_converter
(7200) bounds ONE app-supplied converter sidecar; the 30-minute fallback it
replaced is what killed openobserve’s nightly capture on both estates, and a
single heavy deployment overrides it for itself with timeout: on the
converter in its own backup.yaml rather than by raising the estate number. A
converter that writes its output as it goes may also declare stall_after:
(seconds) there: it is stopped with X504556JOBSTL once its output has not grown
for that long. One that declares none is ended only by its timeout.
timeouts.backup_stack (21600) bounds ONE WHOLE orchestrated stack capture
dispatched to the node holding the deployment (prepare, quiesce, capture,
resume, finalize, including the restic seal and its upload), so it is the
outer bound the other two spend inside, never a synonym for timeouts.backup.
timeouts.quiesce and timeouts.quiesce_hold are two different budgets
and the pair is easy to confuse. quiesce bounds ACQUIRING the freeze: how
long the app-level pause hook may take to answer. quiesce_hold bounds
KEEPING it: past this deadline the capture stops the deployment rather than hold a
freeze of unknown age, which is the 2026-08-02 stopped-beats-untrusted
ruling. Raising quiesce for a slow hook does nothing for a capture that
outruns its hold, and vice versa.
timeouts.quiesce_hold also takes a per-stack override (ruling B4): a
deployment declares its own budget under timeouts.quiesce_hold in its
backup.yaml, and that beats the estate-wide number for that stack alone,
so one known-long capture does not force the unattended-outage bound wider
for every other deployment on the estate. openobserve ships 900 this way.
The override is read on the node running the capture and applies on the
single-stack orchestrated path (every SCHEDULED fire); the GROUP driver
deliberately stays on the estate-wide value, so a group’s total freeze cannot
grow with its member count.
timeouts.drain is per relocation, not per run. A node drain relocates
one stack at a time (the moves are serial, and a measured relocation costs
40-50 seconds), so shc node drain with no --timeout multiplies this
figure by the number of stacks the run plans to move, bounded by a 60-minute
ceiling. Tuning it down to bound a whole run does not do that: it lowers the
allowance for each move, and the run’s deadline is still N times whatever you
set. To bound a whole run, pass shc node drain <node> --timeout <seconds>,
which is honoured verbatim as the total budget for that invocation.
maintenance
Section titled “maintenance”Reader: services_seams_maint.go. Cron schedules live in crons.*, not here.
| Key | Type | Default |
|---|---|---|
maintenance.event_retention_days | int | 14 |
maintenance.event_retention_short_days | int | 2 (0 = no short tier): retention for codes their owning module declares high-churn chatter (registry.RetentionShort, today the daemon’s own execs, the container lifecycle events (started, stopped, restarted, created, removed, died, killed, paused, unpaused, out of memory), the fabric’s flow-ended line X200555FABEND and clusterfs’s slow-build line X200677CFSBLD). |
maintenance.event_retention_long_days | int | 90 (0 = no long tier): retention for codes their owning module declares significant transitions (registry.RetentionLong, today the container health_status transitions). Longer than event_retention_days on purpose: declaring a code long extends its life. |
maintenance.event_max_rows | int | 500000 (0 = off): the whole table’s row cap, audit mirror included, enforced after the age rules by shrinking every tier’s retention by one factor. A backstop sized not to bind at normal rates. |
maintenance.event_broadcast_grace_days | int | 1 |
maintenance.disk_auto_prune_threshold | int (percent) | 80 |
maintenance.stale_jobs_retention_hours | int | 24 |
maintenance.event_pending_max | int | 10000 (0 = off): hard count cap on non-audit rows still pending broadcast, enforced at the write door (drop-oldest, every few hundred inserts) so the backlog is bounded between hourly reaper runs and can never leak. |
maintenance.event_pending_ttl_seconds | int (seconds) | 3600 (0 = off): how long a non-audit row may stay pending before it is aged out of the recovery working set. |
maintenance.control_plane_snapshot_retention | int | 7: scheduled control-plane DB snapshots the db_snapshot_cron keeps (leader-only, newest-first prune). |
event_broadcast_grace_days is a backstop, not a policy. The prune
predicate used to require pending_broadcast = 0 and nothing ever cleared the
flag, so event retention deleted nothing on any estate since the table
was created. The root cause is fixed (a publish with no peer to broadcast to
completes immediately); this key bounds how long a row whose cross-node
broadcast never completed is protected from the pruner, so one permanently
unreachable peer cannot pin the table at unbounded growth again. Set it
above event_retention_days to restore the old never-prune-a-pending-row
behaviour. Rows removed under the backstop are reported separately from
ordinary retention, because a non-zero count means the broadcast path is not
converging.
event_pending_max and event_pending_ttl_seconds bound the same
table on the two dimensions neither the byte cap nor the 14-day retention
reached: how many pending rows may accumulate, and how old one may get.
They exist because a stuck broadcast path took promanager to a 9.6 GB OOM on
140,210 pending rows. The count cap mirrors the in-memory inbound queue size,
so the durable backlog and the memory queue fail at the same scale; healthy
steady-state pending is ~0 and at ~3.6 KB/row the cap is under ~36 MB. The TTL
drops an aged row from the republish SELECT immediately and the hourly reaper
flips pending_broadcast=0; the row is kept, not deleted, and ages out
through ordinary retention. Neither touches audit rows, and every drop is
logged (rate-limited, never re-published).
The hourly reaper is the last resort, not the way out. A pending row leaves the
backlog (events.pending_broadcast) in one of four ways:
- its broadcast settles: every peer took it, or exhausted its retries;
- the node that published it re-publishes it. The boot sweep does that once for what a restart left pending. A running daemon then looks, with 30s between passes, at its own pending rows older than one minute that its broadcaster is no longer holding for a peer, and re-publishes one batch of at most 500 a pass;
- the same sweeps retire the node’s own rows that are past
event_pending_ttl_secondsinstead of re-publishing them, each counted as a drop on the queue; - the leader retires the pending rows of nodes whose lease is lost or that
were removed from the cluster or are leaving it, at most 500 rows a pass
with 30s between passes. Only a row’s publisher sweeps it, and a lost one
cannot. These are counted as
retired, a figure of their own beside the queue’s totals: not out, since nobody was sent them, and not drops, since a drop grades the queue amber and a lost node must not hold a frozen cluster from thawing.shc statusprints it in the queue’s dropped cell (0, retired 3 (source lost)), the metric isshc_pressure_retired_total{queue,reason}, and the journal line names the count and the nodes.
Retiring clears pending_broadcast and nothing else. It applies to audit rows
too: the flag is broadcast bookkeeping, not part of the audit record, and the
row, its payload and its retention are untouched. The age bounds compare
instants, not the stored text: created_at holds two encodings on an estate
that began on the single-node engine, and a text compare hid every row written
before the engine flip from the sweep.
The broadcaster holds nothing for a peer whose lease is lost. It drops what it
had queued for it and queues nothing more until the peer is ready again, each
event counted as a drop on events.broadcast.<peer>. A peer that returns is
not sent what it missed; it never was, since an event that exhausts its retries
is dropped as well. Every event stays in the log.
Every row carries the registry id of the node that published it
(event.source_node_id) beside its OS hostname (source_hostname). A
node’s own sweeps and the leader’s retire match rows by that id, so a node
named otherwise than its hostname, or a host renamed between restarts, is
handled like any other. No row is matched by hostname. A node with no id
yet is in no cluster and writes its rows with nothing pending. A row written
before the column existed carries no id and is matched by nobody: the hourly
reaper takes it once it is past the pending TTL if it is not an audit row,
and an audit row leaves the backlog only when
maintenance.event_audit_retention_days removes it.
shc doctor run grades events.pending-broadcast from the queue’s own
pressure reading, the one shc status prints and the placement freeze reads,
and names the oldest pending rows with their publisher when the queue is off
green. While the queue reads green it reports no finding, whatever the boot
sweep’s continuation last said: a continuation that stopped no longer leaves
a backlog unworked, because the running drain takes what it left. A reading
older than shc status accepts (a minute) is not graded: the probe warns that
the grade is not current and counts the pending rows from the log.
A row can still stay pending for longer than that on a healthy cluster in one case: a peer whose lease is ready but which does not answer. Each event for it is retried for up to 30s, one at a time, the broadcaster is still holding the rows behind it, and the sweep leaves held rows alone. The backlog then reads amber and red like any other, and the freeze is right to hold.
Write-time containment (per-row cap, per-code coalescing)
Section titled “Write-time containment (per-row cap, per-code coalescing)”These bound what one row may cost and how many identical rows a single code may write. Read on every write, so a change applies with no restart.
| Key | Type | Default |
|---|---|---|
maintenance.event_message_max_bytes | int (bytes) | 0 (defer to the fixed 8 KiB floor) |
maintenance.event_payload_max_bytes | int (bytes) | 32768 (32 KiB) |
maintenance.event_coalesce_window_seconds | int (seconds) | 60 (0 = off) |
maintenance.event_coalesce_max_per_window | int | 10 (0 = off) |
There are two mechanisms and these keys are the outer one. core/log’s
persist guard is an unconfigurable floor every durable record already passes
through: 8 KiB per string leaf, 64 KiB per marshalled payload. The keys above
are the operator’s ceiling on top of it: they may only make a row smaller
than the floor already does, and they trim field-wise so the scope scalars
(tenant / stack / environment) survive. event_payload_max_bytes ships
below the floor deliberately, so the configurable layer is the binding one by
default. Truncation is never silent at either layer: the stored value keeps a
[shc-truncated] marker, the payload gains a _shc_truncated record naming
each cut field and its original size, and the daemon logs X500018EVTCAP /
X500905AUDCAP with the emitting code. Coalescing applies to non-audit rows
(same code, same scope, same payload), and suppressed occurrences are counted
onto the next stored row as _shc_suppressed, never dropped without a number.
Audit retention: the two age keys ship on, the caps and coalescing off
Section titled “Audit retention: the two age keys ship on, the caps and coalescing off”| Key | Type | Default |
|---|---|---|
maintenance.audit_retention_days | int (days) | 365: the shortest retention that answers what happened in the last fiscal year; 0 = unbounded |
maintenance.audit_max_rows | int | 0 (off) |
maintenance.event_audit_retention_days | int (days) | 90: the event table’s is_audit mirror, which feeds the HUD and replay and is never the sole copy; 0 = unbounded |
maintenance.event_audit_max_rows | int | 0 (off) |
maintenance.audit_coalesce_window_seconds | int (seconds) | 0 (never) |
maintenance.audit_coalesce_max_per_window | int | 0 (never) |
The two age keys ship on because nothing had ever pruned either table since
install day and the control-plane volume has already filled once. A key set
to 0 explicitly stays unbounded: the shipped default applies only when the
key is absent. Age is the policy an operator can explain to an auditor, so the
row caps stay off, and identical audit rows are never coalesced. Shortening
the days, capping the rows or coalescing is an estate owner’s ruling, and it
costs precisely this: deleted audit
records are gone (the event is_audit mirror is partial: two
emitters write only one of the two tables, and has its own retention); the
audit hash chain is cut, with the pruner attesting to itself in a chained
checkpoint row (A200990AUDPRN) recording the cutoff, the count and the hash it
pruned through, after which shc audit verify reports prefix_pruned=true
permanently; and coalescing replaces N records with one plus a count, which may
not substitute for N records in a jurisdiction that asked for the records.
Vault READ audit: aggregated by default, per-read on request
Section titled “Vault READ audit: aggregated by default, per-read on request”| Key | Type | Default |
|---|---|---|
maintenance.vault_read_audit_window_seconds | int (seconds) | 60; 0 restores a synchronous row per read |
maintenance.vault_read_audit_max_keys | int | 1024, the bound on the in-memory digest table |
maintenance.vault_read_audit_steady_attest_seconds | int (seconds) | 21600 (6 h); 0 restores one digest row per closed window |
A vault READ is not a mutation, and giving every internal read its own replicated audit row put a raft commit on the read path. These two keys are what took it off: reads of the same key inside the window are folded into one digest row instead.
Two reads are never aggregated regardless of this setting: a read whose
value was disclosed across the API boundary (GET /vault/secrets/{key}), which
is the disclosure an auditor actually asks about, and any read that accompanies
a mutation. What aggregation costs is per-occurrence timestamps for internal
reads inside the window, plus, on an unclean stop (SIGKILL, power loss),
the reads counted since the last sweep; a clean stop drains every open window
first.
Set the window to 0 and per-read synchronous rows return byte-for-byte, on
the next read, with no restart: the policy is resolved per read rather than
snapshotted at boot, which is the only activation class that is any use to an
operator who has just been asked to produce a per-read trail.
vault_read_audit_max_keys bounds the digest table (measured distinct-key
cardinality on both live estates is 139). A full table degrades to per-read
rows rather than dropping anything, and reports the count as overflowed on
the next digest row.
vault_read_audit_steady_attest_seconds is there because the window was
necessary and not sufficient. Measured on promanager 2026-08-21: of the last
1000 audit rows, spanning 15 hours, 937 were read digests: openobserve’s
password alone contributed 458 and the four forward-auth secrets 79 each,
against ten rows that were real operational events. A window turns N reads into
one row per window; it does not turn a reader that never stops into anything
smaller than one row per window forever. So a digest row is now minted when a
subject’s read pattern changes (its first window, a new actor, a read that
started failing, or a window more than 2x off the established rate in either
direction), and an unchanged run rolls into one periodic attestation per
subject per this interval, carrying the exact count, the span and the rate. At
steady state that is 4 rows per secret per day instead of 720, and a change
still lands within one window plus one sweep (~70 s). Nothing becomes
invisible: every read is still counted and lands in exactly one chained row, so
SUM(read_count) over the digest code plus COUNT(*) over the per-read code is
still the exact number of reads. What is lost, on top of what the window already
cost, is the per-window boundary inside a quiet run.
backup
Section titled “backup”| Key | Type | Default |
|---|---|---|
backup.repo | null | str | null; required, no default |
backup.password | null | str | null; required, no default |
backup.secrets_password | null | str | null; a ref+vault:// reference only |
backup.secrets_key | null | str | null; a vault reference to the stable key that seals new backups’ secrets, kept to open them after the vault master rotates |
backup.aws_access_key_id | null | str | null |
backup.aws_secret_access_key | null | str | null |
backup.azure_account_name | null | str | null |
backup.azure_account_key | null | str | null |
backup.b2_account_id | null | str | null |
backup.b2_account_key | null | str | null |
backup.google_application_credentials | null | str | null |
backup.retention.daily | null | int | null |
backup.retention.weekly | null | int | null |
backup.retention.monthly | null | int | null |
backup.retention.yearly | null | int | null |
These keys reach BOTH of SHC’s backup engines, by two different routes.
shc backup create(and each member of--all-connected/--with-dependants) captures straight intobackup.repoand refuses withoutbackup.password. Theshc backup schedulecron, the pre-uninstall safety backup, and the pre-restore / pre-rollback snapshots take the orchestrated engine, whose capture reads no key, but whose FINALIZE step then seals the finished.bakintobackup.repounderbackup.password, verifies it readable there, and deletes the local plaintext.
backup.repo and backup.password have no defaults and must be set
together. The daemon does not invent a backup key: with either half
unset it creates no repository and shc backup create refuses
(X500415RSTBKN). Setting one alone is refused naming the missing half,
rather than being silently discarded. A backup schedule set while
backup.repo is set and backup.password is not is refused outright
(X400077BKPSCD): every fire would fall back to local plaintext
forever.
The orchestrated engine still does not refuse, and that is the case to
know. With neither key set (the CE single-node default) it keeps
firing and leaves an unencrypted .bak at
<state_home>/backups/<tenant>/<stack>/, on the same disk being backed
up: a plaintext manifest.json carrying the deployment’s install-time
--var values as bare strings, an uncompressed tar of the app’s own
credential files (a Nextcloud config.php dbpassword, a frappe
site_config.json encryption_key, a postgres converter’s pg_dumpall
role lines), and one sealed member, secrets.vlt. The same happens when a
seal cannot be verified; each such archive logs X200075BKPSEL naming the
reason and X200079BKPLOC naming the path and the repo it did not reach.
SHC writes those containers mode 0600 inside a 0750 directory, but
that is custody, not encryption.
Three artifacts stay plaintext even with both keys set, because each exists to be read without them:
<state_home>/exports/<id>.bkg: written bybackup create --all-connected/--with-dependantsand bybackup group. It bundles its members by decrypting them back out, so one file holds an app’s config credentials next to its database’s dump. Mode0600in a0700directory, and never pruned by retention: delete it yourself. Between clusters that share abackup.password,shc recover --consistency-id <id>reads the same group straight out of the repository and writes no plaintext at all.- pre-move archive: a kept pre-move archive rests into the stack’s backups dir as an ordinary backup, labelled as pre-move, and from then on the normal retention applies to it. The capture stages under
<staging_dir>/clone/<operation id>and that directory is removed when the operation ends. backup create --file/backup exportoutput: you named the path and asked for a portable archive.
To see which engine wrote a given archive, shc backup ls carries an
encryption column (restic / none / unknown) per row, and -o json
adds the location. For the estate-wide posture, shc doctor run reports
backup.encryption (it never prints the key).
A ref+vault:// value is dereferenced, but a reference that cannot
resolve (locked vault, absent key) refuses rather than falling back to
the literal string.
concurrency
Section titled “concurrency”| Key | Type | Default | Notes |
|---|---|---|---|
concurrency.queue_max_depth | int | 1000 | Queue backpressure ceiling (hot-reloadable). |
deploy
Section titled “deploy”The quota/reservation family (deploy.cpu_quota, deploy.memory_quota,
deploy.reservation_ratio, deploy.cpu_reservation_ratio,
deploy.memory_reservation_ratio, deploy.limit_ratio) is install-time;
see When a written value takes effect
and shc quota. Two siblings are not:
| Key | Type | Default | Notes |
|---|---|---|---|
deploy.placement_scoring | str | on | Whether the placement scorer ranks the fleet. on scores free memory and CPU (node total minus committed reservations), deployment count, and tenant/app spread. A node whose runtime matches the deployment outranks any other score (modules/placement/advisor.go). off ranks only the node that received the install. Resolves through the ordinary 5-level cascade, so scoring can be disabled for one tenant and left on globally. |
deploy.disruption | str | rolling | What the cluster’s own movers may do to a deployment. rolling lets a drain move it one replica of a service at a time, each ready on its new node before the next is touched. never blocks a drain of any node it runs on: shc node drain refuses X400423CLSDRM and names it, unless --force is given. It never blocks the operator’s own shc update. Read at the deployment, stack, environment, tenant and global tiers, live at the next drain. Set one deployment’s with shc update <stack> -c deploy.disruption=never, and clear it with -c deploy.disruption!. A package cannot set it. |
| Key | Type | Default |
|---|---|---|
acme.email | null | str | null |
acme.wildcards | null | list[str] | null; global scope only |
acme.wildcards is a list of BASE domains the estate wants covered by ONE
wildcard certificate each instead of one certificate per host. The *. is
added by SHC and is never typed:
shc config set acme.wildcards '[corp.example.com, corp-legacy.example.com]'Every routed host EXACTLY ONE LABEL below a listed base then requests
*.<base> rather than its own name, so a 40-host namespace spends one
certificate and solves one DNS-01 challenge instead of 40 of each. That is
what keeps a large estate inside Let’s Encrypt’s per-registered-domain weekly
cap, since example.com is one registered domain for every third-level
namespace under it.
Two constraints are structural rather than stylistic. It is global scope
only, because a wildcard is a property of a DNS ZONE and not of a
deployment: one certificate in traefik’s shared TLS store serves every host in
the namespace whoever owns them, so no tenant or deployment may declare it on
its neighbours’ behalf. And it is DNS-01 only: a wildcard identifier
cannot be validated over HTTP-01, so a host inside a listed namespace whose
zone no DNS-01-capable DNS connection owns keeps its own per-host order and
says so (X201011ACMWCH). The apex itself is not covered: *.corp.example.com
does not match corp.example.com.
Provider definitions are config. A per-host DNS target is not a
flag. app.example.com=lb.example.com is the removed override and is
refused (X400995HSTTGT). Drop the suffix and the record follows the
ladder. On a non-internet exposure the address is dns.lan_address, then
dns.public_address. Three scoped knobs ARE config: dns.public_address,
the NON-INTERNET cluster entrypoint (an ip or hostname) that an HTTP
--expose record targets on LAN topologies (on the target ladder after
dns.lan_address and above the traefik-VIP and node rungs; internet exposure
never reads it, and internet endpoints are inferred from the system
traefik’s web-conn VIP or the placed node’s public_address), plus the
per-record dns.ttl / dns.proxied knobs.
The operator-facing version of dns.public_address (what the default is,
why a cluster behind a pfSense MUST set it, and why an internet-exposed
cluster can ignore it) is
The cluster entrypoint.
| Key | Type | Default |
|---|---|---|
dns.provider | null | str | null (null disables managed DNS) |
dns.owner_id | str | written by shc init: this cluster’s DNS ownership identity; global |
dns.providers.<name>.* | map | null; open prefix, per-provider credentials/config |
dns.public_address | str | unset; the non-internet entrypoint, scoped |
dns.lan_address | str | unset; the published non-internet address, scoped |
dns.private_records | bool | unset (on); false drops the private-plane record, scoped |
dns.ttl | int | 300 (1..86400); scoped |
dns.proxied | bool | false (Cloudflare orange-cloud); scoped |
dns.externally_published_zones | str | unset; zones something outside this cluster publishes, comma- or space-separated; global |
dns.lan_address is the address a NON-INTERNET deployment’s managed-DNS
records CARRY. It was split off the exposure axis so that “who may connect”
(exposure + lanEnforcement + the ip allow list) and “what address is
published” stop being one decision. It ranks ABOVE dns.public_address on
target-ladder rung 2, so a narrower private value overrides an estate-wide
one.
It takes the address, not a mode, and that is deliberate: a node can hold
several private addresses serving DIFFERENT client populations, one on a
LAN, another on the mesh, so a bare private would have to guess and
would strand whoever is on the other plane. The operator names the address he
means.
Two things it never does. exposure: internet NEVER reads this key: a public
deployment always publishes the public address (owner’s ruling, 2026-08-18).
And it never suppresses a record: every host keeps its public-zone record.
Split-horizon DNS was rejected on 2026-08-18 and re-ruled on 2026-08-20 (ce
modules/dns/purpose.go): a host is published in every zone that matches it,
public and private, and the public record is always kept. Null publishes
whatever the estate publishes today (dns.public_address, then the inference
rungs), an exact no-op. Scoped through the full cascade, so it can be set
estate-wide and carved per environment, stack or deployment.
A private connection on the overlay plane (netbird) also reads it, for every
exposure: its zone carries dns.lan_address when set, else the system Traefik
node’s private underlay address, and never the public address. See
NetBird.
dns.private_records is the per-app opt-out of private publication. Unset or
true, a host gets a record on every plane that matches it. false, while a
public plane also carries the host, removes this cluster’s private records and
its _shc-owner claim on the private planes at the next re-sync, so every
client resolves the public record, which stays. It cannot darken a host: on an
estate whose only DNS connection is private the key is ignored and says so
(X200924DNSPOO). Scoped through the full cascade.
dns.owner_id is the identity every managed record is tagged with: a
companion TXT heritage=shc,shc/owner=<id> at _shc-owner.<host> for each
managed host, or at _shc-owner._wildcard.<domain> for a declared domain
whose hosts share one wildcard. Managed
deletes and replaces touch only records whose TXT carries this id, and the
orphan reaper takes its candidates from it, so two clusters writing into one
zone must carry different ids. shc init mints it at genesis as
<host slug>-<8 hex>, prefixed with cluster.generation when that is set
(ce modules/cluster/commands/init.go, SeedDNSOwnerID). default.yaml
ships it null, and with no value every DNS write refuses with
X503038DNSOID (ce modules/dns/ownership.go). Set it by hand only on a
cluster made before the mint existed: shc config set dns.owner_id <id> --scope global. Never change it on a cluster that has published records:
every record tagged with the old id stops being this cluster’s, and nothing
updates or removes it again. The daemon keeps the id once it has read one,
so a change takes effect when shcd restarts.
dns.providers is an open prefix (like acme.providers / vault.providers /
otel.providers): <name> selects the impl and each impl reads its own field
set (providerBuilders, modules/dns/factory.go): cloudflare,
route53, hetzner, powerdns, powerdns-local, rfc2136, digitalocean,
gcp, azure, linode, vultr, scaleway, exoscale, ovh, unbound,
namecheap (designate is connection-backed only). Legacy fallback path:
dns.<name>.<field>.
| Key | Type | Default |
|---|---|---|
vault.provider | null | str | null (null disables ref+vault resolution) |
vault.providers | null | map | null |
OTLP-HTTP export. otel.provider selects a otel.providers.<name> blob;
when unset a managed default (system openobserve behind SHC_HOST) engages.
| Key | Type | Default |
|---|---|---|
otel.enabled | bool | unset (= enabled): the operator’s master switch for the per-node collector. false tears the collector down on every node; it is deliberately absent from the shipped defaults so that turning telemetry off is a row you wrote and can see. Distinct from the airgap hard-off (license.offline), which keeps the collector running and terminates its pipelines in nop. |
otel.provider | null | str | null |
otel.providers | null | map | null; per-provider {endpoint, insecure, url_path_base, headers} |
otel.filter.quiet | null | str | list | null; regex/literal pattern(s); a container-log line matching one is dropped at source for the row’s scope (the per-app “quiet a chatty container” knob: container stdout has no parsed severity, so this is a body match, not a severity floor); scoped |
otel.filter.rules | null | str | list | null; raw OTTL log_record condition(s), accepted verbatim (the T2 escape hatch); scoped |
otel.filter.* rows are scoped like every other config row: the scope of
the row is what it filters: a stack-scope quiet rule affects that stack
only. The compiled collector config conjoins every rule with a guard on the
row’s scope, so a rule can only narrow its own scope, never widen it; a
raw rule whose expression pins a scope attribute to a different value than
its own row is warned about (and still applied scope-guarded), not silently
applied. Filters drop; the always-on scrub redacts; no filter rule
is ever the security mechanism, and no rule set removes the scrub stage.
otel.provider at a NON-global scope is a routing row (telemetry
slice 5): the row’s scope is what it routes, and routing is fan-out
(owner ruling 2026-07-31): a tenant-scope row sends that scope’s container
logs and -i otel=OTEL app traces/metrics to the named
otel.providers.<name> destination in addition to the global/default
destination, never instead of it. The provider blob resolves through the
scoped cascade first (a tenant-scoped otel.providers.<name>.* override,
with per-tenant credentials, beats the global definition), then the yaml tree.
Node metrics (host + docker stats) never route to a scoped destination, and
every routed branch carries the same always-on scrub. The airgap hard-off
(license.offline) beats routing rows exactly as it beats the default
destination. A global change re-converges the per-node collector
immediately; a scoped routing row lands within one reconcile tick (≤5m).
notification
Section titled “notification”| Key | Type | Default |
|---|---|---|
notification.providers | null | map | null; named transports (type: email|ntfy|slack|discord|webhook) |
notifications | null | list | null; the operator’s rule list, each rule naming a provider. The product ships backup-failed, backup-fire-dropped, backup-unprotected and schedule-late, which send through notification.providers.operator once it is defined; a rule here with one of those names replaces it |
storage
Section titled “storage”| Key | Type | Default |
|---|---|---|
storage.volumes.provider | null | str | null: select a volume-capable connection by name; its credentials supply the token and region |
storage.volumes.auto_failover | bool | false: OFF by default; auto-rebind an RWO volume off a dead node only after it is provably stopped |
storage.volumes.hcloud.filesystem | null | str | null: the filesystem a node formats a new Hetzner volume with; null is ext4. Read for a Hetzner volume connection |
scheduler
Section titled “scheduler”How long a lost node’s replicas wait, counted from its lease expiry, before
they move (shc constraint explain -s <deployment> prints the result). A Go duration or seconds,
read at every tier, so a deployment may shorten its own. A single writer or
a replica with a volume never waits less than the 60s single-writer stop window.
The store reads scheduler.grace.stateless at global scope for a lost store
replica: once that long past its lease expiry, with no announced return, the
leader gives its slot to a live member of its location and evicts it from raft.
| Key | Type | Default |
|---|---|---|
scheduler.grace.stateless | duration | 60s |
scheduler.grace.member | duration | 5m |
scheduler.priority | low | normal | high | normal |
scheduler.moves_per_minute | int | 6 |
scheduler.disk_mark | int (percent) | 80 |
scheduler.disk_mark_free | size | 100Gi |
scheduler.priority orders work, high first: rescheduling a lost node’s
replicas, the retry of one that fits nowhere, and a drain’s moves (shc
modules/failover/reschedule.go, modules/cluster/drain_place.go). It never
preempts anything. It is read through the scope cascade on every pass, so set
it where it matters, for example shc config set scheduler.priority high --scope deployment -t <tenant> -s <stack> -e <environment>, and no restart
is needed. The platform’s own stacks run at system, above high, whatever
is set. A value other than the three reads normal, and shc constraint explain -s <deployment> prints the priority it read and why.
scheduler.moves_per_minute caps the automatic replica moves the cluster
starts inside any sliding minute: a reschedule, a failover, a rebalance, a
drain’s moves, and the moves that resume after a freeze thaws. A move past
the cap waits for a later pass. A manual move is never counted. 0 reads 6.
It is a global key read when shcd starts (ce subsystems/impl/freeze.go,
modules/freeze/limiter.go), so a change takes effect at the next restart.
Raise it when a lost node’s replicas should move faster and the other nodes
have room for them; lower it to spread a recovery’s load.
When the lost node was the leader, two more clocks run. The new leader gives every lease a fresh grace of 30s (two lease lifetimes), so the lost leader’s lease expires 30s after the new leader takes over. The new leader also holds automatic moves frozen for that grace, and thaws once every pressure signal has been green for one minute. A replica moves on the first scheduler tick (every 5s) after both its own grace and the thaw. With the defaults a stateless replica of a lost leader is assigned to another node about 100s after the new leader takes over: the 30s grace, up to 4s for the lost lease and each node’s pressure level to be recorded, the 60s thaw window and one tick.
A signal still amber when the leader-change grace ends pushes the thaw back
for as long as it stays amber. shc status and shc doctor run name it on
the frozen line after not calm:, with every queue that is off green and the
node it is on. The event backlog the live nodes owe a lost node
(events.broadcast.<node>) is not counted while that node’s lease is lost.
It counts again when the node returns, until it has drained. What the lost
node itself had in flight is retired by the leader, 500 rows a pass with 30s
between passes, starting with the first pass after its lease expires. A
handful of rows is gone before any is two minutes old, which is when the
backlog reads amber; a node lost with more than a pass can take, or with rows
already that old, reads amber until the passes have caught up, and the thaw
waits for it.
scheduler.disk_mark and scheduler.disk_mark_free are the disk mark
(SHC-3182). A disk is past it when more than disk_mark percent of it is
used and it has less than disk_mark_free left, so a 40 GiB root disk is
past it with under 8 GiB free and a 4 TiB one only under 100 GiB. A node
with any disk past the mark takes no new bind: its root disk, the store its
runtime unpacks images to (the incus pool instances are made on, docker’s
and containerd’s roots, podman’s graph root) and each active LVM thin
pool’s data and metadata. Neither does a node whose disk an install’s images
would push past the mark. What already runs there stays and is not moved. An
install no node has room for is refused with X507318FNCDSK, which names
the node closest to its mark, the disk, its free bytes, what the install
needs there and what the mark keeps free. shc doctor names each disk past
the mark under scheduler.disk_mark. A disk’s free bytes are what df shows
as available. The health ladder’s degraded rung reads the same two keys for
the root disk, so the node also reads pressured, a little later: the
ladder counts the blocks the filesystem keeps for root as free. Both keys
are global and read on every install, so a change applies to the next one.
100 turns the mark off. A node on an older build answers no disks and is
placed as before.
What an install takes there counts each instance (SHC-3320). An Incus dir
pool, or an lvm pool without a thin pool, unpacks a replica’s image into
each instance’s own root, so eight services of one image take it eight
times there; docker, podman and the other Incus drivers share one copy. A
volume --storage <volume>=node:<size> sizes counts its size too. Each
node also records the free space of the pool it makes instance roots on in
its condition row, every 15 s as it moves, and placement reads the rows: a
move or a failover that asked no node still holds a member to the mark,
and the scorer’s disk_room term ranks the members by the bytes their
pools keep once the install lands, so a burst goes where there is the most
room. A rebalance ranks the members a move would relieve its node onto the
same way, so of two that would, the move goes to the one an install would
take (SHC-3341). X507318FNCDSK names each node’s pool, shc doctor names
them under health.pool-room, and shc rebalance --plan beside each node’s
load.
health
Section titled “health”| Key | Type | Default |
|---|---|---|
health.reconcile_enabled | null | bool | null (null = follow cluster-mode default, leader-only) |
health.check_infrastructure | bool | true |
health.check_docker_networks | bool | true |
health.adopt_keycloak_realms | bool | true: a realm found in the system Keycloak that is no SHC tenant becomes one. Add only: a realm that goes away removes nothing. Master, disabled realms, keycloak/realm vapp instances, tombstoned names and names that are not legal tenant names are skipped. Set false when tenants are made only through SHC and Keycloak keeps realms of its own that SHC must not adopt. The other direction, a tenant’s realm, always runs. Read on every reconcile pass, so a change is live (ce modules/health/reconcile/actions.go) |
publish
Section titled “publish”| Key | Type | Default |
|---|---|---|
publish.listen | selector string | unset (every node listens) |
The nodes that listen for an --expose port which names no @ place.
A selector (edge=true, location=eu/hel, node=@(service=db)); the
empty string is every node, the same as leaving the key unset. Global
scope only. The next fabric render applies it.
cluster
Section titled “cluster”There is no config knob for single-node vs cluster mode. Every binary can
cluster (the raft engine is the external rqlited process); the decision is
the engine marker {state}/engine.json, written by the promote/join flip
(core/rqlited). No marker = single-node.
| Key | Type | Default & notes |
|---|---|---|
cluster.address_quarantine | duration | 1h: how long a fabric chunk a node gave back, a removed node’s chunks and its mesh0 address stay out of reach before another node may take them. Past it, an address goes back only once every live node has said its applied shc0 and mesh0 config no longer names it. Global scope, live: read on each allocation, so shc config set cluster.address_quarantine 5m reaches the next one without a restart. An unset or unparseable value, or one not above zero, is 1h. |
cluster.key_rotation | duration or off | 30d: how old a node’s mesh0 or shc0 key gets before the leader rotates it. The mesh_key_rotation cron starts at most one rotation an hour, the oldest key past this, and shc doctor check mesh.key_rotation warns of a key a day past it. A key’s age starts when the schedule first sees it, so a cluster upgraded from v0.1.21 rotates nothing for 30 days after the upgrade. A Mac’s shc0 key is not rotated. Units w, d, h and m; off stops the schedule. Global scope, live: read on every tick. An unset or unparseable value, or one not above zero, is 30d. |
| Key | Type | Default & notes |
|---|---|---|
store.replica_every | int | 50: how many nodes one store replica serves. Up to 5 nodes vote, one node in this many runs a replica of the store, with at least one in every location, and every other node is a store client that runs no rqlited. A cluster of no more nodes than this has no clients. Global scope, live: the store tier pass reads it each time, so shc config set store.replica_every 20 reaches the next pass without a restart. shc doctor warns when a replica is home to more clients than this. An unset value, or one that is not a whole number above zero, is 50. |
console
Section titled “console”| Key | Type | Default & notes |
|---|---|---|
console.realm | str | master: the realm the Console’s plain address signs people in against. Global scope, live: a browser takes it on its next load of the Console. Set it where the people who run the estate live in a tenant realm, e.g. shc config set console.realm corp. An account of any other realm opens the Console with ?realm=<realm>. Only the stored row is read: the daemon’s files and environment cannot set it. |
Precedence
Section titled “Precedence”DB-backed scoped overrides follow the one SHC scope ladder; the most specific
wins (core/scope):
- Deployment: tenant + stack + environment (
-t X -s Y -e Z,--scope deployment) - Stack: tenant + stack (
-t X -s Y,--scope stack) - Environment: tenant + environment (
-t X -e Z,--scope environment) - Tenant: tenant (
-t X,--scope tenant) - Global: base (
--scope global)
Stack outranks Environment. The same ladder orders vault secret resolution.
Not every key is read at every tier
Section titled “Not every key is read at every tier”A key’s reader may narrow its lookup context below the full ladder, and
core/scope.Cascade skips any tier whose identifiers are absent, so a row
stored at a tier that reader never visits is stored, reads back, and is
honoured by nothing. Each key’s owner now declares the tiers its reader
actually consults, and shc config set refuses a row outside them,
naming the tiers that would work. A key with no declaration is
unrestricted, exactly as before.
| Key | Read only at |
|---|---|
acme.default | global |
modules.* | global |
proxy.proxy_protocol_trusted_ips | global |
storage.volumes.provider, storage.volumes.hcloud.filesystem, storage.volumes.auto_failover | global |
keycloak.access_token_lifespan, keycloak.sso_session_idle_timeout, keycloak.sso_session_max_lifespan, keycloak.offline_session_idle_timeout, keycloak.login_theme, keycloak.policy_cache_ttl | global |
lease.protected_environments | global |
backup.retention.* | global, tenant, stack |
catalog.hidden.* | global, tenant, environment |
lease.expires_at, lease.reap_* | deployment only |
privilege.grants.* | global |
container_broker.enabled, container_broker.default_cpus, container_broker.default_memory, container_broker.pids_limit, container_broker.max_containers, container_broker.max_networks, container_broker.max_volumes | global |
publish.listen | global |
console.realm | global |
Every key read through the ambient koanf tree (cfg.String / cfg.Bool / …)
consumes the global DB tier only; the two read surfaces are disjoint, and
a key resolves from exactly one of them.
A tier also needs its identifiers: --scope environment requires -e,
--scope deployment requires -t -s -e. Without them the row’s derived tier
is a different one, so the write is refused rather than silently landing
somewhere else.
When a written value takes effect
Section titled “When a written value takes effect”Keys fall into three activation classes, and shc config set prints which one
it just wrote:
| Class | Meaning | Examples |
|---|---|---|
| live | picked up by the next reconcile sweep | acme.default, launcher, catalog.hidden.*, backup.retention.*, storage.volumes.auto_failover, lease.*, and the realm settings keycloak.access_token_lifespan, keycloak.sso_session_idle_timeout, keycloak.sso_session_max_lifespan, keycloak.offline_session_idle_timeout, keycloak.login_theme, keycloak.remember_me, keycloak.brute_force_detection, keycloak.admin_events_enabled, keycloak.admin_events_details_enabled, which the leader writes onto every realm on its next reconcile pass |
| install | baked into the rendered deployment: a running container keeps what it was installed with; re-render with shc update <stack> | deploy.cpu_quota, deploy.memory_quota, deploy.reservation_ratio, deploy.cpu_reservation_ratio, deploy.memory_reservation_ratio, deploy.limit_ratio, storage.volumes.provider, storage.volumes.hcloud.filesystem |
| daemon-restart | captured once while the daemon builds its services; restart shcd on every node | keycloak.policy_cache_ttl |
proxy.proxy_protocol_trusted_ips is install-class and worse than the
rest: it is baked into the system Traefik render and absent from the ingress
drift fingerprint, so the standing sweep never converges it. It needs an
explicit shc update traefik.
privilege.grants.<tenant> is the K3 privileged-capability grant
(docs/decisions/2026-08-14-broker-rulings.md): set to the literal boolean
true at global scope by the master tenant’s operator, it allows the
named tenant the privileged request class: privileged: true,
docker-socket/host mounts, dangerous cap_add, and the job-container
broker. The master tenant holds it implicitly. Every narrower scope is
refused (X400066CFGSCP): a grant row the granted tenant could write
itself would be the self-grant hole the ruling forbids. It is live-class,
consulted on every privileged request, so a revoke takes effect on the
next ask. container_broker.enabled (global only, default off,
live-class) opts the estate into the job-container broker: the
broker socket a deployment gets
when it binds the Docker socket, and shc.container.run. The
container_runtime entitlement (Pro+) and the K3 grant still gate every
call.
The broker’s limits are global only and live-class too. Each is a
positive number, and a value that is not one refuses every create
(X403989CBRLIM) until it is fixed:
| Key | Default | Meaning |
|---|---|---|
container_broker.default_cpus | 1 | CPUs for a brokered container whose create names none |
container_broker.default_memory | 1073741824 | Bytes of memory for a brokered container whose create names none |
container_broker.pids_limit | 2048 | The most processes a brokered container may hold |
container_broker.max_containers | 16 | Brokered containers one deployment may have on a node |
container_broker.max_networks | 8 | Networks one deployment may have created through its broker on a node |
container_broker.max_volumes | 64 | Volumes one deployment may have created through its broker on a node |
quota.max_deployments / max_environments / max_apps / max_vdeployments govern
tenant-wide counts (every install’s +1 cascades up to the tenant usage row
and the check reads there; max_environments counts the environments the tenant’s
deployments occupy), so set them at --scope tenant. Below that tier the
write is now refused (X400066CFGSCP) rather than stored: the install gate
resolves the ceiling through a tenant-only lookup context, so an environment-,
stack- or deployment-scoped row could only ever be rendered back by shc quota status and never enforced. The next install reads a new count ceiling with
no daemon restart, and running deployments are never checked again against a
lowered one. quota.cpu / memory / disk are the ones
meaningful at every tier: they are enforced down to the leaf, so every tier
of theirs is read and none is refused.
Across config sources, values resolve in this order (later wins):
default.yaml(bundled)/etc/shc/config.yaml+/etc/shc/config.d/*.yaml(or~/.config/shc/config.yamlfor non-root)- DB-backed scoped overrides (the ladder above)
- Environment variables (
SHC_*)
Source: core/config/default.yaml.