Permission denied while trying to connect to the Docker daemon socket

Soluzione Rapida

L’utente corrente non ha i privilegi necessari per accedere al socket Unix del demone Docker (/var/run/docker.sock). Per risolvere il problema senza usare sudo ogni volta, devi aggiungere il tuo utente al gruppo docker.

Soluzione Permanente (Consigliata per ambienti di sviluppo):

Esegui questi comandi nel terminale:

# 1. Aggiungi l'utente corrente al gruppo 'docker'
sudo usermod -aG docker $USER

# 2. Applica le modifiche al gruppo nella sessione corrente
newgrp docker

# 3. Verifica l'installazione
docker run hello-world

Nota: Se il comando docker run fallisce ancora, prova a disconnetterti e riconnetterti (logout/login) o riavviare il sistema.

Soluzione Temporanea (Non sicura):

Puoi cambiare i permessi del socket, ma questo espone il demone Docker a qualsiasi utente del sistema. Non farlo in produzione.

sudo chmod 666 /var/run/docker.sock

Perché accade questo errore

L’architettura di Docker è divisa in due parti principali:

  1. Docker Client (CLI): Lo strumento da riga di comando che usi (docker build, docker run).
  2. Docker Daemon (dockerd): Il processo in background che gestisce i container, le immagini e le reti.

Il client comunica con il demone tramite un Unix Socket situato in /var/run/docker.sock. Per impostazione predefinita, questo socket è di proprietà dell’utente root e del gruppo docker.

Se esegui un comando Docker come utente normale che non fa parte del gruppo docker, il kernel Linux blocca l’accesso al socket, generando l’errore “permission denied”.

Spiegazione Dettagliata

Quando il demone Docker si avvia, crea il socket /var/run/docker.sock con permessi restrittivi per garantire la sicurezza. Solo chi ha i permessi di scrittura su questo file può inviare istruzioni al demone.

L’errore completo si presenta spesso così:

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

Analisi dei Permessi

Puoi verificare i permessi attuali del socket con:

ls -l /var/run/docker.sock
# Output atteso: srw-rw---- 1 root docker 0 Feb 19 10:00 /var/run/docker.sock

Se il tuo utente non è in root né nel gruppo docker, l’accesso è negato.

Soluzione su Linux

Questa procedura funziona su Ubuntu, Debian, CentOS, Fedora e la maggior parte delle distribuzioni Linux.

1. Verifica e crea il gruppo

Assicurati che il gruppo docker esista. Di solito viene creato durante l’installazione.

# Controlla se il gruppo esiste
grep docker /etc/group

# Se non restituisce nulla, crealo:
sudo groupadd docker

2. Aggiungi l’utente al gruppo

Aggiungi il tuo utente ($USER) al gruppo docker.

sudo usermod -aG docker $USER

3. Attiva le modifiche

Le modifiche ai gruppi non sono immediate per la sessione corrente. Hai due opzioni:

4. Verifica finale

Controlla di appartenere al gruppo ed esegui un test.

# Verifica i gruppi dell'utente
id -nG

# Test
docker version

Fix on macOS

Su macOS, Docker Desktop utilizza una macchina virtuale Linux leggera. I permessi sono gestiti diversamente e l’utente macOS non interagisce direttamente con il socket Linux. Tuttavia, possono verificarsi problemi di configurazione.

1. Permessi Docker Desktop

  1. Apri Docker Desktop.
  2. Vai su Settings > Advanced.
  3. Verifica che “Allow the default Docker socket to be used” sia selezionato (richiede privilegi di amministratore durante l’installazione).

2. Problemi di ownership nella Home

A volte i file di configurazione nella tua home directory possono appartenere a root (se hai usato sudo per sbaglio).

sudo chown -R $USER ~/.docker

3. Contesti Docker

Se usi contesti multipli, assicurati di usare quello corretto:

docker context use default

Fix on Windows

WSL2 (Windows Subsystem for Linux)

Se usi Docker all’interno di una distribuzione WSL2 (es. Ubuntu), devi seguire la procedura Fix on Linux descritta sopra all’interno del terminale WSL.

  1. Apri il terminale Ubuntu.
  2. Esegui sudo usermod -aG docker $USER.
  3. Chiudi e riapri il terminale WSL.

PowerShell / CMD

Se ricevi “permission denied” su Windows nativo:

  1. Assicurati di essere nel gruppo locale docker-users.
    • Esegui lusrmgr.msc (Gestione utenti e gruppi locali).
    • Vai su Gruppi > docker-users.
    • Aggiungi il tuo utente Windows al gruppo.
  2. Riavvia il computer affinché le modifiche ai gruppi abbiano effetto.

Security Implications

Attenzione: Aggiungere un utente al gruppo docker ha serie implicazioni di sicurezza.

Il demone Docker gira come root. Un utente nel gruppo docker può avviare un container mappando l’intera directory radice / dell’host all’interno del container, ottenendo di fatto accesso root illimitato al sistema ospitante senza bisogno di password sudo.

Esempio di escalation privilegi:

docker run -v /:/host -it ubuntu chroot /host
# Ora sei root sul sistema host!

Raccomandazioni:

Alternative: Rootless Docker

Per mitigare i rischi di sicurezza, puoi utilizzare Rootless Docker. Questa modalità esegue il demone Docker e i container interamente come utente non privilegiato, senza permessi di root.

Installazione (Linux):

# Disabilita il docker di sistema se presente
sudo systemctl disable --now docker.service docker.socket

# Installa Rootless Docker
curl -fsSL https://get.docker.com/rootless | sh

Dopo l’installazione, il socket si troverà in /run/user/$UID/docker.sock e non avrai problemi di permessi.

CI/CD Environments

L’errore è molto comune nelle pipeline di CI/CD (Jenkins, GitLab CI, GitHub Actions).

Jenkins

L’utente jenkins deve essere aggiunto al gruppo docker sull’agente dove viene eseguito Docker.

sudo usermod -aG docker jenkins
sudo systemctl restart jenkins

GitLab CI

Se usi lo shell executor, l’utente gitlab-runner deve avere i permessi.

sudo usermod -aG docker gitlab-runner

Common Variations

FAQ

Q: È sicuro eseguire chmod 777 /var/run/docker.sock? A: No. Dare permessi 777 permette a chiunque sul sistema di controllare il demone Docker, avviare container malevoli e ottenere accesso root all’host. È una grave falla di sicurezza.

Q: Ho aggiunto l’utente al gruppo, ma continuo a ricevere l’errore. Perché? A: Probabilmente non hai ricaricato i gruppi. Esegui newgrp docker nel terminale corrente. Se usi un IDE (VS Code, IntelliJ), devi riavviarlo completamente o fare logout/login dal sistema operativo.

Q: Come rimuovo un utente dal gruppo docker? A: Usa il comando sudo gpasswd -d $USER docker. L’utente perderà l’accesso al socket dopo il prossimo login.

Q: Qual è la differenza tra usare sudo docker e aggiungere l’utente al gruppo? A: sudo docker esegue il client come root per ogni singolo comando. Aggiungere l’utente al gruppo permette al client di girare come utente normale, ma comunica con il demone (che è root) tramite il socket condiviso. Il livello di privilegio finale è simile (accesso root indiretto).

Q: Questo errore può apparire se Docker non è avviato? A: Sì, ma solitamente l’errore è diverso (“Is the docker daemon running?”). Tuttavia, se il socket esiste ma il demone è spento o in stato di errore, i permessi potrebbero non essere impostati correttamente.