Daemon Configuration, daemon.json, systemd, Proxies, Registry Mirrors, Live Restore, and Host Integration: Concepts, Architecture, and Mental Model

1. The practical problem: Docker is a host service, not just a CLI

Most Docker commands feel local: a developer types docker run, docker pull, or docker compose up. But the durable policy is owned by the Docker daemon on the selected context. If that daemon is started by systemd, its executable arguments, environment, drop-in files, and daemon.json all affect every workload attached to that Engine.

This is why a “simple” change such as adding a proxy, changing a registry mirror, moving data storage, enabling live restore, or adding a daemon label can have host-wide consequences. The safe workflow is identify owner → capture current effective state → validate proposed state → classify reload/restart impact → apply in an authorized scope → verify → roll back deliberately.

2. Causal daemon-policy model

flowchart TD
  A[Host service manager + environment] --> D[dockerd startup]
  B[dockerd CLI flags] --> D
  C[daemon.json] --> D
  D --> E[Effective daemon policy]
  E --> F[Networking / storage / registry / logging / security]
  E --> G[Running containers]
  H[SIGHUP or systemd reload] --> E
  I[Daemon restart or outage] --> G
  J[live-restore when eligible] --> G
            

Service manager + environment decides how dockerd is launched. CLI flags provide startup configuration. daemon.json is Docker’s preferred persistent configuration source for regular Engine installations. The daemon merges allowed sources, rejects duplicate ownership of the same option, and then applies the resulting policy to registry access, networking, storage, logging, security defaults, and container lifecycle.

A reload asks an already-running daemon to re-read only settings Docker declares reloadable. A restart replaces the daemon process and may interrupt management or containers unless continuity mechanisms and the specific configuration transition support survival. Live restore helps in a bounded set of scenarios; it is not a universal “safe restart” switch.

3. State map: what belongs to which layer?

4. Configuration files and ownership

On a regular Linux Engine installation, Docker looks for /etc/docker/daemon.json by default. Rootless Docker uses per-user configuration rather than the system path. Docker Desktop exposes Engine JSON through Desktop settings and is not managed like a native Linux systemd service.

Docker recommends the configuration file because it centralizes persistent settings. Flags remain useful for packaging, service-manager ownership, testing, or settings the distribution already provides. The rule is strict: do not specify the same option in both places. Docker documents that a duplicate flag/JSON option prevents daemon startup.

5. Systemd is part of the effective configuration

On mainstream Linux distributions, systemd often owns dockerd. A packaged unit can already supply flags such as socket activation or host configuration. Drop-ins under the systemd hierarchy can add environment variables or override ExecStart. Therefore an incident review should capture the unit and drop-in paths before editing JSON.

6. Read-only host inventory before any mutation

docker context show
docker version
docker info
docker info --format 'DockerRootDir={{.DockerRootDir}} Driver={{.Driver}} Logging={{.LoggingDriver}}'

docker context inspect "$(docker context show)"

# Native Linux/systemd host only:
systemctl show docker --property=FragmentPath,DropInPaths,MainPID,ActiveEnterTimestamp
systemctl status docker --no-pager
ps -eo pid,args | grep '[d]ockerd'

# Inspect these privately if authorized; redact credentials before archiving:
# sudo systemctl cat docker
# sudo cat /etc/docker/daemon.json

These commands establish endpoint identity, daemon/server version, storage/logging baselines, service-manager ownership, and startup arguments. If the context is remote, the shell commands describe the client host, not the remote daemon host; do not mix those evidence sets.

7. Validate proposed JSON before starting or restarting

dockerd --validate --config-file=<path> parses a candidate configuration without starting a daemon. Invalid directives or malformed configuration return a non-zero status. Engine 29 validation also performs more system-requirement checks than older tutorials may imply, so validation can surface host prerequisites in addition to JSON syntax.

cat > /tmp/dca33-valid.json <<'EOF'
{
  "labels": ["devops-academy.chapter=33"]
}
EOF
sudo dockerd --validate --config-file=/tmp/dca33-valid.json

This validates a harmless candidate. It does not prove that a later reload/restart will preserve every workload, nor does it prove an external proxy or registry is reachable. Validation is one gate, not the whole rollout.

8. Daemon proxy is not container proxy

The daemon needs outbound proxy configuration when dockerd itself must reach registries or other Engine-side endpoints. Current Docker Engine supports daemon proxy fields in daemon.json, daemon CLI flags, or startup environment variables; command-line/config-file settings take precedence over environment variables.

By contrast, Docker CLI proxy configuration in ~/.docker/config.json can inject proxy environment variables/build arguments into new containers and builds. That changes application/build behavior, not the daemon’s own network path. Treat these as separate trust and secret-distribution surfaces.

9. Registry mirror versus registry trust

A registry mirror is a pull-through cache policy, commonly for Docker Hub. The daemon’s registry-mirrors setting tells Docker where to request mirrored content. A mirror can improve pull latency, reduce duplicate external transfers, or centralize egress, but it also becomes a supply-chain and availability dependency.

Do not confuse a mirror with an insecure registry. Docker assumes registries are secure by default. For private TLS endpoints, install the correct CA trust rather than globally weakening transport verification. Docker’s mirror documentation also warns that configuring mirror credentials for private Hub content can expose whatever that identity is authorized to fetch unless the mirror itself is properly secured.

10. Reload is selective, not magical

On Linux, Docker can reload a documented subset of options through SIGHUP (commonly systemctl reload docker). Current reloadable settings include items such as debug, daemon labels, live-restore, download/upload concurrency, runtimes, authorization plugins, insecure registries, registry mirrors, shutdown timeout, and feature settings.

Everything else must be classified from current documentation rather than assumed reloadable. In particular, a storage-root, bridge, or other startup-sensitive change should be planned as a restart/migration event, not tested by repeatedly sending SIGHUP.

11. Live restore: continuity with strict boundaries

By default, daemon termination shuts down running containers. With live restore enabled, eligible standalone Linux containers can remain running while the daemon is unavailable. Docker documents support for patch-level daemon upgrades when options remain compatible, not arbitrary major upgrades or storage/network architecture changes.

Live restore also has operational limits: if the daemon stays down long enough, a container that keeps writing logs can fill the FIFO buffer and block on logging. It applies to standalone containers, not Swarm service management. On Docker Desktop for Windows, live restore can work for Linux containers, but native Windows containers are not supported.

12. Restart timestamps and continuity evidence

A configuration rollout should be able to answer: Did the daemon process restart? Did a container restart? Did the process inside the container change PID? Was an externally reachable request continuously successful? Did the daemon reattach cleanly? Capture both daemon and container identities around the change.

# Linux/systemd evidence
systemctl show docker --property=MainPID,ActiveEnterTimestamp

docker inspect -f 'id={{.Id}} restart={{.RestartCount}} pid={{.State.Pid}} status={{.State.Status}}' dca33-test 2>/dev/null || true

13. Security boundary: never expose or weaken the daemon to “make config easier”

The Docker API is effectively host-control authority on a rootful Engine. This chapter never recommends opening an unauthenticated TCP socket, mounting the Docker socket into untrusted containers, disabling TLS verification, or broadly marking registries insecure. Configuration-management convenience does not justify expanding daemon authority.

Chapter 34 will cover Engine API and remote-daemon authentication explicitly. Here, the daemon remains locally managed and configuration changes stay within authorized disposable environments.

Knowledge check

Official references and version notes

• Docker Docs — Docker daemon configuration overview — preferred JSON configuration, default paths, flag/JSON conflicts, and Docker Desktop distinction.
• Docker CLI reference — dockerd — configuration keys, --validate, proxy flags, registry trust, reloadable options, and multi-daemon cautions.
• Docker Docs — Daemon proxy configuration — daemon-side HTTP/HTTPS/NO_PROXY behavior and systemd environment drop-ins.
• Docker Docs — Docker CLI proxy configuration — container/build proxy injection and why it is distinct from daemon egress.
• Docker Docs — Mirror the Docker Hub library — pull-through cache configuration, daemon registry-mirrors, and credential/privacy warnings.
• Docker Docs — Live restore — standalone-container continuity, reload, patch-upgrade scope, configuration-change limitations, FIFO log behavior, and Swarm boundary.
• Docker Docs — Read the daemon logs — platform-specific daemon-log locations and incident evidence.
• Docker Docs — Linux post-installation — systemd service enablement and host-integration context.
• Docker Engine 29 release notes — current Engine 29 behavior, validation changes, fixes, and component updates.
• Docker Official Image — registry — current local OCI Distribution image tags used for the optional mirror simulation.