Using the Caddy Admin API

Caddy has two configuration surfaces. The Caddyfile is the human surface: a small, forgiving text format that the server adapts into JSON before it runs anything. The admin API is the machine surface: a REST interface over that very same JSON, published by the running server on a local HTTP endpoint. Most people meet it for the first time when a deployment script needs to add a site without restarting the server. By the end of this page you will be able to read the configuration a running server is actually using, replace it atomically, change one small part of it without touching the rest, and coordinate several writers so that they cannot silently overwrite each other.

1. What the admin endpoint is

Every Caddy process starts a small HTTP server that exists only to administer that process. It listens on localhost:2019 by default, is bound to the loopback interface, and is not reachable from the network unless you deliberately change that.

The endpoint speaks plain HTTP with JSON bodies. It is not a separate daemon, not a plugin, and not optional in the usual sense: it is part of the server process, so it starts and stops with it. Because the API is how caddy reload pushes a new configuration into an already-running server, disabling the endpoint also disables reload.

The default address can be changed with the CADDY_ADMIN environment variable. A value in the configuration file always wins over the environment variable, and the environment variable always wins over the compiled-in default.

2. Enabling and securing the endpoint

The admin global option controls the endpoint. The default is equivalent to admin localhost:2019.

{
	admin localhost:2019
}

The endpoint carries the authority to replace the entire configuration of the process, so exposing it is a decision that deserves scrutiny. There are three shapes worth knowing.

Loopback, the default. Only processes on the same machine can reach it. This is the right choice for almost every deployment, because a deployment script can always run on the host.

A unix socket. Access is then controlled by file permissions rather than by the network, which removes the network entirely from the trust question.

{
	admin unix//run/caddy-admin.sock
}

The double slash is intentional: it is the way to say “this is a path, not a host and port”. The process user must be able to bind that path, so it belongs in a directory the service account owns, for example a RuntimeDirectory created by the systemd unit. Creating an empty file at the path is not enough, because Caddy has to bind the socket itself.

A routable address. This is possible and dangerous.

{
	admin :2020
}

A wildcard interface means the Host header is not validated, and anyone who can reach the port can take over the server. If you must do this, constrain it with origins and turn on enforce_origin.

{
	admin :2020 {
		origins https://ops.example.com
		enforce_origin
	}
}

origins lists the origins permitted to connect. enforce_origin forces the Origin request header to be checked against that list and enables the CORS preflight that goes with it. The default is chosen sensibly: for a loopback address the allowed origins are localhost, ::1 and 127.0.0.1 joined with the listen port, and for any other address the origin is the listen address itself.

Turning the endpoint off entirely is possible and has a real cost.

{
	admin off
}

With the endpoint off, the only way to change configuration is to stop the server and start it again, which means downtime. caddy reload fails, because reload is implemented as an API call.

3. Reading what is running

The simplest read is the whole configuration.

curl -s http://localhost:2019/config/ | jq

The response is the native JSON that Caddy is running right now, including everything implied by the Caddyfile: the routes the adapter generated, the TLS policies, the log definitions. Reading this is the fastest way to answer the question “what is the server actually doing”, because it shows the result of the adapter rather than your intention.

Any subpath of the configuration can be read the same way, and the path is the same one you would use to write to it.

# The listener addresses of one HTTP server
curl -s http://localhost:2019/config/apps/http/servers/srv0/listen | jq

# The upstreams of one reverse proxy handler
curl -s http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0/upstreams | jq

Two other reads are worth knowing. GET /id returns the identifier of the running server, which is useful in logs and in scripts that need to confirm they are talking to the instance they think they are. GET /reverse_proxy/upstreams returns the live state of the proxy pool as a JSON array.

curl -s http://localhost:2019/reverse_proxy/upstreams | jq
[
	{ "address": "10.0.1.1:80", "num_requests": 4, "fails": 2 },
	{ "address": "10.0.1.2:80", "num_requests": 5, "fails": 4 },
	{ "address": "10.0.1.3:80", "num_requests": 3, "fails": 3 }
]

num_requests counts the requests currently being handled by that upstream, and fails counts the failures remembered by the passive health checker. Together with the max_fails and unhealthy_request_count settings of the handler, they tell you whether a backend is healthy. Reading this endpoint is a cheap health probe for the proxy layer specifically.

4. Replacing the whole configuration

POST /load sets the active configuration. The request body is the new configuration, and the Content-Type header tells Caddy how to interpret it.

curl "http://localhost:2019/load" \
	-H "Content-Type: application/json" \
	--data-binary @caddy.json

To send a Caddyfile instead, use the matching content type, and use --data-binary rather than -d, because curl -d collapses the newlines that the Caddyfile parser depends on.

curl "http://localhost:2019/load" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

The request blocks until the reload has finished or failed. Three properties make this safe to use in production.

It is atomic. The new configuration is provisioned and started before the old one is retired. If anything fails, the old configuration is rolled back into place and the server keeps serving. There is no window in which neither configuration is live.

It has no downtime. In-flight requests finish on the old configuration while new requests arrive on the new one.

It is idempotent. If the new configuration is identical to the current one, nothing happens. To force a reload anyway, which is useful when you have replaced a certificate file on disk, add the header Cache-Control: must-revalidate.

curl "http://localhost:2019/load" \
	-H "Content-Type: text/caddyfile" \
	-H "Cache-Control: must-revalidate" \
	--data-binary @Caddyfile

A successful response has an empty body. If the adapter produced warnings, the body instead contains a warnings array. If the configuration could not be adapted or loaded, the status is 400 and the body explains what went wrong.

{
	"error": "loading config: ...",
	"warnings": [
		{ "file": "Caddyfile", "line": 2, "message": "..." }
	]
}

Warnings deserve attention even on a 200. Caddy starts the configuration anyway, but a warning usually means the adapter had to guess.

5. Changing one thing

Loading the entire configuration is wasteful when the goal is to add a single listener, and dangerous when other people are editing the same server. The /config/ paths let you write to one location.

MethodBehaviour on an arrayBehaviour on an object
POSTAppends the payload to the arrayCreates or replaces the value
PUTInserts the payload at the given indexStrictly creates a new value
PATCHReplaces the element at the given indexStrictly replaces an existing value
DELETERemoves the value at the pathRemoves the value at the path

Adding a listener address to an existing server is a POST.

curl "http://localhost:2019/config/apps/http/servers/srv0/listen" \
	-H "Content-Type: application/json" \
	-d '":8080"'

The path may end in /..., in which case an array payload is expanded and every element is appended individually.

curl "http://localhost:2019/config/apps/http/servers/srv0/listen/..." \
	-H "Content-Type: application/json" \
	-d '[":8080", ":5133"]'

Removing one HTTP server while leaving the rest of the process alone is a DELETE.

curl -X DELETE "http://localhost:2019/config/apps/http/servers/srv0"

Deleting the entire configuration with DELETE /config/ unloads everything but keeps the process alive. That is the difference between “take this server out of service” and “shut the machine down”, and POST /stop is the second one.

curl -X DELETE "http://localhost:2019/config/"
curl -X POST "http://localhost:2019/stop"

6. Stable paths with @id

Raw config paths are long and fragile. If you add a route in the middle of a server, every index-based path below it shifts. The API lets you name a part of the configuration so that you can address it directly.

Add an @id field to any object in the JSON.

{
	"@id": "my_proxy",
	"handler": "reverse_proxy"
}

Then reach it through /id/ instead of walking down from the root.

curl -s "http://localhost:2019/id/my_proxy/upstreams" | jq

The path /config/apps/http/servers/myserver/routes/1/handle/0/upstreams becomes /id/my_proxy/upstreams, which is short enough to type by hand and stable against unrelated edits. Any object can carry an @id, and the name must be unique within the configuration.

7. Adapting without loading

POST /adapt runs the config adapter and returns the JSON without applying it. This is the API counterpart of caddy adapt, and it is the right way to check what a Caddyfile becomes before you commit to it.

curl "http://localhost:2019/adapt" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile | jq

The content type selects the adapter in exactly the same way as /load. Because the file is never loaded, this is safe to run against a production server and is a good way to answer the question “what does this directive expand into”.

8. Inspecting the internal certificate authority

Caddy can run its own certificate authority. Two endpoints expose it. GET /pki/ca/local returns information about the CA, including the root and intermediate certificates, and provisions the CA if it has not been provisioned yet.

curl -s http://localhost:2019/pki/ca/local | jq

GET /pki/ca/local/certificates returns the certificate chain, which is what the caddy trust command installs into a local trust store. The local identifier is the default CA; any other identifier must have been provisioned before it will answer.

9. Letting several writers coexist

Each individual request to the config API is atomic, but the API has no transactions spanning multiple requests, and HTTP has no locking. If two clients read the same part of the configuration, edit it, and write it back at the same time, one of them will overwrite the other or leave the configuration in a state neither of them intended.

Caddy solves this with optimistic concurrency control. Every response to a config read carries an ETag header that encodes the path and a hash of the content in that scope. Send that value back as If-Match on the write, and Caddy rejects the write if the scope has changed underneath you.

# 1. Read the scope and remember its tag.
etag=$(curl -sD - -o scope.json \
	"http://localhost:2019/config/apps/http/servers/srv0" \
	| awk '/^ETag:/ {print $2}' | tr -d '\r')

# 2. Edit scope.json however you like.

# 3. Write it back, but only if nothing changed in the meantime.
curl -X PATCH "http://localhost:2019/config/apps/http/servers/srv0" \
	-H "Content-Type: application/json" \
	-H "If-Match: $etag" \
	--data-binary @scope.json

If the scope changed, the response is 412 Precondition Failed. At that point you read it again, reapply your change, and try once more. Two writers touching different scopes never conflict, so the retry only matters when the same part of the configuration is being changed by both.

10. Surviving a restart

Unless you disable it, the current configuration is written to disk after every change made through the API. That means a process that was started empty can come back after a reboot with the configuration it was running.

caddy run --resume

--resume starts Caddy with the last saved configuration instead of a file on disk. This is the natural pairing for an API-driven deployment: the API owns the configuration, and the process keeps running across reboots without a separate configuration file to keep in sync.

11. Common mistakes

MistakeWhat happensCorrection
Exposing the admin endpoint on a public addressAnyone who can reach it controls the serverKeep the loopback default, or use a unix socket
Using curl -d with a CaddyfileNewlines are stripped and the parse failsUse --data-binary
Expecting a POST /load to always reloadIdentical configuration is a no-opSend Cache-Control: must-revalidate
Writing to a long numeric config pathThe path shifts when a route is insertedPut an @id on the object and address it through /id/
Two scripts editing the same scopeThe second write silently discards the firstUse ETag and If-Match
Turning the endpoint off and then trying to reloadReload is impossible without itKeep the endpoint enabled, or accept restarts with downtime
caddy admin apidynamic configurationhot reloadjson config

Approach:

The goal is to add a new site to a server that is already serving traffic, without restarting it and without disturbing the sites that are already there. The naive way, reloading a complete configuration file, works but is coarse: it rewrites everything, it needs the whole file to be correct on the machine doing the deploy, and it is unsafe if anything else is editing the same server. The API offers a better path, but only if the change is scoped, addressed by a stable name, and guarded against concurrent writers.

Steps:

  1. Confirm the endpoint is reachable and that you know which process you are talking to. GET /id returns the server identifier, and GET /config/ returns the configuration currently in force. If the endpoint listens somewhere other than localhost:2019, pass --address to the CLI commands or set CADDY_ADMIN.
  2. Read the existing configuration with GET /config/ and keep the response. This is the source of truth, not the Caddyfile on disk, because it shows what the adapter actually produced.
  3. Decide the smallest useful change. Adding a site means adding a route, which in practice means adding to the routes array of an existing HTTP server, or adding a new HTTP server entirely.
  4. Give the new object a stable name. Put an @id field such as "@id": "new_site" on the object you are creating, so that later updates do not depend on array positions.
  5. Capture the ETag of the scope you are about to modify from the response headers of the read in step 2.
  6. Write the change with POST on the config path, using Content-Type: application/json and the --data-binary form of curl so the JSON is sent byte for byte. An array payload appended to an array is expanded when the path ends in /....
  7. Send the ETag from step 5 as If-Match. A 200 means the change was applied; a 412 means someone else changed the same scope in the meantime, so read the scope again and retry.
  8. Verify with GET /id/new_site that the new object is in place, then make a real request to the new hostname to confirm the route serves traffic.

Answer:

The site is added with three API calls and no restart. The first is a read that establishes both the current state and the concurrency token.

curl -sD headers.txt -o config.json "http://localhost:2019/config/"

The second is the write, scoped to the routes array of the server that should handle the new hostname, with the token from the read attached.

etag=$(awk '/^ETag:/ {print $2}' headers.txt | tr -d '\r')

curl -X POST "http://localhost:2019/config/apps/http/servers/srv0/routes/..." \
	-H "Content-Type: application/json" \
	-H "If-Match: $etag" \
	--data-binary @route.json

where route.json is a single route object carrying a stable name.

{
	"@id": "new_site",
	"match": [{ "host": ["new.example.com"] }],
	"handle": [{ "handler": "static_response", "body": "hello" }]
}

The third is the verification.

curl -s "http://localhost:2019/id/new_site" | jq
curl -I https://new.example.com

The result is that the new hostname is served, the existing sites keep running on the old configuration until their own requests drain, the change was rejected rather than silently merged if another writer touched the same scope, and the server was never restarted, so there was no downtime and no effect on certificate issuance for the other sites.

Found an issue with this content?

Tell us what could be improved.