daemon.json — every production-relevant key · Docker & Containers

/etc/docker/daemon.json is the single source of truth for dockerd’s behaviour. It is also the only file on a Docker host that can stop the daemon from starting at all, and a daemon that will not start takes every container with it. That asymmetry — cheap to edit, expensive to get wrong — is what this lesson is really about.

The file does not exist by default on most installations. The daemon runs with built-in defaults until you create it.

A production-shaped daemon.json

/etc/docker/daemon.jsonSensible defaults for a production Linux host. Every key below is documented in the dockerd reference.

"live-restore": true
"data-root": "/var/lib/docker"
"storage-driver": "overlay2"
"log-driver": "json-file"
"log-opts.max-size": "10m"
"log-opts.max-file": "3"
"userland-proxy": false
"no-new-privileges": true
"default-ulimits.nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 }
"default-runtime": "runc"
"exec-opts": ["native.cgroupdriver=systemd"]
"metrics-addr": "127.0.0.1:9323"
"features": { "containerd-snapshotter": true }
"registry-mirrors": ["https://mirror.example.com"]
"hosts": ["unix:///var/run/docker.sock"]

01"live-restore"= true
Keep standalone containers running when dockerd restarts. Reloadable on SIGHUP, so you can turn it on without an outage.
Production: Enable on any host where container uptime matters. Incompatible with Swarm services.
02"data-root"= "/var/lib/docker"
Where images, layers, volumes and container metadata live. Change this to move Docker onto a dedicated filesystem.
Production: Give /var/lib/docker its own filesystem so a runaway image pull cannot fill the root partition.
03"storage-driver"= "overlay2"
Filesystem layering driver. Requires a full daemon restart and, in practice, a rebuild of the data root.
Production: overlay2 on modern Linux. Changing it later orphans every existing image and container.
04"log-driver"= "json-file"
Default log driver for containers created after the change. Not reloadable, and existing containers keep the driver they were created with.
Production: Switch to journald or local where centralised logging exists.
05"log-opts.max-size"= "10m"
Per-log-file size cap before rotation. json-file writes unbounded without it.
06"log-opts.max-file"= "3"
Number of rotated log files to keep.
Production: Budget the worst case: 200 containers x 10m x 3 files is roughly 6 GB before you count the active file.
07"userland-proxy"= false
Stop spawning a docker-proxy process per published port and let the kernel NAT rules do the forwarding.
Production: A real saving at high port counts, but it changes IPv6-to-IPv4 port mapping behaviour. Test before rolling out.
08"no-new-privileges"= true
Applies the no_new_privs kernel bit to every container by default, so a setuid binary inside a container cannot raise privileges.
Production: Default-on unless a specific image genuinely needs setuid (ping on some bases, sudo in dev images).
09"default-ulimits.nofile"= { "Name": "nofile", "Hard": 65536, "Soft": 65536 }
Default file-descriptor limits for containers, so you are not setting --ulimit on every run.
10"default-runtime"= "runc"
Default OCI runtime. Reloadable on SIGHUP, together with the runtimes map.
Production: runc is correct unless a threat model justifies gVisor or Kata as an additional named runtime.
11"exec-opts"= ["native.cgroupdriver=systemd"]
Selects the cgroup driver. Only cgroupfs or systemd are accepted.
Production: Match whatever else on the host manages cgroups. Mixing drivers gives you two managers writing the same tree.
12"metrics-addr"= "127.0.0.1:9323"
Expose the daemon Prometheus endpoint. The documented example binds loopback.
Production: Never 0.0.0.0. The endpoint is unauthenticated and describes your whole host.
13"features"= { "containerd-snapshotter": true }
Feature gates. containerd-snapshotter selects the containerd image store, which is the default on fresh Engine 29.0+ installs and opt-in before that.
Production: Turning it on hides images created under overlay2 until you turn it back off. Plan the migration.
14"registry-mirrors"= ["https://mirror.example.com"]
Pull-through cache for Docker Hub. Reloadable on SIGHUP.
Production: A mirror is the cheapest defence against Hub rate limits and Hub outages.
15"hosts"= ["unix:///var/run/docker.sock"]
Where dockerd listens. Adding a tcp:// entry exposes an unauthenticated root-equivalent API unless TLS is configured.
Production: Leave it alone. See the warning below about the fd:// conflict.

Read-only / Safethe fd:// conflict— A daemon that will not start, and the exact reason in the journal.

$ journalctl -u docker --no-pager -n 3

dockerd[4412]: unable to configure the Docker daemon with file /etc/docker/daemon.json: \
the following directives are specified both as a flag and in the configuration file: \
hosts: (from flag: [fd://], from file: [unix:///var/run/docker.sock tcp://0.0.0.0:2375])
systemd[1]: docker.service: Main process exited, code=exited, status=1/FAILURE
systemd[1]: docker.service: Failed with result 'exit-code'.

Illustrative output

The fix is not to delete daemon.json. It is to stop passing the option twice: add a systemd drop-in that clears ExecStart and re-issues it without -H, so the socket list comes from exactly one place. That drop-in belongs in configuration management, because the next package upgrade rewrites the unit file and not the drop-in.

The reload boundary

“Restart the daemon” is the advice everywhere, and it is usually right — but not always necessary, and knowing the difference is worth real downtime. systemctl reload docker runs ExecReload=/bin/kill -s HUP $MAINPID. The daemon re-reads daemon.json on SIGHUP but only applies a fixed subset of keys.

Reloadable on SIGHUP	Requires a full daemon restart
`debug`	`log-driver`, `log-opts`
`labels`	`storage-driver`, `storage-opts`
`live-restore`	`data-root`, `exec-root`
`max-concurrent-downloads`	`hosts`, `tls*`
`max-concurrent-uploads`	`userland-proxy`
`max-download-attempts`	`no-new-privileges`
`default-runtime`	`exec-opts` (cgroup driver)
`runtimes`	`bip`, `default-address-pools`, `mtu`
`authorization-plugin`	`iptables`, `ip6tables`, `firewall-backend`
`insecure-registries`	`metrics-addr`
`registry-mirrors`	`userns-remap`
`shutdown-timeout`	`default-ulimits`, `default-shm-size`
`features`	everything else

Two consequences fall straight out of that table.

live-restore is reloadable. You can turn it on with a SIGHUP, no container downtime, and only then schedule the restart that needs it. Turning it on and immediately restarting to “make it take effect” is backwards.

log-driver is not reloadable. A systemctl reload docker after changing the log driver silently changes nothing, which is exactly the shape of failure that gets diagnosed as “the log driver is broken” three weeks later.

What the daemon actually does with SIGHUP

dockerd installs a signal handler at startup that, on SIGHUP, re-parses the config file path it was given and walks a hard-coded list of reloadable fields, calling a per-field apply function for each. Anything not on that list is parsed, compared, and discarded.

The daemon does not tell you it discarded anything. There is no warning in the journal for “you changed a key I cannot reload”. The only signal is that the behaviour did not change — which is why the verification step below reads the value back out of docker info rather than trusting the exit status of systemctl reload.

Two more things worth knowing about the reload path:

Reload happens in the running daemon. It does not touch containerd, does not touch running shims, and does not disturb a single container. A SIGHUP is the safest change you can make to a Docker host.
A reload with a syntactically broken file logs a parse error and keeps the old configuration. The daemon stays up. That is the good case. The dangerous case is the same broken file sitting on disk when the host reboots three months later, at which point the daemon will not start and nobody connects the two events.

The edit that only breaks on the next reboot

The sequence that produces a 03:00 page months after the change:

Somebody adds a trailing comma or a duplicated key to daemon.json.
They run systemctl reload docker. The daemon logs a parse error, keeps its running configuration, and stays up. Nobody looks at the journal.
docker ps works. docker info works. The host is declared healthy.
Eleven weeks later the host reboots for a kernel update.
dockerd reads the same broken file at cold start and exits. Every container on the host is down, and live-restore does not help, because live-restore preserves containers across a daemon restart — not across a host reboot, which kills the shims and the container processes anyway.

The first diagnosis is always the kernel upgrade, because that is what changed today. It is not. journalctl -u docker -b shows the JSON error in the first few lines, and git log on /etc/docker/daemon.json shows an edit from eleven weeks ago.

The defence is one command in step 2, and it is in the next section.

Validating before you commit

dockerd --validate parses the file and exits non-zero if it is invalid, without starting a daemon. It is safe to run on a host with a daemon already running.

Read-only / Safevalidate— Parse the config without starting a daemon. Non-zero exit means do not reload.

$ sudo dockerd --validate --config-file=/etc/docker/daemon.json; echo rc=$?

configuration OK
rc=0

Illustrative output

Read-only / Safevalidate (failing)— What a trailing comma looks like before it becomes an outage.

$ sudo dockerd --validate --config-file=/etc/docker/daemon.json; echo rc=$?

unable to configure the Docker daemon with file /etc/docker/daemon.json: \
invalid character '}' looking for beginning of object key string
rc=1

Illustrative output

A bare JSON syntax check catches less than --validate does — it will not catch a wrong type or an unknown key — but it needs no privileges and belongs in a pre-commit hook:

Read-only / Safesyntax only— Cheap syntax gate. Catches commas and braces, not semantics.

CONFIG=/etc/docker/daemon.json
python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$CONFIG" \
&& echo "JSON parses"

Verification that can fail

systemctl restart docker exiting 0 tells you systemd started a process. It does not tell you your key took effect. Read the value back:

Read-only / Safeverify— Assert the daemon's live view of the settings you changed.

$ docker info --format 'live-restore={{.LiveRestoreEnabled}} cgroup={{.CgroupDriver}} storage={{.Driver}} logging={{.LoggingDriver}}'

live-restore=true cgroup=systemd storage=overlay2 logging=json-file

Illustrative output

For keys that docker info does not surface, ask the daemon what it parsed by reading its own view of the file back through the API:

Read-only / Safeassert— A check that fails loudly instead of printing something for a human to squint at.

WANT=true
GOT=$(docker info --format '{{.LiveRestoreEnabled}}')
if [ "$GOT" != "$WANT" ]; then
  echo "live-restore is $GOT, expected $WANT" >&2
  exit 1
fi
echo "live-restore confirmed active"

Undoing a change

Because daemon.json can prevent the daemon from starting, the rollback path has to work when docker itself does not.

Keep /etc/docker/daemon.json in version control, or at minimum copy it to daemon.json.bak before every edit. cp is cheaper than a 40-minute outage.
On a daemon that will not start, read journalctl -u docker -b --no-pager | head -20. The parse error is in the first few lines and names the offending construct.
Restore the previous file and run sudo dockerd --validate --config-file=/etc/docker/daemon.json before you attempt another start.
Start the daemon with sudo systemctl start docker and confirm with docker info, not with systemctl is-active — systemd reports a daemon that started and is failing calls as active.
If the file itself is fine but the flag conflict above is the cause, inspect the effective unit with systemctl cat docker and look for a drop-in you did not write.

What happens if you bind metrics-addr to 0.0.0.0?

You publish an unauthenticated HTTP endpoint that describes the host: every container name, image name, and count of builds, plus daemon internals. There is no token, no TLS by default, and no per-endpoint access control — the documented example in the Docker docs binds 127.0.0.1 for exactly this reason.

The failure is not that somebody scrapes it. The failure is that container names in a lot of estates encode the customer, the environment, and the application version, so an open metrics port is a free inventory of what you run and which version of it. Bind loopback and have Prometheus scrape through a node exporter, an SSH tunnel, or a firewalled interface — and confirm it with ss -ltnp | grep 9323 after the restart, not with the config file.

Note also that metrics-addr is not reloadable. Getting this wrong and fixing it costs a daemon restart.

Common mistakes

Why this matters

Configuration mistakes that bite in production, in rough order of how often they show up:

No log rotation. Without log-opts.max-size, a single verbose container fills the disk, and a full /var/lib/docker breaks the daemon, not just the container. This is the most common Docker outage there is.
Reloading a key that does not reload. systemctl reload docker after a log-driver change is a no-op that looks like a success.
A cgroup driver that does not match the rest of the host. If systemd owns the cgroup tree and Docker writes it with cgroupfs, you get two managers, drifting limits, and resource controls that silently stop applying.
Turning on containerd-snapshotter without planning. Existing images become invisible — they are still on disk, under the other store — and the first symptom is every deploy on the host pulling from scratch at once.
Setting experimental: true to get one feature. It enables the whole experimental surface, and experimental features can change or disappear between patch releases.
Editing the file on a host and nowhere else. The next rebuild reverts it. daemon.json belongs in configuration management like any other host state.

Sanity workflow after every daemon.json change

Back up the current file: sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.
Edit, then validate with sudo dockerd --validate --config-file=/etc/docker/daemon.json and check the exit status.
Decide reload or restart by looking up every key you touched in the reload table above. When in doubt, restart.
If a restart is needed, confirm live-restore is already active first — that is itself a reloadable change you can make in advance.
Apply: sudo systemctl reload docker or sudo systemctl restart docker.
Verify the daemon believes the new value, with docker info --format on the specific field. Do not accept a zero exit status as proof.
Confirm containers are still running with docker ps, and that a workload actually serves traffic — not just that its state says running.
Tail journalctl -u docker -f for a few minutes to catch warnings the restart emitted.
Commit the change to version control with the ticket reference.

A production-shaped daemon.json

The reload boundary

Validating before you commit

Verification that can fail

Undoing a change

Common mistakes

Sanity workflow after every daemon.json change

Knowledge check