Configuring the daemon: daemon.json

What daemon.json is

dockerd reads /etc/docker/daemon.json when it starts. It's the one place to set host-wide behaviour: how logs are rotated, where images and volumes are stored, which registries are mirrored or trusted, which IP ranges Docker may use, and more. It doesn't exist until you create it. Rootless Docker reads ~/.config/docker/daemon.json instead, and Docker Desktop has an editor for it under Settings → Docker Engine.

A sensible starting file

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "live-restore": true,
  "default-address-pools": [
    { "base": "10.200.0.0/16", "size": 24 }
  ],
  "bip": "10.199.0.1/24",
  "registry-mirrors": ["https://registry.lab.local:5001"]
}

Plain JSON: no comments, no trailing commas, and values in log-opts must be strings ("3", not 3).

The settings that matter

Apply a change safely

$ sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
$ sudoedit /etc/docker/daemon.json
$ sudo dockerd --validate --config-file /etc/docker/daemon.json
configuration OK
$ sudo systemctl reload docker        # if every changed key is reloadable
$ sudo systemctl restart docker       # otherwise
$ docker info | grep -A3 -E 'Logging Driver|Registry Mirrors|Docker Root Dir'

• Reload (SIGHUP) applies a subset of settings without touching containers. It includes, among others, debug, log-level, labels, live-restore, registry-mirrors, insecure-registries and the max-concurrent-* download/upload limits. Docker's documentation for dockerd lists the reloadable options for your version.
• Restart is needed for everything else (data-root, bip, default-address-pools, log-driver, storage-driver ...). Without live-restore, a restart stops all containers; those with a restart policy come back up.
• Log and default-network settings apply only to containers created afterwards. Recreate existing ones to pick them up.

Proxies for the daemon

On a network where the internet is behind a proxy, docker pull is done by dockerd, not your shell, so your shell's HTTPS_PROXY doesn't help. Two ways:

{
  "proxies": {
    "http-proxy": "http://proxy.corp.local:3128",
    "https-proxy": "http://proxy.corp.local:3128",
    "no-proxy": "localhost,127.0.0.0/8,registry.lab.local,.corp.local"
  }
}

or, on older engines, a systemd drop-in:

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTPS_PROXY=http://proxy.corp.local:3128"
Environment="NO_PROXY=localhost,127.0.0.0/8,registry.lab.local"

followed by sudo systemctl daemon-reload && sudo systemctl restart docker. Put your internal registries in no-proxy, or pulls from them go to the proxy and fail. Proxy settings for containers and builds are separate: they go in the client's ~/.docker/config.json under proxies.

When Docker won't start

$ sudo systemctl restart docker
Job for docker.service failed because the control process exited with error code.
$ journalctl -u docker -n 20 --no-pager
... unable to configure the Docker daemon with file /etc/docker/daemon.json: invalid character '}' looking for beginning of object key string

The three usual causes:

1. Invalid JSON, usually a trailing comma. dockerd --validate or python3 -m json.tool points at it.
2. Unknown or misspelt key ("registry-mirror" without the s). The error names the key.
3. The same setting as a flag and in the file, typically hosts, because the distribution's unit starts dockerd -H fd://. Remove it from one place. To manage hosts in daemon.json, override ExecStart with a systemd drop-in that has no -H flag.

Restore the backup to get the host running again first, then fix the change calmly.

Recap

• /etc/docker/daemon.json configures the whole host. Plain JSON, strings in log-opts.
• Always set log rotation; consider live-restore, default-address-pools/bip, registry-mirrors, data-root.
• Validate before applying. Reload covers a subset of keys; the rest needs a restart. Log/network defaults need containers recreated.
• Won't start? journalctl -u docker: bad JSON, unknown key, or a flag/file conflict (hosts).