}

Docker daemon.json Configuration: Complete Guide with Examples [2025]

6 min read

Introduction to Docker daemon.json

The daemon.json file is Docker's primary configuration file for the Docker daemon (dockerd). It allows you to configure various Docker settings without using command-line flags, making your Docker configuration persistent, portable, and version-controllable.

In this comprehensive guide, we'll cover everything you need to know about the Docker daemon.json configuration file, including its location, available options, common configurations, and best practices.

⚠️ WARNING: Never make changes to production Docker configurations without testing in a staging environment first. Incorrect configurations can prevent Docker from starting.

Where is daemon.json Located?

The daemon.json file location varies by operating system:

Operating System Location
Linux /etc/docker/daemon.json
Windows C:\ProgramData\docker\config\daemon.json
macOS (Docker Desktop) ~/.docker/daemon.json

Creating the daemon.json File

The file doesn't exist by default. Create it:

Linux:

sudo mkdir -p /etc/docker
sudo touch /etc/docker/daemon.json
sudo nano /etc/docker/daemon.json

Windows (PowerShell as Administrator):

New-Item -ItemType Directory -Path "C:\ProgramData\docker\config" -Force
New-Item -ItemType File -Path "C:\ProgramData\docker\config\daemon.json"

Basic daemon.json Structure

The daemon.json file uses JSON format. Here's a minimal example:

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Common Configuration Options

1. Logging Configuration

Control how Docker containers log output:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5",
    "compress": "true"
  }
}

Available log drivers: - json-file (default) - syslog - journald - gelf - fluentd - awslogs - splunk - none

2. Storage Driver Configuration

Configure the storage driver for container layers:

{
  "storage-driver": "overlay2",
  "storage-opts": [
    "overlay2.override_kernel_check=true"
  ]
}

Available storage drivers: - overlay2 (recommended for most Linux distributions) - fuse-overlayfs - btrfs - zfs - vfs

3. Registry Mirrors

Speed up image pulls by configuring registry mirrors:

{
  "registry-mirrors": [
    "https://mirror.gcr.io",
    "https://docker-mirror.example.com"
  ]
}

4. Insecure Registries

Allow Docker to connect to insecure (HTTP) registries:

{
  "insecure-registries": [
    "192.168.1.100:5000",
    "registry.local:5000"
  ]
}

5. DNS Configuration

Set custom DNS servers for containers:

{
  "dns": ["8.8.8.8", "8.8.4.4"],
  "dns-opts": ["ndots:1"],
  "dns-search": ["example.com"]
}

6. Network Configuration

Configure Docker networking options:

{
  "bip": "172.17.0.1/16",
  "fixed-cidr": "172.17.0.0/24",
  "default-address-pools": [
    {
      "base": "172.20.0.0/16",
      "size": 24
    }
  ],
  "ip-forward": true,
  "iptables": true
}

7. Resource Limits

Set default resource limits for containers:

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 65536
    }
  },
  "default-shm-size": "64M"
}

8. Security Options

Configure security-related settings:

{
  "userns-remap": "default",
  "live-restore": true,
  "userland-proxy": false,
  "no-new-privileges": true
}

9. Debug and Logging Level

Enable debug mode and set log level:

{
  "debug": true,
  "log-level": "info"
}

Log levels: debug, info, warn, error, fatal

10. TLS Configuration

Configure TLS for secure Docker daemon access:

{
  "tls": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem",
  "tlsverify": true,
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"]
}

Complete daemon.json Example

Here's a comprehensive example for production use:

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "5",
    "compress": "true"
  },
  "data-root": "/var/lib/docker",
  "exec-opts": ["native.cgroupdriver=systemd"],
  "registry-mirrors": [
    "https://mirror.gcr.io"
  ],
  "insecure-registries": [],
  "dns": ["8.8.8.8", "8.8.4.4"],
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 65536
    }
  },
  "live-restore": true,
  "userland-proxy": false,
  "log-level": "warn",
  "max-concurrent-downloads": 10,
  "max-concurrent-uploads": 10,
  "default-shm-size": "128M",
  "features": {
    "buildkit": true
  }
}

Applying Configuration Changes

After modifying daemon.json, you must restart Docker:

Method 1: Restart Docker Service

# Linux with systemd
sudo systemctl restart docker

# Check status
sudo systemctl status docker

Method 2: Reload Configuration (Partial)

Some options support hot reload using SIGHUP:

sudo kill -SIGHUP $(pidof dockerd)

Options that support reload without restart: - debug - log-level - cluster-store - cluster-advertise - labels - live-restore

Verifying Configuration

Check if your configuration was applied:

docker info

Or inspect specific settings:

docker info --format '{{.LoggingDriver}}'
docker info --format '{{.Driver}}'

Configuration for Specific Use Cases

Kubernetes Node Configuration

For nodes running Kubernetes:

{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}

Development Environment

Optimized for local development:

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "debug": false,
  "experimental": true,
  "features": {
    "buildkit": true
  },
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "20GB"
    }
  }
}

CI/CD Server Configuration

Optimized for build servers:

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "2"
  },
  "max-concurrent-downloads": 20,
  "max-concurrent-uploads": 20,
  "features": {
    "buildkit": true
  }
}

Air-Gapped Environment

For environments without internet access:

{
  "storage-driver": "overlay2",
  "insecure-registries": ["internal-registry.company.local:5000"],
  "registry-mirrors": ["http://internal-mirror.company.local:5000"]
}

Troubleshooting

Docker Won't Start After Configuration Change

Check the Docker daemon logs:

# Linux
sudo journalctl -u docker.service -n 50

# Or check syslog
sudo tail -f /var/log/syslog | grep docker

Validate JSON Syntax

Before applying, validate your JSON:

cat /etc/docker/daemon.json | python3 -m json.tool

Or use jq:

cat /etc/docker/daemon.json | jq .

Common Errors

Error: "unable to configure the Docker daemon with file" - Check JSON syntax - Ensure no trailing commas - Verify all values are correct types

Error: "conflict between --flag and daemon.json" - Don't use the same option in both command line and daemon.json - Remove conflicting flags from Docker service file

Reset to Default Configuration

If Docker won't start, temporarily remove the config:

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.backup
sudo systemctl start docker

Best Practices

  1. Version Control: Keep daemon.json in version control
  2. Environment Separation: Use different configurations for dev/staging/prod
  3. Documentation: Comment your configuration choices (in a separate file)
  4. Backup: Always backup before making changes
  5. Test First: Test configuration changes in non-production environments
  6. Monitor Logs: Enable appropriate logging for your environment
  7. Security: Use TLS for remote Docker daemon access

Quick Reference: All Options

Here's a reference of all commonly used options:

{
  "api-cors-header": "",
  "authorization-plugins": [],
  "bip": "",
  "bridge": "",
  "cgroup-parent": "",
  "containerd": "/run/containerd/containerd.sock",
  "data-root": "/var/lib/docker",
  "debug": false,
  "default-address-pools": [],
  "default-cgroupns-mode": "host",
  "default-gateway": "",
  "default-gateway-v6": "",
  "default-runtime": "runc",
  "default-shm-size": "64M",
  "default-ulimits": {},
  "dns": [],
  "dns-opts": [],
  "dns-search": [],
  "exec-opts": [],
  "experimental": false,
  "features": {},
  "fixed-cidr": "",
  "fixed-cidr-v6": "",
  "group": "docker",
  "hosts": [],
  "icc": true,
  "init": false,
  "insecure-registries": [],
  "ip": "0.0.0.0",
  "ip-forward": true,
  "ip-masq": true,
  "iptables": true,
  "ip6tables": false,
  "ipv6": false,
  "labels": [],
  "live-restore": true,
  "log-driver": "json-file",
  "log-level": "info",
  "log-opts": {},
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 5,
  "metrics-addr": "",
  "mtu": 0,
  "no-new-privileges": false,
  "oom-score-adjust": -500,
  "pidfile": "/var/run/docker.pid",
  "raw-logs": false,
  "registry-mirrors": [],
  "runtimes": {},
  "seccomp-profile": "",
  "selinux-enabled": false,
  "shutdown-timeout": 15,
  "storage-driver": "",
  "storage-opts": [],
  "tls": false,
  "tlscacert": "",
  "tlscert": "",
  "tlskey": "",
  "tlsverify": false,
  "userland-proxy": true,
  "userns-remap": ""
}

Summary

The Docker daemon.json file is a powerful configuration tool that allows you to:

  • Configure logging drivers and options
  • Set storage drivers and data locations
  • Configure registry mirrors and insecure registries
  • Set network options including DNS and IP ranges
  • Enable security features
  • Tune performance with concurrent download/upload limits

Remember to always test configuration changes in a non-production environment and validate your JSON syntax before applying changes.

Additional Resources