Switch to AF_UNIX admin socket by default

[DemiMarie]

Issue Details

Nowadays, Windows supports AF_UNIX sockets too. Also, using a TCP listening socket might increase the impact of SSRF vulnerabilities in other applications. Finally, AF_UNIX sockets can be shared between containers and between containers and the host system, whereas localhost sockets are container-local (or at least pod-local).

Assistance Disclosure

AI not used

If AI was used, describe the extent to which it was used.

No response

[pauloappbr]

This is a great proposal. From an operational and container orchestration perspective, switching to AF_UNIX makes a lot of sense. It completely neutralizes the SSRF vector and makes sharing the admin API between containers in the same Kubernetes Pod (via volume mounts) much cleaner and more secure than binding to 0.0.0.0.

However, making this the default behavior right away would be a massive breaking change for existing CI/CD pipelines, Helm charts, and local automation scripts that hardcode localhost:2019.

A safer migration path might be:

Introduce the AF_UNIX socket as a natively supported and easily toggleable option first (e.g., via an environment variable like CADDY_ADMIN_SOCKET=unix or a simple global config).

Update the Caddy CLI (caddy reload, caddy stop, etc.) to implement a smart fallback: try the unix socket first, and if it fails or doesn't exist, fall back to localhost:2019.

Schedule the actual default switch for a major release (like Caddy 3.0), giving the ecosystem time to adapt.

This way, we get the security benefits for modern containerized environments without instantly breaking backward compatibility for thousands of existing setups.

[DemiMarie]

I like this plan, but it might be better to be able to set the socket in a global configuration file somewhere as well as via an environment variable. That’s harder to forget when using the CLI interactively.

try the unix socket first, and if it fails or doesn't exist, fall back to localhost:2019.

I think this only makes sense if it doesn’t know that the unix socket should exist.

[francislavoie]

That was the original plan to do it for certain deployment methods after we added the env var in #5332 but we never got around to finishing it because it needs to be robust and work end-to-end. The env var on its own is fine, but once you realize users will probably be running caddy commands (reload, trust, stuff like that) as their own user without that env var set, and our current approach of pulling the admin address from the specified config would be insufficient if the main process used CADDY_ADMIN env to change the default.

[steadytao]

I think the main point is that the hard part here is not server-side AF_UNIX support by itself, it is making the whole admin workflow work end-to-end.

In other words, the default only becomes viable once Caddy commands like reload, stop, trust, etc. can reliably find the active admin endpoint even when the running process got it from CADDY_ADMIN or some deployment-specific setup.

So this still seems like a good direction to me, but more as a staged migration than a direct default flip:

1. make AF_UNIX fully robust as an explicit/admin-configured option
2. make CLI/admin endpoint discovery work reliably across that setup
3. only then consider whether a default switch makes sense, probably in a major release or for specific deployment methods first

Without that, switching the default seems more likely to break automation than to help users immediately.