SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

PUID e PGID in Docker Compose: cosa fanno davvero

PUID e PGID non sono impostazioni Docker: sono una convenzione degli entrypoint linuxserver.io. Scopri perché i file finiscono come 911:911 e come correggerli.

Cosa sono realmente PUID e PGID

PUID e PGID sono due variabili d'ambiente che determinate immagini container leggono all'avvio. Docker non le legge direttamente. Sono una convenzione usata dalle immagini linuxserver.io e da alcune altre immagini. Un'immagine che non è stata progettata per leggerle le ignora senza segnalazioni.

All'interno di un'immagine linuxserver.io esiste un utente chiamato abc, creato durante la build con UID (ID utente) 911 e GID (ID gruppo) 911. Il container viene avviato come root, esegue gli script di inizializzazione e uno di questi script modifica l'UID e il GID dell'utente prima dell'avvio dell'applicazione:

groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abc

Il flag -o consente di usare un ID già in uso altrove. Al termine, lo script rimuove i privilegi e avvia l'applicazione come abc. Docker passa quindi PUID=1000 al container come una normale variabile d'ambiente e non interviene sul suo valore. La variabile modifica l'UID e il GID di un utente all'interno del container prima dell'avvio dell'applicazione. Di conseguenza, con un daemon rootful standard senza rimappatura dei namespace utente, i file creati vengono normalmente salvati sul disco con proprietario 1000. La scrittura su un file esistente e scrivibile non ne modifica il proprietario. Docker rootless modifica questo numero, come spiegato più avanti. Se PUID non è impostata, abc mantiene il valore 911. Per questo un bind mount non configurato si riempie di file appartenenti a 911:911.

Ottieni i due numeri con id

Esegui questo comando sull’host, usando l’utente proprietario delle directory dei dati:

id
uid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)

uid è il tuo PUID e gid è il tuo PGID. In uno script, id -u e id -g stampano solo i numeri. Nella maggior parte delle immagini VPS appena create, il primo account umano usa 1000:1000, ma non devi darlo per scontato. L’assegnazione dipende dagli account e dalla configurazione presenti: un server ricreato può assegnare di nuovo 1000, mentre a un account creato successivamente viene assegnato un ID disponibile più alto. Se i tuoi servizi vengono eseguiti con un account di servizio dedicato invece del tuo utente di accesso, esegui id thatuser e ricava i numeri da quell’output.

Perché i file risultano di proprietà di 911:911

ls -l stampa un ID numerico invece di un nome quando nessun account dell'host corrisponde a quell'ID. Se nessun account dell'host corrisponde all'UID 911, non c'è alcun nome da stampare. Usa ls -ln per visualizzare sempre i numeri ed eliminare l'ambiguità:

ls -ln /srv/appdata/sonarr
drwxr-xr-x 2 911 911 4096 Aug  7 09:12 Backups
-rw-r--r-- 1 911 911  512 Aug  7 09:12 config.xml

L'output corrisponde ai valori predefiniti integrati nel container, ma i soli file esistenti non dimostrano quale utente esegua attualmente l'applicazione. In quell'elenco, config.xml è anche il file che contiene le impostazioni di autenticazione. Questo è importante la prima volta che apri l'interfaccia web e scopri che Sonarr e Radarr non forniscono un nome utente o una password predefiniti. Verificalo dall'interno del container invece di procedere per ipotesi:

docker exec sonarr id abc
docker compose logs sonarr | head -n 25

L'init di linuxserver stampa il risultato nel log di avvio su due righe:

User UID:    911
User GID:    911

Se dopo aver impostato PUID=1000 nel file Compose queste righe riportano 911, il container in esecuzione non sta usando il valore impostato. La causa più comune è aver modificato docker-compose.yml e aver eseguito quindi docker compose restart, che riutilizza il container esistente con il relativo ambiente originale. Le modifiche all'ambiente richiedono docker compose up -d, che ricrea il container. L'altra causa è intenzionale: quando un'immagine viene eseguita in modalità di sola lettura o non-root, l'init salta completamente la riassegnazione degli ID, anche se la variabile è presente nel container. In modalità di sola lettura, il banner riporta l'ID invariato di abc; in modalità non-root riporta il proprietario di /run.

Perché non puoi eliminare un file scritto dal container

Il kernel confronta numeri, non nomi. La shell viene eseguita con UID 1000. Il file appartiene a UID 911. La directory che lo contiene è drwxr-xr-x e appartiene anch'essa a 911, quindi il gruppo e gli altri utenti dispongono dei permessi di lettura ed esecuzione, ma non di scrittura. Per eliminare un file è necessario il permesso di scrittura sulla sua directory, non sul file. Per questo ottieni il seguente risultato anche quando il file sembra innocuo:

rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission denied

Un container che deve scrivere incontra lo stesso problema dal lato opposto. Se la directory dell'host appartiene al tuo utente ed è impostata a 755, mentre l'applicazione viene eseguita con UID 911, la prima operazione di scrittura fallisce con Permission denied e l'applicazione lo segnala con il proprio messaggio. In un'applicazione .NET come Sonarr o Radarr, l'errore viene mostrato come UnauthorizedAccessException: Access to the path '/data/downloads' is denied. La stringa dei permessi davanti al file indica a quale dei tre insiemi di permessi sei effettivamente soggetto. Interpretare correttamente drwxr-xr-x è ciò che trasforma questo errore da misterioso a ovvio.

Questo è nello specifico un problema di bind mount. Quando Docker crea un named volume vuoto e lo monta su un percorso già presente nell'immagine, copia nel volume il contenuto di quel percorso, inclusi proprietario e bit dei permessi. L'applicazione trova quindi una directory di cui è già proprietaria. Un bind mount non riceve questo trattamento: Docker monta la directory dell'host esattamente nello stato in cui si trova. Questa differenza è uno dei motivi pratici per cui è importante sapere quando un bind mount è preferibile a un named volume e quando non lo è.

Correggere una directory che ha già proprietari o permessi errati

L'impostazione di PUID e PGID modifica il comportamento dell'applicazione da quel momento in poi. Non corregge retroattivamente tutti i file già presenti sul disco, anche se lo script di inizializzazione corregge la proprietà sui percorsi specifici descritti di seguito. Arresta lo stack, correggi autonomamente la proprietà dei file, quindi riavvialo:

docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -d

Usa sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr se preferisci non digitare i numeri. Esegui questa operazione con il container arrestato, perché un'applicazione ancora in esecuzione che sta scrivendo durante un chown ricorsivo può lasciare una struttura di directory corretta solo in parte e causare una seconda serie di errori difficili da interpretare.

Cosa non risolvono PUID e PGID

Questa è la parte che spesso sfugge anche a chi ha configurato tutto correttamente. Lo script di configurazione dell'utente dell'immagine di base linuxserver esegue chown su tre percorsi all'avvio: /app, /config e /defaults. I mount dei contenuti multimediali non sono inclusi nell'elenco. /data, /downloads e /tv vengono passati all'applicazione senza modifiche. Di conseguenza, se sul sistema host questi mount hanno una proprietà che impedisce all'utente del container di scrivervi, il container si avvia correttamente, mostra l'UID corretto nel banner e poi fallisce al primo import.

Questo comportamento è corretto. Eseguire un chown ricorsivo chown a ogni avvio del container su una libreria multimediale da dodici terabyte sarebbe disastroso. Questo significa però che la gestione delle directory dei contenuti multimediali spetta a voi. Sono proprio questi i mount in cui si verificano i problemi di permessi. Poiché questo tipo di errore compare spesso in modo silenzioso nel log dell'applicazione, ore dopo che il container sembrava funzionare correttamente, un test periodico di scrittura collegato a ntfy sul vostro VPS, con invio degli avvisi al telefono è un modo semplice ed economico per rilevarlo prima che una settimana di episodi mancanti renda il problema evidente.

Tre modalità per controllare l’utente e quando usare ciascuna

Variabili d’ambiente PUID e PGID

Funziona soltanto con le immagini il cui entrypoint le legge. È una soluzione diffusa perché il container viene comunque avviato come root, completa la propria configurazione, corregge /config e solo dopo riduce i privilegi. Docker Mods e gli script init personalizzati continuano a funzionare. Il limite è che ci si affida a una convenzione anziché a una funzionalità della piattaforma, e i nomi delle variabili non sono standard tra i vari progetti.

La chiave user: in Compose

Questa è una funzionalità reale di Docker e funziona con qualsiasi immagine, perché il runtime del container la applica prima che venga eseguito il codice dell’immagine:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    user: "1000:1000"

Il processo non viene mai eseguito come root, nemmeno per un istante, con un effettivo vantaggio di sicurezza. Tuttavia, si interrompe qualsiasi operazione nell’entrypoint che richieda root. Nelle immagini linuxserver il progetto supporta questa modalità facendo il possibile e soltanto per le immagini che ha testato. Le limitazioni sono precise: PUID e PGID non hanno più alcun effetto, Docker Mods non viene eseguito, i servizi personalizzati non vengono eseguiti e la gestione dei permessi su ogni volume montato ricade sull’utente. Il modello documentato associa il flag a un /run scrivibile:

user: 1000:1000
tmpfs:
  - /run:uid=1000,gid=1000,exec
security_opt:
  - no-new-privileges=true

Un effetto puramente estetico può sorprendere. Un user: numerico senza una voce corrispondente nel /etc/passwd del container fa sì che gli strumenti interni mostrino whoami: cannot find name for user ID 1000. L’ID è valido e l’accesso ai file funziona normalmente. Fallisce soltanto la ricerca del nome.

Docker rootless

Docker rootless esegue il daemon come utente non privilegiato, quindi il daemon e i container funzionano senza i privilegi dell’utente root sull’host. Questo cambia completamente il calcolo della proprietà. L’UID 0 del container viene mappato sull’UID dell’utente host che esegue Docker rootless, mentre l’UID del container n per qualsiasi n pari o superiore a 1 viene mappato su subuid + (n - 1), dove subuid è la base dell’intervallo assegnato all’utente in /etc/subuid; gli ID di gruppo seguono la stessa regola usando /etc/subgid. Docker richiede in quel file almeno 65,536 ID subordinati.

Rileggere questo mapping è importante, perché inverte le indicazioni abituali. Con Docker rootless, un container che crea un file come root produce normalmente un file di proprietà dell’utente host. Un container che crea un file come UID 1000 produce normalmente un file di proprietà di un ID subordinato, ad esempio 100999 quando l’intervallo inizia da 100000. L’accesso dalla shell dipende da permessi e ACL; l’eliminazione dipende normalmente dalla directory che contiene il file, quindi è possibile eliminare il file da una directory controllata dall’utente. Di conseguenza, il valore PUID corretto con un daemon rootful è errato in questo caso. I due meccanismi modificano la proprietà a livelli diversi e applicarli entrambi senza una verifica può impedire la scrittura nei dati montati. Se si sceglie la modalità rootless, verificare la proprietà di un file creato sul proprio server prima di migrare una raccolta di dati.

Per la maggior parte degli stack self-hosted su un singolo VPS, PUID e PGID con un daemon rootful sono la scelta più pragmatica, perché è la configurazione per cui le immagini sono state sviluppate e documentate. Usare user: quando il README dell’immagine dichiara che l’immagine è stata testata con questa modalità, oppure quando si esegue un’immagine ufficiale upstream che non supporta PUID. Un’area di lavoro per documenti come un’istanza self-hosted di AFFiNE su un singolo VPS rientra nel secondo caso, perché nessuno dei suoi container legge PUID e la proprietà della directory del database e dei file caricati viene determinata dal runtime, non da una variabile nel blocco d’ambiente. Lo stesso vale per un help desk self-hosted basato su Chatwoot, in cui il container Rails e il worker Sidekiq scrivono entrambi in una directory degli upload e nessuno dei due legge PUID; perciò la directory deve corrispondere all’utente con cui l’immagine viene già eseguita. Nulla di questo cambia con uno stack più recente, quindi assegnare a ogni persona del team il proprio agente OneCLI isolato lascia le directory di lavoro dei singoli utenti e la directory dei dati PostgreSQL di proprietà dell’utente con cui viene già eseguita ciascuna immagine. Il problema riguarda quindi user: e chown, non PUID. Posizionare una singola API self-hosted davanti a Codex, Claude Code e Hermes significa che l’entrypoint gestisce più identità: il container deve essere avviato come root, la console e il gateway vengono eseguiti come utente non privilegiato e ogni sessione dell’agente viene eseguita come utente distinto. Non aggiungere user: a questa distribuzione: l’entrypoint gestisce la proprietà del volume dei dati.

Il caso dello stack multimediale: un gruppo condiviso tra i container

Un arr media stack con Sonarr, Radarr e un client di download è il caso in cui questo principio diventa concreto. Il client di download scrive il file completato in /data/downloads. Sonarr crea quindi un hard link per quel file oppure lo sposta in /data/media. Per creare l'hard link, i due container devono avere accesso in scrittura allo stesso albero di directory. Se il client di download viene eseguito come 1000 mentre Sonarr viene eseguito come 1001, senza permessi di scrittura condivisi per il gruppo, uno dei due possiede file che l'altro può soltanto leggere.

La soluzione consiste in un gruppo condiviso che ogni container dello stack utilizza come PGID:

sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +

Il 2 iniziale in 2775 è il bit setgid. Su una directory indica che ogni nuovo file e ogni nuova sottodirectory creati al suo interno ereditano il gruppo media invece del gruppo primario dell'utente che li crea. In questo modo la configurazione resta valida anche per i nuovi download, senza dover eseguire nuovamente chown. Eseguire il logout e accedere di nuovo, oppure eseguire newgrp media, prima di verificare il proprio accesso: un gruppo aggiunto con usermod -aG non compare in una sessione shell già aperta.

All'interno del container, groupmod -o -g 13000 abc riassegna al gruppo abc il GID 13000. In questo modo abc scrive usando lo stesso GID del gruppo media sull'host. Ogni container linuxserver che accede a questo albero mantiene il proprio PUID e condivide quel PGID. Questo vale anche per i container successivi nella catena che leggono soltanto la libreria completata, come Jellyfin. Un frontend come Halcyon, che espone quella libreria come un videonoleggio degli anni 90 esplorabile, si collega a Jellyfin tramite HTTP usando HALCYON_JELLYFIN_URL. La relativa distribuzione standard non richiede né il PGID condiviso dei contenuti multimediali né un mount della directory dei contenuti multimediali.

Impostare quindi UMASK=002 su ogni container linuxserver dello stack. Questo è il passaggio che spesso viene omesso. Se non viene impostato, l'applicazione mantiene il proprio umask ereditato, a meno che qualcosa non lo modifichi. Il valore di esempio mostrato nei README delle immagini è UMASK=022. Con un umask effettivo pari a 022, un'applicazione che richiede 0666 per un nuovo file ottiene 0644 quando non esiste una ACL predefinita: il resto del gruppo può ancora leggerlo, ma non può modificarlo. Questo annulla gran parte della condivisione appena configurata. Con 002 e senza una ACL predefinita, un'applicazione che richiede i valori usuali 0666 per i file e 0777 per le directory ottiene file 0664 e, all'interno dell'albero setgid, directory 2775; il gruppo può quindi scrivere. Un umask rimuove soltanto bit, quindi un'applicazione che richiede 0600 ottiene comunque 0600. Una directory con una ACL predefinita ignora invece completamente l'umask. Aggiungere la variabile accanto a PUID e PGID:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - UMASK=002
      - TZ=Etc/UTC
    volumes:
      - /srv/appdata/sonarr:/config
      - /srv/media:/data
    restart: unless-stopped

Inserire questi due valori in un file .env accanto al file Compose, in modo che l'intero stack legga un'unica definizione:

PUID=1000
PGID=13000

Compose legge automaticamente quel file per la sostituzione nello stile ${PUID}, usando lo stesso meccanismo previsto per le credenziali. Le regole per mantenere i valori fuori da docker-compose.yml e inserirli in un file .env si applicano anche in questo caso, con la differenza che questi due numeri non sono segreti.

Verificare il funzionamento dall'inizio alla fine invece di fidarsi soltanto della configurazione. Scrivere un nuovo file come utente dell'applicazione, applicando l'umask configurato, quindi leggerlo dall'host. Usare un nome di file di test che non esista già:

docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtest

Un risultato corretto mostra il PUID dell'utente come proprietario, 13000 come gruppo e -rw-rw-r-- come modalità. Se il gruppo risulta 1000, eseguire ls -ldn /srv/media/downloads: manca il bit setgid, cioè il s in drwxrwsr-x, oppure la directory appartiene ancora al gruppo 1000 invece che a media. I comandi chown e chmod 2775 riportati sopra risolvono entrambi i problemi. Se la modalità risulta -rw-r--r--, controllare il valore UMASK del container e la ACL predefinita della directory; ricreare il container se il relativo ambiente non è aggiornato. Questo test verifica la creazione come abc con la maschera configurata. La modalità di creazione usata dall'applicazione e il suo umask effettivo determinano comunque i permessi dei relativi file. Al termine, rimuovere il file di test con rm /srv/media/downloads/permtest.

Quali immagini usano quali variabili

Le immagini di linuxserver.io usano PUID, PGID e UMASK. Paperless-ngx usa nomi diversi per lo stesso concetto: USERMAP_UID e USERMAP_GID, entrambi impostati per impostazione predefinita su 1000. La documentazione indica di leggerli da id -u e id -g. Anche i server fotografici mostrano la stessa varietà: PhotoPrism ha la propria coppia PHOTOPRISM_UID e PHOTOPRISM_GID, mentre Immich non fornisce un equivalente e lascia che l'utente del container sia determinato dalla chiave user: di Docker. Di conseguenza, scegliere tra PhotoPrism e Immich determina anche quale di questi meccanismi dovrai gestire per la libreria più grande del server. Molte immagini ufficiali upstream, comprese le comuni immagini per database e server web, usano un utente integrato fisso e si aspettano che tu utilizzi user: oppure che lasci la configurazione invariata. Anche le distribuzioni con una singola applicazione pongono la stessa domanda. Quando configuri un tracker di allenamento openGym self-hosted, conviene quindi verificare con quale utente viene eseguito realmente il container prima di associarvi un bind mount. La directory che contiene il database eredita infatti quella configurazione, indipendentemente dal fatto che tu imposti PUID. Lo stesso vale per un relay di accesso remoto. Quando esegui un server relay RustDesk autonomo, la coppia di chiavi Ed25519 che hbbs scrive al primo avvio viene creata nel bind mount con il proprietario corrispondente all'utente utilizzato dall'immagine. In seguito puoi correggere la proprietà con un comando chown eseguito sull'host, oppure scegliere in anticipo l'identità tramite la chiave user:, perché questa immagine non imposta un utente autonomamente. È sufficiente che la directory montata sia scrivibile dall'ID scelto. Lo stesso vale per l'infrastruttura aggiunta in seguito. Inserire Authentik davanti alle applicazioni per usare un unico accesso significa eseguire le immagini ufficiali di authentik e Postgres, che non leggono affatto PUID. La proprietà dei volumi dipende dagli utenti con cui vengono eseguiti i processi e dalla configurazione eseguita dai rispettivi entrypoint. Authentik ha rimosso la dipendenza da Redis nella release 2025.10.

Controlla quindi il README di ogni immagine prima di copiare un blocco di variabili d'ambiente tra progetti. Docker passa a ogni container qualsiasi variabile d'ambiente impostata, indipendentemente dal fatto che un processo interno la legga. Una PUID non utilizzata da alcun componente non produce errori, avvisi né effetti. Il container viene avviato con l'utente selezionato dall'impostazione user: di Docker o dal Dockerfile. In seguito, il relativo entrypoint può ridurre i privilegi prima di avviare l'applicazione. Esegui questa verifica prima di aggiungere qualsiasi nuovo servizio al server, compreso uno stack self-hosted di scansione della sicurezza basato su open-kritt. Il file Compose indica se le immagini rispettano PUID oppure se la proprietà delle directory montate è determinata direttamente dalle immagini.

FAQ

Perché i miei file Docker appartengono a 911:911?

911 è l'UID e il GID dell'utente abc integrato nelle immagini linuxserver.io. Il valore corrisponde ai valori predefiniti integrati, ma i file possono conservare questa proprietà dopo la modifica di PUID e PGID del container. ls -l mostra i valori numerici grezzi quando nessun account sull'host corrisponde a questi ID, quindi non è possibile visualizzare alcun nome. Impostare PUID e PGID sull'output di id, ricreare il container con docker compose up -d, quindi correggere i file esistenti con sudo chown -R 1000:1000 nella directory interessata.

PUID e PGID funzionano con tutte le immagini Docker?

No. Non sono funzionalità di Docker e Docker non li legge mai. Funzionano solo con le immagini il cui entrypoint li legge ed esegue usermod e groupmod prima di avviare l'applicazione. Questo vale per la famiglia linuxserver.io e per alcuni progetti che hanno copiato questo modello. Altri progetti usano nomi diversi, come USERMAP_UID e USERMAP_GID in paperless-ngx. In un'immagine che non legge nessuna di queste variabili, le variabili vengono accettate e ignorate senza alcun avviso.

Devo usare PUID e PGID oppure la chiave user: in Docker Compose?

Usare PUID e PGID quando l'immagine li supporta, perché l'entrypoint continua a essere eseguito come root abbastanza a lungo da correggere /config e avviare correttamente i propri servizi. Usare user: quando l'immagine documenta il supporto per l'utente scelto; la sola assenza del supporto per PUID non significa che l'entrypoint funzioni senza root. In un'immagine linuxserver, l'impostazione di user: rende inattivi PUID e PGID, impedisce l'esecuzione di Docker Mods e dei servizi personalizzati e rende l'utente responsabile dei permessi di ogni volume montato.

Sonarr ha il PUID corretto, ma non riesce ancora a spostare i file. Qual è il problema?

Controllare tre elementi, in questo ordine. Primo, il mount dei file multimediali: lo script di configurazione dell'utente dell'immagine di base esegue chown su /app, /config e /defaults, quindi /data o /downloads conserva la proprietà presente sull'host. Secondo, il gruppo condiviso: assegnare ai container che accedono all'albero dei file multimediali lo stesso PGID e i permessi di scrittura per il gruppo. Terzo, umask: una maschera effettiva di 022 produce file 0644 quando l'applicazione richiede 0666 e non si applica alcuna ACL predefinita, quindi gli altri container del gruppo possono leggerli ma non modificarli. Lasciare UMASK non impostato non garantisce una maschera o una modalità specifica per i file. Impostare UMASK=002 e applicare il bit setgid alle directory con chmod 2775, in modo che i nuovi file ereditino il gruppo. Un'applicazione che richiede 0600 crea comunque file privati, mentre un'ACL predefinita modifica il modo in cui vengono assegnati i permessi alla creazione.

Questo articolo ti è stato utile?