Skip to content

docs: document validate conflicts with exclusive resources #569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
faiyazrahmann wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: document validate conflicts with exclusive resources #569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/docs/markdown/caddyfile/directives/acme_server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ An embedded [ACME protocol](https://tools.ietf.org/html/rfc8555) server handler.

When enabled, requests matching the path `/acme/*` will be handled by the ACME server.

The ACME server keeps a database on disk, and only one process can have it open at a time. This means [`caddy validate`](/docs/command-line#caddy-validate) fails with a database timeout if it is run while Caddy is already serving this config, because validating provisions the modules for real. Validate before starting Caddy, or use [`caddy reload`](/docs/command-line#caddy-reload) to check a config against the running instance: reload provisions the new config within the running process, so it does not contend for the database. If provisioning fails, the active config keeps running; if it succeeds, the new config is applied.


## Client configuration

Expand Down
2 changes: 2 additions & 0 deletions src/docs/markdown/command-line.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -688,6 +688,8 @@ Similarly to `caddy upgrade`, replaces the current Caddy binary with the latest

Validates a configuration file, then exits. This command deserializes the config, then loads and provisions all of its modules as if to start the config, but the config is not actually started. This exposes errors in a configuration that arise during loading or provisioning phases and is a stronger error check than merely serializing a config as JSON.

Because modules are provisioned for real, this command is best run before starting Caddy. Some modules acquire exclusive resources while being provisioned, and a second Caddy process cannot acquire them while a running instance holds them. For example, the [`acme_server`](/docs/caddyfile/directives/acme_server) directive opens a database that only one process can have open at a time, so validating a config that uses it while Caddy is already running fails with a database timeout, even though the config itself is fine. To check a config against a running instance, use [`caddy reload`](#caddy-reload) instead: it provisions the new config within the running process, so it does not contend with the running instance for those resources. If provisioning fails, the active config keeps running; if it succeeds, the new config is applied.

`--config` is the config file to validate. If `-`, the config is read from stdin. Default is the `Caddyfile` in the current directory, if any.

`--adapter` is the name of the config adapter to use. This flag is not necessary if the `--config` filename starts with `Caddyfile` or ends with `.caddyfile` which assumes the `caddyfile` adapter. Otherwise, this flag is required if the provided config file is not in Caddy's native JSON format.
Expand Down