Storage

The persistence layer for TLS state and any other module that needs a key/value store across reloads. Defined in storage.go.

Purpose

Provide a certmagic.Storage to all of Caddy. CertMagic uses it for:

• Storing managed certificates and their private keys.
• OCSP staple cache.
• ACME account state and lock files for cluster coordination.

Other modules may persist their own data through the same interface — anything that should survive a reload but not need a real database.

Directory layout

Path	Role
storage.go	StorageConverter interface, HomeDir, DataDir, default storage path
modules/filestorage/	The default file-system backend (module ID caddy.storage.file_system)
External plugins	Other backends (Redis, S3, Consul, etc. — not in this repo)

Key abstractions

Type	Where	Description
certmagic.Storage	github.com/caddyserver/certmagic	The actual interface (Store, Load, Delete, List, locks)
StorageConverter	storage.go	Module interface for converting a Caddy module into a certmagic.Storage
FileStorage	modules/filestorage/filestorage.go	The default backend; CertMagic provides the implementation
DataDir()	storage.go	OS-appropriate path: $XDG_DATA_HOME/caddy, ~/Library/Application Support/Caddy, %AppData%\Caddy, or under /var/lib/caddy for systemd

How it works

graph TD
    Config["Config.StorageRaw<br/>caddy:namespace=caddy.storage inline_key=module"] --> Provision[caddy.Load]
    Provision -->|LoadModule| Mod[storage module]
    Mod -->|StorageConverter.CertMagicStorage| StoreImpl[certmagic.Storage impl]
    Provision -->|set on Config and certmagic.Default| Global[global storage]
    Global -->|read/write certs, OCSP, locks| Disk
    Modules -->|ctx.Storage| Global

When a config loads, the storage module from Config.StorageRaw is loaded and asked for a certmagic.Storage. That storage becomes the default for CertMagic operations and is also available via ctx.Storage() for any module that wants to use it.

Default location

If no storage is configured, Caddy uses caddy.storage.file_system rooted at DataDir(). The exact path depends on the OS:

• Linux: $XDG_DATA_HOME/caddy (typically ~/.local/share/caddy) for non-root, /var/lib/caddy when running as a system service.
• macOS: ~/Library/Application Support/Caddy.
• Windows: %AppData%\Caddy.

These paths are computed in storage.go: DataDir().

StorageConverter indirection

A storage module doesn't return a Caddy-specific type — it returns a certmagic.Storage directly. The StorageConverter interface is the seam:

type StorageConverter interface {
    CertMagicStorage() (certmagic.Storage, error)
}

This is because CertMagic predates the v2 module system and has its own interface; Caddy adapts modules into it without importing CertMagic into every plugin.

Test override

caddy.go exposes a package-level testCertMagicStorageOverride so test code can inject in-memory storage and avoid touching disk. It's documented as a test hook only; production code must not set it.

Integration points

• tls app: the heaviest user. CertMagic's cache is configured to use this storage.
• pki app: persists CA private material under a subdirectory keyed by CA ID.
• Cluster mode: when multiple Caddy instances share a storage backend (e.g. Redis/S3 via plugins), they coordinate ACME issuance through CertMagic's locking.

Entry points for modification

• A new backend? Build a separate Go module that registers a caddy.storage.<name> module and implements StorageConverter. The repo intentionally doesn't ship more backends to keep the binary lean.
• A new well-known path? Edit DataDir() in storage.go.

Related pages

• TLS app
• PKI app
• Reference: configuration