Skip to content
SHC Docs

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.

KeyTypeDefaultNotes
devboolfalseDevelopment mode.
launcherbooltrueInject the SHC launcher button into gated apps’ HTML. Resolved through the scope cascade; global kill-switch is shc config set launcher false.
launcherGzipbooltrueWhether 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.
ssoAutoRedirectboolfalseWhether 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.
launcherPlacedbooltrueWhether 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.
launcherEnvironmentstrautoWhich 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.
lanEnforcementstrallowlistWhether 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.
lanAllowlistCidrsstrunsetExtra 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.

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.

KeyTypeDefault
keycloak.client_idstrshc-api
keycloak.base_pathnull | strnull: 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_verifybooltrue (set false only for self-signed dev stacks)
keycloak.access_token_lifespanint (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_timeoutnull | 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_lifespannull | 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_timeoutnull | 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_themenull | strnull 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_mebooltrue: 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_detectionbooltrue: 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_enabledbooltrue: 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_enabledboolfalse: 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.
KeyTypeDefault & notes
auth.gate_cookie_domainenum (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_adminsstring"": 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_hostsstring 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_realmsstring"": 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.

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.

KeyTypeDefault
rate_limit.requestsint1500
rate_limit.windowint (seconds)30
rate_limit.ip_ceiling_multiplierint8
rate_limit.forward_auth.requestsint3000
rate_limit.forward_auth.windowint (seconds)10
rate_limit.auth.requestsint3000
rate_limit.auth.windowint (seconds)10
rate_limit.status.requestsint600
rate_limit.status.windowint (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.

Polling intervals. Reader: core/timeouts / the loops that consume them.

KeyTypeDefault
timing.slow_pollfloat (seconds)1.0
timing.tick_intervalstrevery 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:

KeyDefault (in code)
crons.image_prune_cronevery 6 hours
crons.disk_auto_prune_cronevery 1 hour
crons.cleanup_cronevery 1 hour
crons.db_analyze_cronevery 6 hours
crons.db_vacuum_cronevery 6 hours

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)).

KeyDefaultKeyDefault
timeouts.keycloak10timeouts.compose_converge900
timeouts.db_connect10timeouts.container_stop10
timeouts.rqlite_ready60timeouts.exec_idle1800
timeouts.rqlite_shutdown10timeouts.exec_kill_wait5
timeouts.drain300timeouts.log_idle300
timeouts.mesh_ping10timeouts.enroll60
timeouts.quiesce30timeouts.git_clone600
timeouts.quiesce_hold300timeouts.git_fetch300
timeouts.backup1800timeouts.backup_converter7200
timeouts.backup_stack21600

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.

Reader: services_seams_maint.go. Cron schedules live in crons.*, not here.

KeyTypeDefault
maintenance.event_retention_daysint14
maintenance.event_retention_short_daysint2 (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_daysint90 (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_rowsint500000 (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_daysint1
maintenance.disk_auto_prune_thresholdint (percent)80
maintenance.stale_jobs_retention_hoursint24
maintenance.event_pending_maxint10000 (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_secondsint (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_retentionint7: 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_seconds instead 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 status prints it in the queue’s dropped cell (0, retired 3 (source lost)), the metric is shc_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.

KeyTypeDefault
maintenance.event_message_max_bytesint (bytes)0 (defer to the fixed 8 KiB floor)
maintenance.event_payload_max_bytesint (bytes)32768 (32 KiB)
maintenance.event_coalesce_window_secondsint (seconds)60 (0 = off)
maintenance.event_coalesce_max_per_windowint10 (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”
KeyTypeDefault
maintenance.audit_retention_daysint (days)365: the shortest retention that answers what happened in the last fiscal year; 0 = unbounded
maintenance.audit_max_rowsint0 (off)
maintenance.event_audit_retention_daysint (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_rowsint0 (off)
maintenance.audit_coalesce_window_secondsint (seconds)0 (never)
maintenance.audit_coalesce_max_per_windowint0 (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”
KeyTypeDefault
maintenance.vault_read_audit_window_secondsint (seconds)60; 0 restores a synchronous row per read
maintenance.vault_read_audit_max_keysint1024, the bound on the in-memory digest table
maintenance.vault_read_audit_steady_attest_secondsint (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.

KeyTypeDefault
backup.reponull | strnull; required, no default
backup.passwordnull | strnull; required, no default
backup.secrets_passwordnull | strnull; a ref+vault:// reference only
backup.secrets_keynull | strnull; 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_idnull | strnull
backup.aws_secret_access_keynull | strnull
backup.azure_account_namenull | strnull
backup.azure_account_keynull | strnull
backup.b2_account_idnull | strnull
backup.b2_account_keynull | strnull
backup.google_application_credentialsnull | strnull
backup.retention.dailynull | intnull
backup.retention.weeklynull | intnull
backup.retention.monthlynull | intnull
backup.retention.yearlynull | intnull

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 into backup.repo and refuses without backup.password. The shc backup schedule cron, 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 .bak into backup.repo under backup.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 by backup create --all-connected / --with-dependants and by backup 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. Mode 0600 in a 0700 directory, and never pruned by retention: delete it yourself. Between clusters that share a backup.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 export output: 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.

KeyTypeDefaultNotes
concurrency.queue_max_depthint1000Queue backpressure ceiling (hot-reloadable).

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:

KeyTypeDefaultNotes
deploy.placement_scoringstronWhether 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.disruptionstrrollingWhat 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.
KeyTypeDefault
acme.emailnull | strnull
acme.wildcardsnull | 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:

Terminal window
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.

KeyTypeDefault
dns.providernull | strnull (null disables managed DNS)
dns.owner_idstrwritten by shc init: this cluster’s DNS ownership identity; global
dns.providers.<name>.*mapnull; open prefix, per-provider credentials/config
dns.public_addressstrunset; the non-internet entrypoint, scoped
dns.lan_addressstrunset; the published non-internet address, scoped
dns.private_recordsboolunset (on); false drops the private-plane record, scoped
dns.ttlint300 (1..86400); scoped
dns.proxiedboolfalse (Cloudflare orange-cloud); scoped
dns.externally_published_zonesstrunset; 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>.

KeyTypeDefault
vault.providernull | strnull (null disables ref+vault resolution)
vault.providersnull | mapnull

OTLP-HTTP export. otel.provider selects a otel.providers.<name> blob; when unset a managed default (system openobserve behind SHC_HOST) engages.

KeyTypeDefault
otel.enabledboolunset (= 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.providernull | strnull
otel.providersnull | mapnull; per-provider {endpoint, insecure, url_path_base, headers}
otel.filter.quietnull | str | listnull; 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.rulesnull | str | listnull; 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).

KeyTypeDefault
notification.providersnull | mapnull; named transports (type: email|ntfy|slack|discord|webhook)
notificationsnull | listnull; 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
KeyTypeDefault
storage.volumes.providernull | strnull: select a volume-capable connection by name; its credentials supply the token and region
storage.volumes.auto_failoverboolfalse: OFF by default; auto-rebind an RWO volume off a dead node only after it is provably stopped
storage.volumes.hcloud.filesystemnull | strnull: the filesystem a node formats a new Hetzner volume with; null is ext4. Read for a Hetzner volume connection

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.

KeyTypeDefault
scheduler.grace.statelessduration60s
scheduler.grace.memberduration5m
scheduler.prioritylow | normal | highnormal
scheduler.moves_per_minuteint6
scheduler.disk_markint (percent)80
scheduler.disk_mark_freesize100Gi

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.

KeyTypeDefault
health.reconcile_enablednull | boolnull (null = follow cluster-mode default, leader-only)
health.check_infrastructurebooltrue
health.check_docker_networksbooltrue
health.adopt_keycloak_realmsbooltrue: 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)
KeyTypeDefault
publish.listenselector stringunset (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.

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.

KeyTypeDefault & notes
cluster.address_quarantineduration1h: 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_rotationduration or off30d: 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.
KeyTypeDefault & notes
store.replica_everyint50: 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.
KeyTypeDefault & notes
console.realmstrmaster: 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.

DB-backed scoped overrides follow the one SHC scope ladder; the most specific wins (core/scope):

  1. Deployment: tenant + stack + environment (-t X -s Y -e Z, --scope deployment)
  2. Stack: tenant + stack (-t X -s Y, --scope stack)
  3. Environment: tenant + environment (-t X -e Z, --scope environment)
  4. Tenant: tenant (-t X, --scope tenant)
  5. Global: base (--scope global)

Stack outranks Environment. The same ladder orders vault secret resolution.

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.

KeyRead only at
acme.defaultglobal
modules.*global
proxy.proxy_protocol_trusted_ipsglobal
storage.volumes.provider, storage.volumes.hcloud.filesystem, storage.volumes.auto_failoverglobal
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_ttlglobal
lease.protected_environmentsglobal
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_volumesglobal
publish.listenglobal
console.realmglobal

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.

Keys fall into three activation classes, and shc config set prints which one it just wrote:

ClassMeaningExamples
livepicked up by the next reconcile sweepacme.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
installbaked 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-restartcaptured once while the daemon builds its services; restart shcd on every nodekeycloak.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:

KeyDefaultMeaning
container_broker.default_cpus1CPUs for a brokered container whose create names none
container_broker.default_memory1073741824Bytes of memory for a brokered container whose create names none
container_broker.pids_limit2048The most processes a brokered container may hold
container_broker.max_containers16Brokered containers one deployment may have on a node
container_broker.max_networks8Networks one deployment may have created through its broker on a node
container_broker.max_volumes64Volumes 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):

  1. default.yaml (bundled)
  2. /etc/shc/config.yaml + /etc/shc/config.d/*.yaml (or ~/.config/shc/config.yaml for non-root)
  3. DB-backed scoped overrides (the ladder above)
  4. Environment variables (SHC_*)

Source: core/config/default.yaml.