Systematic Diagnosis and Solution for Docker Service Startup Failure in Ubuntu 16.04

Problem Background and Diagnosis

When deploying Docker 1.10 on Ubuntu 16.04 systems, users frequently encounter service startup failures. The systemctl status docker.service command reveals a 'failed' service status with primary error messages pointing to the devicemapper storage driver: devicemapper: Can't set task name /dev/mapper/docker-8:6-2101297-pool. This error indicates that Docker encountered permission or configuration issues while attempting to manage device mapper storage pools.

Detailed Error Analysis

Running the sudo docker daemon -D command provides detailed debug output that offers deeper insight into the problem's root cause. The output shows multiple failures during devicemapper driver initialization:

ERRO[0000] devmapper: Unable to delete device: devicemapper: Can't set task name /dev/mapper/docker-8:6-2101297-pool 
WARN[0000] devmapper: Usage of loopback devices is strongly discouraged for production use.

The error message explicitly discourages loopback device usage in production environments, suggesting that storage driver configuration may require adjustment. Meanwhile, the kernel configuration check script check-config.sh output shows system support for multiple storage drivers including overlay and btrfs, providing alternative paths for solutions.

Root Cause: Masked systemd Unit Files

Through thorough investigation, the fundamental issue was identified as masked systemd unit files for Docker. In newer Docker versions and Ubuntu systems, /lib/systemd/system/docker.service and /lib/systemd/system/docker.socket files may be symbolically linked to /dev/null, preventing normal service startup. This can be verified with:

sudo file /lib/systemd/system/docker.service
sudo file /lib/systemd/system/docker.socket

If the output shows these files pointing to /dev/null, unmasking is required.

Solution Implementation

Step 1: Unmask systemd Services

First, unmask the Docker systemd services, which is the most direct and effective solution:

sudo systemctl unmask docker.service
sudo systemctl unmask docker.socket
sudo systemctl start docker.service
sudo systemctl status docker

These commands remove the symbolic links to /dev/null, restore normal service unit files, then start the Docker service and verify its status.

Step 2: Configure Alternative Storage Driver (Optional)

If problems persist after unmasking, or to avoid devicemapper driver issues, Docker can be configured to use the overlay storage driver. For Ubuntu systems using systemd (version 15.04 and above), create a systemd override configuration file:

1. Create configuration file /etc/systemd/system/docker.service.d/overlay.conf:

[Service]
ExecStart=
ExecStart=/usr/bin/docker daemon -H fd:// -s overlay

This configuration overrides the default ExecStart directive, specifying the overlay storage driver.

Storage Driver Selection Recommendations

Docker supports multiple storage drivers, each with appropriate use cases:

• devicemapper: Default driver, but poor performance with loop devices, not suitable for production
• overlay: Recommended for modern Linux kernels, good performance, supports union filesystems
• btrfs: Requires btrfs filesystem, supports snapshots and compression
• aufs: Default driver for older Ubuntu versions, gradually being replaced by overlay

Storage driver selection should consider kernel support, performance requirements, and feature needs. For Ubuntu 16.04, the overlay driver is typically a good choice, provided kernel configuration supports it (CONFIG_OVERLAY_FS enabled).

Kernel Configuration Verification

The Docker-provided check-config.sh script verifies whether the system kernel meets Docker runtime requirements. The script checks:

• Essential namespace and cgroup support
• Network driver modules (veth, bridge, macvlan, etc.)
• Storage driver support (devicemapper, overlay, btrfs, etc.)
• Optional features (user namespaces, seccomp, etc.)

Ensure all 'Generally Necessary' items show as 'enabled', which forms the foundation for Docker's normal operation.

Preventive Measures and Best Practices

1. Regular System Updates: Keep Ubuntu system and Docker versions updated to avoid known compatibility issues
2. Configuration Backups: Backup relevant files before modifying Docker or systemd configurations
3. Production Environment Configuration: Avoid using devicemapper loop device mode in production; configure dedicated storage devices
4. Log Monitoring: Regularly check journalctl -u docker.service output to identify potential issues early
5. Test Environment Validation: Verify configuration changes in test environments before production deployment

Conclusion

Docker service startup failures in Ubuntu 16.04 typically stem from masked systemd unit files or storage driver configuration issues. By unmasking systemd services, selecting appropriate storage drivers (such as overlay), and ensuring kernel configuration meets requirements, most startup problems can be resolved. The systematic diagnostic methods and solutions provided in this article, combined with Docker official documentation and community experience, offer practical guidance for stable Docker deployment in Linux environments. For more complex issues, consulting Docker official documentation and community forums is recommended to obtain the latest solutions and support.