Docker-fout oplossen: ‘permission denied while trying to connect to the Docker daemon’

Deze tutorial helpt je de veelvoorkomende Docker-fout op te lossen:

permission denied while trying to connect to the Docker daemon

Je krijgt niet alleen “snelle fixes”, maar ook de onderliggende oorzaken, hoe je diagnose stelt, en welke oplossing het best past bij jouw situatie (Linux, WSL2, rootless Docker, CI, enz.). Alle voorbeelden gebruiken echte commando’s.

Inhoud

• 1. Wat betekent deze fout precies?
• 2. Snelle herkenning: hoe ziet de fout eruit?
• 3. Hoe Docker communiceert met de daemon
• 4. Stap-voor-stap diagnose
  • 4.1 Check of Docker draait
  • 4.2 Controleer welk socket-pad gebruikt wordt
  • 4.3 Inspecteer permissies van de Docker socket
  • 4.4 Controleer je groepslidmaatschap
  • 4.5 Check SELinux/AppArmor (optioneel)
• 5. Oplossing 1: gebruiker toevoegen aan de docker-groep (meest gebruikt)
• 6. Oplossing 2: tijdelijk via sudo (snelle workaround)
• 7. Oplossing 3: permissies van /var/run/docker.sock corrigeren (meestal niet aanbevolen)
• 8. Oplossing 4: Docker daemon starten/enable’n (systemd)
• 9. Oplossing 5: Rootless Docker (veilig alternatief zonder docker-groep)
• 10. Specifieke scenario’s
  • 10.1 Ubuntu/Debian
  • 10.2 Fedora/RHEL/CentOS
  • 10.3 Arch Linux
  • 10.4 WSL2 + Docker Desktop
  • 10.5 Remote Docker context / DOCKER_HOST
  • 10.6 CI/CD (GitLab CI, GitHub Actions runners)
• 11. Verificatie: testen dat het werkt
• 12. Veelgemaakte fouten en valkuilen
• 13. Samenvatting en aanbevolen aanpak

1. Wat betekent deze fout precies?

Docker bestaat grofweg uit twee delen:

• De Docker CLI: het docker-commando dat jij uitvoert in de terminal.
• De Docker daemon: het achtergrondproces (dockerd) dat containers bouwt, start, stopt, images beheert, netwerken aanmaakt, volumes mount, enz.

Wanneer jij docker ps of docker run uitvoert, praat de CLI met de daemon via een API. Op Linux gebeurt dat meestal via een Unix socket:

• Standaard: /var/run/docker.sock (vaak een symlink naar /run/docker.sock)

De fout permission denied betekent vrijwel altijd:

• De socket bestaat wel, maar jouw gebruiker mag hem niet openen (geen lees-/schrijfrechten).
• Of de daemon draait niet, en je probeert via een pad te praten waar je geen rechten op hebt (minder vaak).
• Of je gebruikt een andere socket/host (bijv. rootless socket of remote host), en daar kloppen de rechten of credentials niet.

2. Snelle herkenning: hoe ziet de fout eruit?

Typische output:

$ docker ps
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.45/containers/json": dial unix /var/run/docker.sock: connect: permission denied

Of bij docker build:

$ docker build -t test .
permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

3. Hoe Docker communiceert met de daemon

3.1 Unix socket: bestand met rechten

/var/run/docker.sock is een bestand (socket) met Unix-permissies zoals:

• owner (meestal root)
• group (meestal docker)
• mode (bijv. srw-rw----)

Voorbeeld:

$ ls -l /var/run/docker.sock
srw-rw---- 1 root docker 0 Apr 15 10:12 /var/run/docker.sock

Interpretatie:

• root is eigenaar: mag lezen/schrijven
• groep docker mag lezen/schrijven
• “others” hebben geen rechten

Dus: als jij niet root bent en niet in de docker-groep zit, krijg je “permission denied”.

3.2 Waarom is dit gevoelig?

Toegang tot de Docker socket is in de praktijk root-toegang. Wie de socket kan gebruiken, kan:

• containers starten met -v /:/host en zo het host-filesysteem lezen/schrijven
• privileged containers starten
• kernel-capabilities misbruiken

Daarom is “gebruiker toevoegen aan docker-groep” functioneel handig, maar security-wise belangrijk om bewust te doen.

4. Stap-voor-stap diagnose

Voer onderstaande checks uit om exact te zien waar het misgaat.

4.1 Check of Docker draait

Op systemen met systemd:

sudo systemctl status docker

Start Docker indien nodig:

sudo systemctl start docker

En zet hem aan bij boot:

sudo systemctl enable docker

Zonder systemd (of in containers):

ps aux | grep dockerd

Als Docker niet draait, krijg je vaak een andere fout (zoals “Cannot connect to the Docker daemon”), maar permissies kunnen alsnog meespelen.

4.2 Controleer welk socket-pad gebruikt wordt

Docker CLI kan via environment variables of contexts een andere host gebruiken.

Check:

echo "$DOCKER_HOST"
docker context ls
docker context show

Als DOCKER_HOST leeg is en context “default” actief is, dan is het meestal unix:///var/run/docker.sock.

Toon de effectieve host:

docker info 2>/dev/null | sed -n '1,30p'

Als docker info al faalt door permissies, gebruik dan:

docker version

Die geeft ook vaak aan welke endpoint gebruikt wordt (maar kan eveneens falen).

4.3 Inspecteer permissies van de Docker socket

ls -l /var/run/docker.sock

Als dat pad niet bestaat, check:

ls -l /run/docker.sock

Je kunt ook zoeken:

sudo find /run -maxdepth 2 -type s -name "docker.sock" -ls 2>/dev/null

4.4 Controleer je groepslidmaatschap

id
groups

Zoek naar docker in de output.

Bestaat de docker-groep?

getent group docker

4.5 Check SELinux/AppArmor (optioneel)

Op Fedora/RHEL met SELinux:

getenforce

Op Ubuntu met AppArmor:

sudo aa-status

Meestal is SELinux/AppArmor niet de directe oorzaak van socket permission denied (dat is doorgaans pure Unix-permissie), maar bij afwijkende policies kan het meespelen.

5. Oplossing 1: gebruiker toevoegen aan de docker-groep (meest gebruikt)

Dit is de standaardoplossing op veel Linux-distributies.

5.1 Maak de docker-groep aan (als die nog niet bestaat)

sudo groupadd docker

Als de groep al bestaat, krijg je een melding; dat is prima.

5.2 Voeg je gebruiker toe aan de groep

Vervang $USER door je gebruikersnaam (meestal automatisch goed):

sudo usermod -aG docker $USER

Belangrijk:

• -aG betekent “append to groups”; zonder -a overschrijf je groepslidmaatschappen (gevaarlijk).

5.3 Log uit en weer in (of herstart je sessie)

Groepslidmaatschap wordt meestal pas actief bij een nieuwe login shell.

Opties:

1. Uitloggen en opnieuw inloggen (meest betrouwbaar)

2. Of een nieuwe shell met groepsrechten:

newgrp docker

Let op: newgrp kan je huidige shell-context wijzigen; vaak is uit/inloggen het schoonst.

5.4 Test

docker ps
docker run --rm hello-world

Als dit werkt, is de permissie-fout opgelost.

5.5 Security-opmerking

Iedere gebruiker in de docker-groep kan effectief root-achtige acties uitvoeren via Docker. Voeg dus alleen vertrouwde accounts toe, en liever niet op multi-user systemen zonder extra maatregelen.

6. Oplossing 2: tijdelijk via sudo (snelle workaround)

Als je snel verder wilt, kun je Docker-commando’s als root draaien:

sudo docker ps
sudo docker run --rm hello-world

Voordelen:

• Geen groepswijzigingen nodig
• Duidelijk dat je root gebruikt

Nadelen:

• Onhandig (steeds sudo)
• Bestanden die Docker aanmaakt (bijv. in bind mounts) kunnen root-owned worden
• Scripts/CI kunnen complexer worden

Je kunt eventueel een alias gebruiken (alleen voor jezelf):

alias docker='sudo docker'

Maar wees hier voorzichtig mee, vooral in scripts.

7. Oplossing 3: permissies van /var/run/docker.sock corrigeren (meestal niet aanbevolen)

Soms zie je adviezen als:

sudo chmod 666 /var/run/docker.sock

Dit maakt de socket wereld-schrijfbaar. Dat is bijna altijd een slechte security-keuze, omdat iedere lokale gebruiker dan Docker kan misbruiken.

7.1 Beter: check waarom de socket “verkeerd” staat

Normaal is:

• owner: root
• group: docker
• mode: 660

Je kunt herstellen met:

sudo chown root:docker /var/run/docker.sock
sudo chmod 660 /var/run/docker.sock

Maar let op:

• Docker (of je init-systeem) kan dit bij herstart weer overschrijven.
• Als jouw distro Docker anders configureert (bijv. rootless), is dit niet de juiste aanpak.

7.2 Structurele oplossing: systemd override (geavanceerd)

Je kunt de socket-permissies via systemd beheren (afhankelijk van hoe Docker is geïnstalleerd). Op veel systemen is er een docker.socket unit, maar vaak draait Docker zonder aparte socket unit.

Check:

systemctl list-units --type=socket | grep -i docker

Als er een docker.socket bestaat, kun je een override maken:

sudo systemctl edit docker.socket

En dan bijvoorbeeld SocketMode=0660 en SocketGroup=docker instellen. Dit verschilt per distro; controleer altijd de bestaande unit:

systemctl cat docker.socket

8. Oplossing 4: Docker daemon starten/enable’n (systemd)

Soms lijkt het op een permissieprobleem, maar is Docker simpelweg niet actief of is de socket niet aanwezig/juist.

8.1 Installatie-check (Debian/Ubuntu voorbeeld)

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

8.2 Service status

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

8.3 Start en enable

sudo systemctl start docker
sudo systemctl enable docker

8.4 Controleer containerd

Docker gebruikt doorgaans containerd. Als Docker niet start, kan containerd issues hebben:

sudo systemctl status containerd
sudo journalctl -u containerd --no-pager -n 200

9. Oplossing 5: Rootless Docker (veilig alternatief zonder docker-groep)

Als je Docker wilt gebruiken zonder root en zonder de docker-groep (die quasi-root is), kun je rootless mode gebruiken.

9.1 Wat is rootless?

• De daemon draait als jouw user
• De socket staat in jouw home directory (bijv. unix:///run/user/1000/docker.sock)
• Minder privileges: veiliger, maar met beperkingen (netwerk, low ports, sommige storage drivers)

9.2 Installatie (algemeen)

Op veel systemen kun je rootless setup doen met:

dockerd-rootless-setuptool.sh install

Als dat script niet bestaat, mis je mogelijk het pakket docker-ce-rootless-extras (naam verschilt per distro).

Voor Debian/Ubuntu (indicatief):

sudo apt-get update
sudo apt-get install -y docker-ce-rootless-extras uidmap

Daarna:

dockerd-rootless-setuptool.sh install

9.3 Environment instellen

Vaak krijg je instructies om DOCKER_HOST te zetten, bijvoorbeeld:

export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock

Test:

docker ps
docker run --rm hello-world

9.4 Wanneer rootless kiezen?

Kies rootless als:

• je op een gedeelde server werkt
• je security-eisen strikt zijn
• je geen users quasi-root wilt geven

Kies “normale” Docker (root daemon + docker-groep) als:

• je maximale compatibiliteit wilt
• je veel met netwerk/volumes/system integratie doet
• je omgeving single-user is en je de risico’s accepteert

10. Specifieke scenario’s

10.1 Ubuntu/Debian

Meest voorkomende fix:

sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world

Docker service:

sudo systemctl enable --now docker

10.2 Fedora/RHEL/CentOS

SELinux staat vaak “Enforcing”. Meestal is dat oké, maar check eerst socket-permissies:

ls -l /var/run/docker.sock
id

Als je Podman gebruikt in plaats van Docker, kan docker een wrapper zijn of helemaal niet draaien. Controleer:

docker --version
podman --version

Als je echt Docker gebruikt:

sudo systemctl enable --now docker
sudo usermod -aG docker $USER

10.3 Arch Linux

Docker daemon moet expliciet aan:

sudo systemctl enable --now docker

Groep:

sudo usermod -aG docker $USER

Herlogin of:

newgrp docker

10.4 WSL2 + Docker Desktop

In WSL2 is de situatie anders:

• Docker daemon draait vaak in Docker Desktop (Windows)
• WSL distro praat via integratie naar die daemon

Diagnose:

docker context ls
docker context show
echo "$DOCKER_HOST"

Veelvoorkomende oorzaken:

• Docker Desktop staat uit
• WSL integration staat uit voor jouw distro
• Je gebruikt per ongeluk een Linux Docker install binnen WSL die conflicteert

Aanpak:

1. Start Docker Desktop op Windows
2. Ga naar Settings → Resources → WSL Integration en zet integratie aan voor jouw distro
3. In WSL: test

docker run --rm hello-world
docker ps

Als je zowel docker.io in WSL hebt geïnstalleerd als Docker Desktop gebruikt, kan dat verwarring geven. Check waar docker vandaan komt:

which docker
docker version

10.5 Remote Docker context / DOCKER_HOST

Soms is de fout niet lokaal, maar komt hij doordat je naar een remote endpoint wijst dat je niet mag gebruiken.

Check:

docker context show
docker context inspect "$(docker context show)"

Als DOCKER_HOST gezet is:

echo "$DOCKER_HOST"

Voorbeeld: je hebt ooit gedaan:

export DOCKER_HOST=tcp://127.0.0.1:2375

Dan praat Docker niet met de Unix socket maar met een TCP endpoint. Dat kan falen met permissions/auth issues.

Reset naar default:

unset DOCKER_HOST
docker context use default

Test opnieuw:

docker ps

10.6 CI/CD (GitLab CI, GitHub Actions runners)

In CI kom je de fout tegen wanneer:

• je runner user geen toegang heeft tot de Docker socket
• je Docker-in-Docker (DinD) verkeerd is opgezet
• je probeert /var/run/docker.sock te mounten maar permissies kloppen niet

10.6.1 Runner met host Docker socket

Als je in een job /var/run/docker.sock mount:

• De user in de container moet rechten hebben op die socket.
• Vaak draait de container als root; dan werkt het, maar security is zwak.
• Als je als non-root draait, moet je GID matchen.

Check op host:

stat -c '%g %G %a' /var/run/docker.sock

Bijv. GID is 998 (groep docker). In je job/container moet je user in die groep zitten of je moet group-add doen.

Voorbeeld (lokaal):

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  alpine:3.20 sh

In de container:

apk add --no-cache docker-cli
docker ps

10.6.2 Docker-in-Docker (DinD)

Bij DinD praat je vaak met docker:2375 (zonder TLS) of docker:2376 (met TLS). Als je per ongeluk naar de host socket praat, krijg je permission issues.

Check in job:

echo "$DOCKER_HOST"

11. Verificatie: testen dat het werkt

Na je fix wil je zeker weten dat:

1. De daemon bereikbaar is
2. Je echt zonder sudo kunt werken (als dat je doel was)
3. Basisfuncties werken (pull, run, build)

11.1 Basis

docker version
docker info
docker ps

11.2 Hello-world

docker run --rm hello-world

11.3 Build-test

Maak een tijdelijke map:

mkdir -p /tmp/docker-perm-test
cd /tmp/docker-perm-test

Maak een Dockerfile:

cat > Dockerfile <<'EOF'
FROM alpine:3.20
RUN echo "Docker build werkt"
CMD ["sh", "-c", "echo container draait; id; ls -la"]
EOF

Build en run:

docker build -t perm-test:latest .
docker run --rm perm-test:latest

12. Veelgemaakte fouten en valkuilen

12.1 “Ik heb mezelf toegevoegd aan de docker-groep, maar het werkt nog niet”

Meest voorkomende oorzaak: je sessie heeft de nieuwe groepen nog niet.

Oplossing:

• log uit/in
• of:

newgrp docker

Controleer:

id

Je moet docker in de groepen zien.

12.2 “Ik heb chmod 777 gedaan en nu werkt het, klaar!”

Functioneel werkt het, maar je hebt een groot security-gat gemaakt. Zet het terug:

sudo chown root:docker /var/run/docker.sock
sudo chmod 660 /var/run/docker.sock

En los het correct op via groep of rootless.

12.3 “Docker draait, maar socket bestaat niet”

Check of Docker wel op de standaard manier luistert. In /etc/docker/daemon.json kan een custom host staan.

Bekijk config:

sudo cat /etc/docker/daemon.json

En check de service parameters:

systemctl cat docker | sed -n '1,200p'

Zoek naar -H opties (hosts).

12.4 “Ik gebruik Podman, maar ik typ docker”

Op sommige systemen is docker een alias/wrapper naar Podman. Dan is de foutmelding anders, maar kan lijken op Docker-problemen. Check:

readlink -f "$(which docker)"
docker --version

13. Samenvatting en aanbevolen aanpak

Aanbevolen volgorde

1. Check of Docker daemon draait

   sudo systemctl status docker

2. Check socket-permissies

   ls -l /var/run/docker.sock

3. Voeg je user toe aan de docker-groep (meest praktisch)

   sudo usermod -aG docker $USER
   # log uit/in of:
   newgrp docker

4. Test

   docker run --rm hello-world

Security-keuze

• Wil je maximale compatibiliteit en accepteer je dat docker-groep quasi-root is?
  → Gebruik docker-groep.

• Wil je betere isolatie zonder root?
  → Overweeg rootless Docker.

Als je wilt, kun je de exacte foutmelding en de output van deze commando’s plakken, dan kan ik gericht zeggen welke oorzaak bij jou speelt:

id
ls -l /var/run/docker.sock
systemctl status docker --no-pager
echo "$DOCKER_HOST"
docker context show
docker context ls