Persistent runtime state
AuthCrunch normally keeps runtime sessions in memory. The optional state
block saves completed sessions and generated keys so an unchanged installation
can restart without asking every user to sign in again. This is available in
caddy-security v1.3.0 / go-authcrunch v1.3.8.
Enable storage
Add this block inside your existing global security block:
state {
directory /var/lib/authcrunch/runtime
}
Choose a stable absolute directory outside temporary or release directories. The service creates missing storage privately; an existing directory must have owner-only permissions. The runtime uses 0700 directories and 0600 files. Ensure the service account can create and maintain them. An empty block, root directory, or invalid path is an error, not a request to fall back to memory.
Use a local Unix filesystem and one active process per directory. Network filesystems, sharing between active replicas, and Windows persistence are not supported. File-backed local user databases remain separate from runtime state; an in-memory local database is incompatible with persistence.
Only completed authority crosses a controlled restart. One runtime owns the private state directory and commits completed state synchronously. A full stop/start releases ownership before restoration. Restored credentials keep original expiry and replay history. Pending login, enrollment, consent interactions, and cross-device work remain volatile, while the local identity database is a separate artifact.
What survives a restart
| State | Retained with the same storage and compatible configuration |
|---|---|
| Generated signing keys | Existing generated key material and verification of unexpired tokens |
| Completed portal logins | Unexpired sessions and their original local authentication evidence |
| Portal refresh | Families, deadlines, rotations and complete replay history |
| Direct OAuth authorization | Completed sessions and successful local logout |
| OIDC provider | Completed browser sessions, consent, code/token grants and replay history |
Pending logins, sandbox checkpoints, MFA enrollment, registration and unfinished interactive authorization must start again. Offline time counts toward expiry. Persistent state does not renew upstream OAuth tokens or extend session deadlines.
Keep identity databases, configuration, TLS files, explicit signing keys, OIDC client registrations and provider secrets in their existing locations. Runtime state does not replace any of them. The local database remains the authority for current account status and credential versions.
Deploy with stop/start
- Stop admitting requests and drain the old process.
- Stop Caddy completely and wait for it to release the directory lock.
- Start the replacement using the same service account, public addresses, identity files, state directory and compatible security configuration.
- Verify a pre-restart session, an access denial, renewal if enabled, and logout.
An overlapping reload is rejected because the replacement cannot acquire the old process's storage. Plan this handover in your service manager or container deployment. Multiple workers do not gain shared sessions from a shared volume.
First enabling persistence does not import existing in-memory sessions. Users must sign in again. Changes to the normalized security configuration can also invalidate sessions conservatively, including ordering or unrelated security settings. Diagnostic logging changes and the storage path are excluded from that comparison. Generated keys persist independently of those session changes.
Removing a component and reintroducing it does not restore its previous sessions when the same directory observed both configurations. A dormant directory or old backup can still contain valid authority; returning to it is a recovery decision, not an ordinary way to undo configuration changes.
Back up and recover
Drain and stop the host, then back up the entire state directory together with its configuration, identity databases and explicit key files. Preserve ownership and permissions. Restore a coherent set; do not combine individual records from different backups or edit internal snapshots.
State records are encrypted, but master.key is stored in the same directory.
Treat the complete directory and its backups as credentials. Encrypt backups
and restrict their access. Restoring an older complete matching backup can
restore old authority; plan revocation or a fresh login when recovering.
Corrupt or missing committed files, unsafe permissions, a missing key, and a competing owner fail closed. Failed state writes disable further state-dependent decisions. An interrupted write can discard the affected sessions on reopen; this is preferable to restoring a possibly revoked credential. Do not delete the directory to repair an ordinary startup error: deletion creates new keys and a new installation.
Snapshots are synchronous local files. Measure write latency and storage size under your intended session population before raising capacity. This feature provides restart continuity, not a distributed session database.
Agentic Prompts
Copy a prompt into your LLM to explore this topic. Each prompt prioritizes upstream repository guidance and code over this page, and asks for version-aware reasoning.
Build a persistence map
Help me understand Persistent runtime state.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-state, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/operations/runtime-state
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain the difference between a local identity database and runtime-state
storage. Classify signing keys, completed sessions, refresh/replay families,
downstream OIDC grants, and pending login/MFA/cross-device work. Show what
survives a full stop/start, what expires during downtime, and what remains
volatile.
Plan a single-owner restart
Help me understand Persistent runtime state.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-state, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/operations/runtime-state
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Review a deployment using an absolute private local directory and one
supported process owner. Explain stop admission, drain requests, stop
completely, release ownership, and start the replacement. Compare this with
overlapping Caddy reload, active-active sharing, network storage, and browser
affinity; do not assume they preserve the ownership contract.
Reason about configuration transitions
Help me understand Persistent runtime state.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-state, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/operations/runtime-state
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Compare first enabling state, changing signing material, changing
identity/provider/client/policy settings, changing only logging, and moving
the state directory. Explain conservative session binding and why activation
does not import old in-memory authority. Use the installed implementation to
identify which changes invalidate completed credentials.
Design a coherent backup and restore
Help me understand Persistent runtime state.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-state, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/operations/runtime-state
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Plan a stopped, coherent backup of the full runtime directory, matching local
identities, configuration, and protected keys. Explain the adjacent master
key, encrypted backup handling, account rollback, and dormant sessions. Ask
what external rollback protection exists before treating an older backup as
harmless recovery.
Diagnose a fail-closed storage problem
Help me understand Persistent runtime state.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-state, runtime-state.
Secondary reference:
https://docs.authcrunch.com/docs/operations/runtime-state
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Classify bad permissions, corruption, missing encryption material, competing
ownership, partial restore, and failed writes. Explain which operations must
deny after a storage failure and why deleting state or retrying rotations is
not a routine repair. Propose disposable failure checks and a measured
capacity/latency plan before production changes.
Source Code References
Start with the code search, then follow the parser, runtime, and tests relevant
to this topic. These links target main; use GitHub's branch/tag selector to
compare them with your installed release.
- Search this topic in both repositories — searches topic-specific symbols and paths across both codebases.
- caddy-security: caddyfile_state.go — adapts root persistent-state directory configuration.
- caddy-security: app.go — owns Caddy security-app startup, route admission, and cleanup.
- caddy-security: app_state_test.go — tests persistent startup, admission, ownership, and lifecycle failures.
- go-authcrunch: pkg/state/store.go — opens private state storage and commits named records under exclusive ownership.
- go-authcrunch: pkg/state/codec.go — serializes bounded private snapshots and restores them through the persistent record store.
- go-authcrunch: server_persistent_state.go — derives conservative persistent-session bindings from security configuration.
- go-authcrunch: server_persistent_state_e2e_test.go — tests root-server restart continuity and persistent failure boundaries.