Corriger l’erreur « permission denied » lors de la connexion au daemon Docker (débutant)

L’erreur suivante (ou une variante très proche) est l’un des premiers obstacles quand on débute avec Docker sous Linux :

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: 
Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json": dial unix /var/run/docker.sock: connect: permission denied

Elle signifie simplement : votre utilisateur n’a pas le droit d’accéder au socket Unix du daemon Docker (/var/run/docker.sock). Ce tutoriel explique en profondeur pourquoi cela arrive, comment diagnostiquer correctement, et plusieurs façons de corriger (avec les implications de sécurité).

1) Comprendre ce qui se passe : daemon, client, socket et permissions

1.1 Docker “client” vs Docker “daemon”

Quand vous tapez :

docker ps

Vous lancez le client Docker (la commande docker). Ce client ne fait pas tout le travail lui-même : il envoie une requête au daemon Docker (le service en arrière-plan, souvent dockerd) qui gère :

• les images
• les conteneurs
• les réseaux
• les volumes
• l’accès au runtime (containerd, runc…)

1.2 Comment le client parle au daemon

Sous Linux, la communication se fait très souvent via un socket Unix :

• Chemin typique : /var/run/docker.sock
• URL “interne” : unix:///var/run/docker.sock

Un socket Unix est un fichier spécial qui permet à des programmes de communiquer localement. Comme tout fichier, il a un propriétaire, un groupe, et des droits (lecture/écriture).

1.3 Pourquoi “permission denied”

Le daemon Docker tourne généralement en root (superutilisateur). Le socket /var/run/docker.sock est donc souvent :

• propriétaire : root
• groupe : docker
• permissions : srw-rw---- (lecture/écriture pour root et groupe docker, rien pour les autres)

Donc si votre utilisateur n’est pas root et n’appartient pas au groupe docker, la tentative d’accès au socket échoue → permission denied.

2) Vérifier l’erreur et collecter des indices (diagnostic)

2.1 Reproduire l’erreur

Essayez :

docker version

ou :

docker ps

Si l’erreur est un problème de permissions, vous verrez une mention de /var/run/docker.sock.

2.2 Vérifier que Docker est installé et que le service tourne

Sur une distribution avec systemd (Ubuntu, Debian, Fedora, etc.) :

systemctl status docker

Vous devriez voir active (running).

Si ce n’est pas le cas, démarrez :

sudo systemctl start docker

Et pour démarrer au boot :

sudo systemctl enable docker

Important : si le service n’est pas lancé, vous aurez plutôt une erreur du type “Cannot connect to the Docker daemon… Is the docker daemon running?” (pas forcément “permission denied”). Mais il est utile de valider ce point.

2.3 Inspecter les permissions du socket

Affichez les droits :

ls -l /var/run/docker.sock

Exemple courant :

srw-rw---- 1 root docker 0 Apr 15 10:20 /var/run/docker.sock

Interprétation :

• s : c’est un socket
• rw- pour root : root peut lire/écrire
• rw- pour le groupe docker : les membres du groupe peuvent lire/écrire
• --- pour “others” : les autres utilisateurs ne peuvent rien faire

2.4 Vérifier vos groupes

Affichez les groupes de votre utilisateur :

groups

ou :

id -nG

Si vous ne voyez pas docker, vous avez trouvé la cause la plus fréquente.

3) Solution recommandée (débutant) : ajouter votre utilisateur au groupe docker

3.1 Pourquoi c’est la solution “classique”

Docker crée souvent un groupe système docker. En ajoutant votre utilisateur à ce groupe, vous obtenez le droit d’accéder au socket sans sudo.

3.2 Étapes détaillées

Étape A — Vérifier si le groupe docker existe

getent group docker

• Si une ligne s’affiche, le groupe existe.
• Sinon, vous pouvez le créer :

sudo groupadd docker

Étape B — Ajouter votre utilisateur au groupe

Remplacez $USER si nécessaire :

sudo usermod -aG docker $USER

• -aG signifie “append” (ajouter) à la liste de groupes secondaires, sans écraser les autres.

Étape C — Recharger votre session (très important)

Votre session actuelle ne “voit” pas toujours le nouveau groupe immédiatement.

Options :

1. Se déconnecter / reconnecter (méthode simple et fiable)

2. Ou lancer une nouvelle session de groupe :

newgrp docker

3. Ou redémarrer la machine (radical mais efficace)

Étape D — Vérifier que vous êtes bien dans le groupe

groups

Vous devez voir docker.

Étape E — Tester

docker ps

ou :

docker run --rm hello-world

Si tout est correct, Docker téléchargera l’image (si nécessaire) et exécutera un conteneur de test.

4) Comprendre l’impact sécurité : le groupe docker ≈ accès root

C’est crucial : appartenir au groupe docker donne un pouvoir très élevé.

Pourquoi ? Parce que si vous pouvez parler au daemon Docker, vous pouvez généralement :

• monter des répertoires sensibles du système hôte dans un conteneur
• modifier des fichiers système
• accéder à des secrets
• potentiellement obtenir un shell root sur l’hôte

Exemple (illustratif) : un utilisateur ayant accès à Docker peut lancer un conteneur qui monte / (racine) de l’hôte :

docker run --rm -it -v /:/host alpine chroot /host /bin/sh

Selon la configuration, cela peut permettre de manipuler l’hôte comme root. Conclusion : n’ajoutez au groupe docker que des utilisateurs de confiance, idéalement sur une machine de dev.

5) Solution alternative : utiliser sudo (simple, mais moins confortable)

Si vous ne voulez pas ajouter votre utilisateur au groupe docker, vous pouvez exécuter Docker avec sudo :

sudo docker ps

Test :

sudo docker run --rm hello-world

Avantages

• Pas besoin de modifier les groupes.
• Contrôle plus explicite (vous tapez votre mot de passe, logs sudo, etc.).

Inconvénients

• Moins pratique (répéter sudo).
• Peut créer des fichiers root dans votre $HOME si vous manipulez des volumes/montages de manière maladroite.
• Certains outils (docker-compose, scripts, IDE) s’attendent à un accès sans sudo.

6) Vérifier que le problème n’est pas ailleurs (cas fréquents)

6.1 Le service Docker ne tourne pas

Symptômes : message “Is the docker daemon running?”

Vérifiez :

systemctl status docker
journalctl -u docker --no-pager -n 200

Démarrez :

sudo systemctl start docker

6.2 Le socket a des permissions inattendues

Si ls -l /var/run/docker.sock montre un groupe différent de docker (ex. root root), c’est possible selon l’installation.

Vous pouvez regarder qui “possède” le socket et quel groupe est utilisé :

stat /var/run/docker.sock

Si le groupe n’est pas docker, l’ajout au groupe docker ne suffira pas.

Dans ce cas, vérifiez la configuration systemd du service Docker (souvent inutile pour débutant, mais utile si installation custom) :

systemctl cat docker

6.3 Vous êtes bien dans le groupe, mais l’erreur persiste

Causes possibles :

• Vous n’avez pas relancé la session (le plus fréquent)
• Le groupe n’est pas pris en compte dans le shell courant
• Vous êtes connecté via un service qui ne recharge pas les groupes (certaines sessions SSH persistantes, tmux/screen anciens, etc.)

Solutions :

• Déconnectez-vous / reconnectez-vous
• Ou :

newgrp docker

Puis retestez :

docker ps

6.4 Docker Desktop / contexte Docker différent

Sur certaines machines, vous pouvez avoir plusieurs contextes Docker. Vérifiez :

docker context ls

Et le contexte actif :

docker context show

Si vous utilisez un contexte distant, l’erreur peut être différente (TLS, permissions réseau), mais si le message mentionne /var/run/docker.sock, on est bien sur le socket local.

7) Cas des distributions et environnements spécifiques

7.1 Ubuntu / Debian (installation via dépôt officiel Docker)

Après installation, le groupe docker est souvent créé automatiquement. La procédure “usermod -aG docker” est la plus courante.

Vérification :

dpkg -l | grep -E 'docker|containerd'

7.2 Fedora / RHEL / CentOS

Même principe, mais SELinux peut ajouter des complications (souvent sur les volumes). Pour l’erreur “permission denied” sur le socket, c’est généralement identique : groupe docker et relog.

Vérifiez :

rpm -qa | grep -E 'docker|containerd'

7.3 WSL2 (Windows Subsystem for Linux)

Deux scénarios :

• Vous utilisez Docker Desktop côté Windows et la distro WSL se connecte à un daemon “intégré”.
• Ou vous installez Docker directement dans WSL (moins recommandé).

Si l’erreur mentionne /var/run/docker.sock, vérifiez que le socket existe :

ls -l /var/run/docker.sock

Dans certains setups Docker Desktop, le socket peut être ailleurs ou géré via intégration. Il faut alors vérifier la doc Docker Desktop + WSL. Mais si vous avez bien un socket local, les permissions restent pertinentes.

7.4 Machines multi-utilisateurs (serveur partagé)

Sur un serveur partagé, ajouter des utilisateurs au groupe docker revient à leur donner un contrôle quasi-root. Dans ce contexte, on préfère souvent :

• sudo avec politiques strictes
• ou des solutions rootless (voir section suivante)
• ou un orchestrateur/plateforme qui isole mieux les droits

8) Option avancée (mais utile) : Docker “rootless” pour éviter le socket root

Docker propose un mode rootless : le daemon tourne sans privilèges root, et le socket est dans votre $XDG_RUNTIME_DIR (souvent sous /run/user/<uid>/docker.sock).

8.1 Pourquoi rootless peut éviter ce problème

Si le daemon appartient à votre utilisateur, vous n’avez pas besoin d’accéder à /var/run/docker.sock (socket root). Vous accédez à un socket qui vous appartient.

8.2 Vérifier si vous êtes en rootless

Essayez :

docker info | grep -i rootless

Ou regardez la variable d’environnement :

echo "$DOCKER_HOST"

En rootless, on voit parfois :

unix:///run/user/1000/docker.sock

8.3 Installer/configurer rootless (aperçu)

Cela dépend de la distribution et du paquet Docker. Souvent, on utilise :

dockerd-rootless-setuptool.sh install

Puis on exporte DOCKER_HOST si nécessaire. Comme c’est un sujet large (réseau, ports <1024, cgroups), retenez surtout : rootless est une alternative plus “sécurité-friendly”, mais peut être plus complexe pour un débutant.

9) Dépannage guidé : scénario pas à pas

Voici une séquence “type” qui résout 90% des cas sur Linux :

9.1 Confirmer l’erreur

docker ps

9.2 Confirmer que Docker tourne

systemctl status docker

Si inactif :

sudo systemctl start docker

9.3 Vérifier le socket

ls -l /var/run/docker.sock

Vous voulez typiquement voir root docker.

9.4 Vérifier votre appartenance au groupe docker

groups

Si docker absent :

sudo usermod -aG docker $USER

Puis déconnexion/reconnexion (ou newgrp docker).

9.5 Retester

docker run --rm hello-world

Si ça fonctionne, vous avez corrigé la cause principale.

10) Questions fréquentes (FAQ)

“Pourquoi Docker n’autorise pas tout le monde par défaut ?”

Parce que l’accès au daemon Docker permet des actions très puissantes sur la machine. Sans restriction, n’importe quel utilisateur local pourrait compromettre le système.

“J’ai ajouté mon utilisateur au groupe docker, mais ça ne marche toujours pas”

Dans la majorité des cas, c’est une session non rechargée. Faites :

newgrp docker

ou déconnectez-vous/reconnectez-vous. Vérifiez ensuite :

id

Vous devez voir docker dans la liste des groupes.

“Puis-je faire chmod 666 /var/run/docker.sock ?”

Techniquement oui, mais c’est fortement déconseillé : vous donneriez l’accès Docker à tous les utilisateurs locaux. De plus, le socket est souvent recréé au redémarrage du service, donc ce changement ne tient pas.

“Pourquoi le socket est dans /var/run ?”

/var/run est souvent un lien vers /run, un répertoire temporaire en RAM/FS temporaire, destiné aux fichiers runtime (PID, sockets). Le socket Docker est un fichier runtime typique.

“Docker fonctionne avec sudo, mais pas sans”

C’est cohérent : sudo exécute la commande en root, donc root a accès au socket. La question est ensuite : voulez-vous un accès sans sudo (groupe docker) ou garder sudo (contrôle plus strict) ?

11) Résumé des solutions (choisir la bonne)

Solution A — Ajouter l’utilisateur au groupe docker (la plus courante)

Commandes :

sudo usermod -aG docker $USER
# puis relog ou:
newgrp docker
docker ps

Idéal pour : poste de dev personnel.

Solution B — Utiliser sudo

Commandes :

sudo docker ps

Idéal pour : environnement sensible, serveur partagé, ou si vous voulez éviter le groupe docker.

Solution C — Rootless Docker (plus avancé)

Idéal pour : meilleure isolation des privilèges, mais configuration plus complexe.

12) Checklist finale (rapide)

1. Docker tourne ?

   systemctl status docker

2. Socket accessible par groupe docker ?

   ls -l /var/run/docker.sock

3. Votre utilisateur est dans le groupe docker ?

   groups

4. Session rechargée ?

   • relog, ou :

     newgrp docker

5. Test :

   docker run --rm hello-world

Si vous me dites votre distribution (Ubuntu/Debian/Fedora/Arch/WSL2), votre méthode d’installation (paquet distro, dépôt Docker officiel, Docker Desktop) et le résultat de :

ls -l /var/run/docker.sock
groups
systemctl status docker --no-pager

je peux vous indiquer la correction la plus adaptée à votre cas précis.