Docker daemon.json Configuration File: Default Location, Creation, and Conflict Resolution

Overview of Docker daemon.json Configuration File

In the Docker ecosystem, the daemon.json file serves as the primary configuration file for the Docker daemon (dockerd). According to official documentation, the default configuration path on Linux systems is /etc/docker/daemon.json. However, many users discover that this file does not exist after a fresh Docker installation, raising questions about the default configuration mechanism.

Reason for Absence and Creation Method

The /etc/docker/daemon.json file is not automatically generated during initial Docker installation. This is a deliberate design choice, as the Docker daemon can operate with default parameters without a configuration file. Users must manually create this file based on specific requirements. The creation process is straightforward:

sudo touch /etc/docker/daemon.json
sudo chmod 644 /etc/docker/daemon.json

After creation, users can add JSON-formatted configuration parameters to the file. For example, setting log driver and storage driver:

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

Since /etc/docker/daemon.json is the default path, there's no need to explicitly specify the configuration file when starting the daemon. However, for system maintainability, it's recommended to include the --config-file parameter explicitly in startup commands:

dockerd --config-file /etc/docker/daemon.json

Conflict Resolution Between Configuration and Command-Line Arguments

When configuring daemon.json, special attention must be paid to avoid conflicts with command-line arguments. The Docker daemon performs strict consistency checks during startup: if the same configuration item appears in both the configuration file and command-line arguments, the daemon will fail to start regardless of whether the values match. For instance, if "log-driver": "syslog" is set in daemon.json while --log-driver=json-file is used in the command line, a conflict will occur.

To prevent such issues, a unified configuration management strategy is recommended:

1. Prioritize daemon.json for persistent configuration
2. Use command-line arguments only for temporary debugging
3. Regularly review parameter settings in startup scripts

Practical Application Scenarios and Best Practices

In production environments, the daemon.json file is commonly used to configure core parameters such as network settings, storage drivers, and image registries. Below is a comprehensive configuration example:

{
  "debug": true,
  "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"],
  "registry-mirrors": ["https://registry.docker-cn.com"],
  "insecure-registries": ["192.168.1.100:5000"],
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

After configuration, restart the Docker service to apply changes:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify configuration effectiveness:

sudo docker info | grep -A5 -B5 "Logging Driver"

Troubleshooting and Common Issues

When the Docker daemon fails to start, first check the syntax correctness of daemon.json. JSON format errors are common causes; use the jq tool for validation:

jq . /etc/docker/daemon.json

If parsing errors are returned, correct the JSON format. Another common issue is improper permission settings; ensure correct file ownership:

sudo chown root:root /etc/docker/daemon.json
sudo chmod 644 /etc/docker/daemon.json

Detailed error information can be obtained through system logs:

sudo journalctl -u docker.service --no-pager -n 50

These methods effectively help diagnose and resolve configuration-related problems.