From 56e5f132a365b914428c081a545cc2cca7fe6e2c Mon Sep 17 00:00:00 2001
From: Sonic Build Admin <sonicbld@microsoft.com>
Date: Sat, 14 Feb 2026 07:02:13 +0000
Subject: [PATCH] [docker] Fix Docker commands hanging before docker.service
 starts

#### Why I did it
Fix Docker socket activation broken since PR #2417 (January 2019). Docker commands executed before docker.service starts hang indefinitely because -H unix:// breaks systemd socket activation.

**Fixes #25383**

##### Work item tracking
- Microsoft ADO **(number only)**:

#### How I did it
Changed `-H unix://` to `-H fd://` in  `files/docker/docker.service.conf`. Added documentation comments explaining why this flag is required to prevent future regression.

#### How to verify it

<!--
If PR needs to be backported, then the PR must be tested against the base branch and the earliest backport release branch and provide tested image version on these two branches. For example, if the PR is requested for master, 202211 and 202012, then the requester needs to provide test results on master and 202012.
-->

Verified on VS image:
- docker.socket is active and triggers docker.service
- dockerd runs with -H fd:// flag
- Socket activation works correctly

#### Which release branch to backport (provide reason below if selected)

<!--
- Note we only backport fixes to a release branch, *not* features!
- Please also provide a reason for the backporting below.
- e.g.
- [x] 202006
-->

- [x] 202305
- [x] 202311
- [x] 202405
- [x] 202411
- [x] 202505
- [x] 202511

**Reason:** This is a bug fix that has existed since January 2019. All active release branches are affected and should receive this fix.

#### Tested branch (Please provide the tested image version)

<!--
- Please provide tested image version
- e.g.
- [x] 20201231.100
-->

- [x] master : `fix_docker-socket-activation-25383.0-b01504e6c` (sonic-vs.img.gz)

#### Description for the changelog

Fix Docker socket activation hang by using -H fd:// instead of -H unix:// in docker.service.conf

<!--
 Ensure to add label/tag for the feature raised. example - PR#2174 under sonic-utilities repo. where, Generic Config and Update feature has been labelled as GCU.
-->

#### Link to config_db schema for YANG module changes
<!--
Provide a link to config_db schema for the table for which YANG model
is defined
Link should point to correct section on https://github.com/Azure/sonic-buildimage/blob/master/src/sonic-yang-models/doc/Configuration.md
-->
N/A

#### A picture of a cute animal (not mandatory but encouraged)

![michael-sum-LEpfefQf4rU-unsplash](https://github.com/user-attachments/assets/a4f71f80-b11c-49f4-a562-26d63b89fdbe)
---
 files/docker/docker.service.conf | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/files/docker/docker.service.conf b/files/docker/docker.service.conf
index 73d953ecfd..ea7f29f518 100644
--- a/files/docker/docker.service.conf
+++ b/files/docker/docker.service.conf
@@ -1,4 +1,14 @@
+# Docker daemon systemd service override configuration
+#
+# IMPORTANT: The -H fd:// flag is required for systemd socket activation.
+# This allows Docker clients to connect to /var/run/docker.sock before
+# docker.service starts - systemd listens on the socket and passes it to
+# dockerd when the service starts. If changed to -H unix://, dockerd creates
+# a new socket instead of inheriting the one systemd was listening on, causing
+# early Docker commands to hang indefinitely.
+# See: https://github.com/sonic-net/sonic-buildimage/issues/25383
+
 [Service]
 Environment=GODEBUG=netdns=cgo
 ExecStart=
-ExecStart=/usr/bin/dockerd -H unix:// --storage-driver=overlay2 --bip=240.127.1.1/24  --iptables=false --ipv6=true --fixed-cidr-v6=fd00::/80
+ExecStart=/usr/bin/dockerd -H fd:// --storage-driver=overlay2 --bip=240.127.1.1/24  --iptables=false --ipv6=true --fixed-cidr-v6=fd00::/80