SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-10-21

Systemd non avvia l'unità: leggi il codice di uscita

Leggi prima systemctl status: scopri cosa significano 203/EXEC e 226/NAMESPACE e perché un'unità può avviarsi correttamente e terminare dopo un secondo.

Perché un'unità systemd non si avvia

Un'unità systemd che non si avvia indica la causa in un campo preciso. Esegui systemctl status <unit> e cerca code= e status= nella riga che segnala l'errore. Un codice di stato nell'intervallo 200 indica quasi sempre che systemd non ha mai avviato il programma: si è verificato un errore durante la preparazione dell'ambiente richiesto dal file dell'unità. Se la riga contiene code=exited con un codice inferiore a 200, il programma è stato eseguito e si è terminato autonomamente. In questo caso il file dell'unità è probabilmente corretto e il problema riguarda l'applicazione. code=killed indica che un segnale ha terminato il processo. È un caso distinto, trattato verso la fine.

Questa distinzione definisce il percorso decisionale. Tutto ciò che segue dipende da essa, nell'ordine in cui vengono visualizzati i codici.

Quali tre comandi rispondono alla domanda, nell'ordine

systemctl status myapp.service
journalctl -u myapp.service -b --no-pager
systemd-analyze verify /etc/systemd/system/myapp.service

systemctl status fornisce il verdetto. Leggere prima la riga Loaded:, perché indica il file che systemd ha effettivamente analizzato e specifica se l'unità è abilitata, mascherata o completamente assente. Leggere quindi la riga Active: e la coppia code= e status= riportata sotto.

journalctl -u myapp.service -b --no-pager fornisce i dettagli. -u filtra una sola unità, -b limita l'output all'avvio corrente, così non si legge un errore della settimana precedente, e --no-pager stampa direttamente sul terminale, consentendo di inoltrare l'output a grep. status mostra soltanto le ultime righe del log e tronca quelle troppo lunghe. Il journal mostra tutto ciò che il programma ha stampato prima di terminare. Di solito contiene l'errore effettivo. Senza -n vengono visualizzate tutte le voci di questo avvio. Aggiungere -n 100 per conservare soltanto le ultime 100, oppure eseguire il comando con -f in un secondo terminale mentre si riavvia l'unità.

systemd-analyze verify carica un file di unità senza eseguirlo. Segnala sezioni e direttive sconosciute e indica i comandi in ExecStart= che non riesce a eseguire. Questo rileva due categorie di errori difficili da notare: una chiave scritta in modo errato, che systemd ignora al caricamento mostrando un avviso che spesso non viene letto, e un percorso inesistente.

Dopo aver modificato un file di unità, eseguire sudo systemctl daemon-reload. Fino a quel momento, systemd continua a usare la copia caricata in precedenza e systemctl status aggiunge un avviso che il file su disco è cambiato. Una correzione che "non ha prodotto alcun effetto" spesso è una correzione che systemd non ha ancora riletto.

Altri due comandi sono utili. systemctl cat myapp.service stampa l'unità effettiva, cioè il file principale e tutti i drop-in presenti in /etc/systemd/system/myapp.service.d/. systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory stampa questi valori nel formato analizzato da systemd, cioè quello che verrà effettivamente eseguito.

Che cosa significa status=203/EXEC?

203/EXEC indica che systemd ha completato la configurazione, ha chiamato execve() e il kernel ha rifiutato l'esecuzione. Il programma non ha eseguito alcuna istruzione del proprio codice. Quattro cause coprono quasi tutti i casi.

  1. Il percorso in ExecStart= è errato oppure non è assoluto. Verificalo con ls -l e confrontalo con la stringa esatta presente nel file unit.
  2. Il file non ha il bit di esecuzione. sudo chmod +x /opt/myapp/run.sh lo imposta. Un file estratto da un archivio o copiato da un altro computer spesso perde questo bit.
  3. La riga shebang è errata. Il kernel legge la prima riga di uno script ed esegue l'interprete indicato. Per questo #!/usr/bin/env python3 fallisce quando il PATH del servizio non contiene python3. Inoltre, un file salvato con terminatori di riga Windows richiede un interprete chiamato /bin/bash\r, che non esiste.
  4. Il file non è eseguibile su questo computer: ha un'architettura errata oppure è un file di testo privo di shebang.

Riproduci il problema manualmente, usando l'utente del servizio, prima di modificare qualsiasi cosa.

sudo -u appuser /opt/myapp/run.sh
file /opt/myapp/run.sh
head -1 /opt/myapp/run.sh | cat -A

file indica l'architettura e mostra "with CRLF line terminators" quando il problema riguarda i terminatori di riga. cat -A mostra lo stesso problema sotto forma di ^M finale. Rimuovili con sed -i 's/\r$//' /opt/myapp/run.sh.

Una precisazione importante sull'intervallo: 200 e valori superiori sono una convenzione, non una garanzia. Il tuo programma può terminare con 203 e systemd non è in grado di distinguere i due casi. systemd-analyze exit-status 203 stampa il nome e la classe di qualsiasi codice; questo aiuta a leggere la tabella. Tuttavia, se l'applicazione utilizza codici di uscita superiori a 199, modificali.

Perché ottengo 217/USER o 216/GROUP?

217/USER indica in genere che l'account specificato in User= non esiste quando il servizio viene avviato. Lo stesso codice comprende anche il mancato avvio della gestione degli spazi dei nomi utente per un'opzione di sandboxing come PrivateUsers=. In questo caso, il journal riporta "Failed to set up user namespacing" invece di indicare un utente mancante. 216/GROUP segnala lo stesso errore per Group= o SupplementaryGroups=. Verificalo con un comando per ciascun caso.

getent passwd appuser
getent group appgroup

Ciascun comando stampa una riga oppure non stampa nulla e restituisce un codice diverso da zero. Nessun output significa che il nome non è noto al sistema. systemd non può quindi eseguire il cambio e interrompe l'avvio prima di exec. La soluzione consiste nel creare l'account, non nell'impostare User=root. Eseguire un servizio con un account di sistema dedicato e privilegi minimi è esattamente lo scopo di quella direttiva.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin appuser

DynamicUser=yes aggira il problema, chiedendo a systemd di allocare un account temporaneo a ogni avvio. È adatto a un servizio che non conserva dati persistenti. Qualsiasi servizio che scrive file richiede anche StateDirectory=, perché l'ID utente cambia a ogni avvio e i file memorizzati in un percorso semplice finiscono di proprietà di un account che non esiste più.

Che cos’è 226/NAMESPACE?

226/NAMESPACE deriva dalle direttive di sandboxing. Quando un’unità imposta ProtectSystem=, ProtectHome=, PrivateTmp=, ReadWritePaths= o direttive simili, systemd crea un mount namespace privato per il servizio prima di eseguire il programma. In questo contesto, un namespace è una vista privata del filesystem per un singolo processo. Se un mount previsto dal piano non riesce, l’avvio termina con il codice 226 e il programma non viene mai eseguito.

La causa più comune è un percorso in ReadWritePaths= che non esiste. ProtectSystem=strict monta l’intero filesystem in sola lettura, mentre ReadWritePaths= riapre in scrittura i percorsi indicati. systemd non può riaprire una directory che non esiste. Sono disponibili due correzioni appropriate. Lasciare che systemd crei la directory con StateDirectory=, che crea /var/lib/<name> a ogni avvio e la assegna all’utente del servizio, oppure anteporre il prefisso - al percorso, indicando a systemd di ignorare la voce quando la sorgente non è disponibile. La correzione sbagliata consiste nel rimuovere il blocco di hardening, trasformando un problema di cinque minuti in un problema permanente.

[Service]
ProtectSystem=strict
ProtectHome=yes
StateDirectory=myapp
ReadWritePaths=-/srv/uploads

Quando non è possibile capire quale riga sia responsabile, rimuovere l’intero blocco di hardening, ricaricare la configurazione e avviare il servizio. Se il servizio parte, aggiungere nuovamente le righe una alla volta e riavviare dopo ciascuna modifica. Due codici correlati sono 233/RUNTIME_DIRECTORY e 238/STATE_DIRECTORY. Indicano che systemd non ha potuto creare o assegnare la proprietà della directory indicata in RuntimeDirectory= o StateDirectory=, di solito perché il percorso esiste già ed è assegnato a un altro utente.

Perché compare 200/CHDIR quando WorkingDirectory sembra corretto?

200/CHDIR indica che chdir() in WorkingDirectory= non è riuscito. La directory non esiste oppure l’utente del servizio non può accedervi. Per accedere a una directory è necessaria l’autorizzazione di esecuzione sulla directory e su ogni directory padre del percorso. Di conseguenza, un /home/deploy/app perfettamente leggibile non è raggiungibile quando /home/deploy ha modalità 700 e il servizio viene eseguito come appuser.

sudo -u appuser test -x /srv/myapp && echo ok
namei -l /srv/myapp

namei -l mostra il proprietario e la modalità di ogni componente del percorso. È il modo più rapido per individuare la directory che impedisce l’accesso al resto del percorso. Impostare WorkingDirectory=-/srv/myapp rende non fatale l’assenza della directory. È corretto per un programma che non dipende dalla directory iniziale, ma non per un programma che apre file usando percorsi relativi.

Perché il servizio si avvia e poi si arresta un secondo dopo?

Qui non compare alcun codice della serie 200 e spesso non viene mostrato neppure un messaggio di errore. L’unità mostra inactive (dead) subito dopo l’avvio oppure passa ciclicamente a activating (auto-restart). systemd ha configurato correttamente l’ambiente. Il problema è la differenza tra il comportamento effettivo del programma e quello previsto da Type=.

Type=simple, l’impostazione predefinita, indica che il programma rimane in primo piano. Se gli si assegna un demone che esegue il fork in background e termina, systemd rileva la conclusione del processo principale e considera completato il servizio. La maggior parte dei demoni dispone di un’opzione per rimanere in primo piano, ad esempio nginx -g 'daemon off;'.

Type=forking indica che il primo processo termina quando il processo figlio è pronto. Se gli si assegna un programma che rimane in primo piano, il job di avvio attende finché non scade TimeoutStartSec=, che per impostazione predefinita è di 90 secondi; quindi systemd termina il processo e registra un timeout.

Type=notify indica che il programma chiama sd_notify() per segnalare di essere pronto. Un programma che non supporta questa funzione non invia alcuna segnalazione. Di conseguenza, l’avvio va in timeout e il journal registra il risultato come errore di protocollo.

Scegliere il tipo in base al comportamento effettivo del programma. Differenze tra simple, forking, oneshot e notify è il riferimento che consente di risolvere questa intera classe di errori.

Quando un servizio termina ripetutamente, systemd smette di tentare l’avvio e segnala che la richiesta di avvio è stata ripetuta troppo rapidamente. L’unità rimane quindi nello stato failed e systemd non la riavvia automaticamente. È possibile avviarla manualmente dopo la scadenza dell’intervallo del limite di frequenza oppure eseguire sudo systemctl reset-failed myapp.service, che cancella lo stato failed e il contatore dei riavvii, consentendo di avviare subito il servizio manualmente. Aumentare il limite nasconde soltanto il sintomo. Consultare il journal a partire dal primo errore, non dall’ultimo, e leggere che cosa ritenta davvero Restart=on-failure prima di modificarlo.

Perché l’unità è inattiva senza alcun errore?

Un’unità può essere ignorata invece di essere avviata. Le direttive Condition* sono silenziose per progettazione: quando il controllo non viene superato, systemd considera il job riuscito e non esegue alcuna azione. Un’unità che contiene ConditionPathExists=/etc/myapp/config.yml non verrà mai avviata finché il file non esiste e non segnalerà mai un errore.

systemctl show myapp.service -p ConditionResult -p ConditionTimestamp
journalctl -u myapp.service -b --no-pager | grep -i condition

ConditionResult=no conferma l’omissione e il journal indica il controllo che non è stato soddisfatto. Usa invece una direttiva Assert* quando l’assenza di un prerequisito deve generare un errore esplicito. Condizioni, assert e ordinamento delle unità spiega quale controllo utilizzare in ciascun punto.

Esistono anche altri casi silenziosi nelle vicinanze. Un errore “could not be found” indica di solito che il file si trova nella directory sbagliata oppure che non hai ricaricato la configurazione: i file delle unità creati manualmente devono trovarsi in /etc/systemd/system/. Un’unità mascherata rifiuta ogni avvio finché sudo systemctl unmask myapp.service non rimuove la maschera. Inoltre, systemctl enable non funziona su un’unità priva della sezione [Install], quindi aggiungi WantedBy=multi-user.target.

Cosa succede se il processo è stato terminato invece di essere considerato non riuscito?

code=killed indica una situazione diversa da code=exited. Qualcosa ha terminato il processo dall'esterno. status=9/KILL indica spesso l'intervento dell'out-of-memory (OOM) killer e, in questo caso, il journal indica il processo selezionato. SIGKILL non indica però chi lo ha inviato: systemd lo invia a sua volta quando un servizio in fase di arresto ignora SIGTERM oltre TimeoutStopSec=. Prima di attribuire la causa alla memoria, verifica quindi se era in corso un arresto o un riavvio. Un limite impostato direttamente da te produce lo stesso effetto all'interno del cgroup (control group). Controlla quindi la memoria libera sull'host con free -m e verifica nell'unità la presenza di MemoryMax=. MemoryMax, CPUQuota e gli altri limiti del cgroup spiega quale limite termina un processo e quale invece ne riduce soltanto la velocità.

status=15/TERM subito dopo un tentativo di avvio indica di solito che systemd ha superato il timeout di avvio e ha terminato il processo. Devi quindi tornare a Type=.

Due abitudini che evitano la maggior parte di questi errori

Usate sempre percorsi assoluti. systemd non esegue la shell di login, quindi non sono disponibili .bashrc, .profile né un ambiente virtuale attivato. $PATH per un servizio di sistema è un elenco integrato molto breve, che non contiene /opt né gli shim di un gestore delle versioni del linguaggio. Scrivete per esteso /usr/bin/python3 o /opt/myapp/venv/bin/python. command -v myapp nella shell stampa il percorso da incollare. La stessa regola vale per WorkingDirectory=, EnvironmentFile= e per ogni percorso in ReadWritePaths=.

ExecStart= non è una shell. systemd divide la riga in parole e chiama direttamente execve(). Pipe, redirezioni, glob, &&, backtick e ~ non hanno alcun significato: arrivano al programma come argomenti letterali. ExecStart=/usr/bin/myapp --flag > /tmp/out.log passa > e /tmp/out.log a myapp, che termina quindi con un errore di utilizzo apparentemente scollegato da un problema di systemd. Quando servono funzionalità della shell, richiedete esplicitamente una shell.

ExecStart=/bin/sh -c '/usr/bin/myapp --flag | /usr/bin/tee -a /var/log/myapp.log'

Per il solo output non è necessario. Per impostazione predefinita, l'output del servizio viene inviato al journal e StandardOutput=append:/var/log/myapp.log scrive in un file senza coinvolgere alcuna shell.

L'espansione delle variabili è limitata nello stesso modo. $MYVAR e ${MYVAR} vengono sostituite leggendo da Environment=, EnvironmentFile= e dalle poche variabili impostate direttamente da systemd, come $USER; anche gli specificatori %, come %i, vengono espansi. Nulla di ciò che proviene dalla shell di login viene espanso. $HOME viene impostata solo quando l'unità contiene User=, tramite il valore predefinito di SetLoginEnvironment=; di conseguenza, un servizio eseguito come root senza User= non dispone di $HOME, a meno che non lo impostiate. Un EnvironmentFile= non è neppure uno script di shell: export non è previsto al suo interno, le regole di quoting sono diverse da quelle di bash e un file mancante causa un errore irreversibile, a meno che non anteponiate - al percorso.

Procedura su un server in produzione

Leggi il codice, dimostra la causa, modifica una sola cosa e riavvia. L'ordine è più importante del conoscere ogni numero, perché evita di accumulare tre modifiche speculative e di perdere di vista quale abbia risolto il problema. La stessa procedura funziona anche per le unità che non hai scritto tu. Un timer che non viene mai attivato dipende da un servizio che non è mai stato avviato, quindi esegui prima il debug del servizio: un timer systemd e il servizio che attiva presenta esattamente i problemi descritti sopra, mentre il timer nasconde l'output finché non lo richiedi al journal.

FAQ

Che cosa significa status=203/EXEC in systemctl status?

systemd ha configurato tutto ciò che l'unità richiedeva, quindi la chiamata execve() non è riuscita e il programma non è mai stato avviato. Controllare questi quattro elementi, nell'ordine: il percorso in ExecStart= esiste ed è assoluto, il file ha il bit di esecuzione, lo shebang specifica un interprete presente nel PATH del servizio e il file usa terminatori di riga Unix. Per l'ultimo controllo, file restituisce "with CRLF line terminators". In questo caso il nome dell'interprete diventa /bin/bash\r e il kernel rifiuta di eseguire il file.

Perché il servizio si avvia e poi si arresta subito?

Il file dell'unità definisce un comportamento che il programma non implementa. Con Type=simple systemd si aspetta che il programma resti in primo piano. Un daemon che esegue il fork e passa in background sembra quindi terminato non appena esegue il fork. Con Type=forking systemd attende l'uscita del primo processo. Un programma in primo piano fa quindi rimanere bloccato il job di avvio finché non scade TimeoutStartSec=. Impostare Type= in base al comportamento del programma. Se il programma offre un flag per l'esecuzione in primo piano, usare quel flag insieme al valore predefinito Type=simple.

Come posso visualizzare l'errore reale invece dell'output di stato abbreviato?

systemctl status stampa soltanto le ultime righe del journal e tronca quelle troppo lunghe. Eseguire journalctl -u myapp.service -b --no-pager per visualizzare tutto ciò che l'unità ha registrato durante questo boot, aggiungere -n 200 per conservare soltanto le 200 righe più recenti oppure passare l'output a grep. Se l'applicazione scrive un proprio file di log, leggere anche quello, perché systemd acquisisce soltanto ciò che il programma invia allo standard output e allo standard error.

Perché la mia unità è inattiva senza messaggi di errore?

Nella maggior parte dei casi, una direttiva Condition* ha impedito l'avvio. Questi controlli sono silenziosi: se una condizione non è soddisfatta, il job di avvio viene contrassegnato come riuscito. Eseguire systemctl show myapp.service -p ConditionResult e cercare ConditionResult=no, quindi leggere la riga del journal che identifica il controllo. Un'altra causa comune è un'unità mascherata, che rifiuta ogni avvio finché sudo systemctl unmask non rimuove la maschera.

È necessario eseguire daemon-reload dopo ogni modifica al file dell'unità?

Sì, per qualsiasi modifica a un file dell'unità o a un drop-in. sudo systemctl daemon-reload fa rileggere a systemd i file dal disco, quindi sudo systemctl restart myapp.service applica le modifiche al servizio in esecuzione. Non è necessario dopo systemctl edit, che esegue automaticamente il reload, e non è necessario dopo la modifica di un file di configurazione appartenente all'applicazione anziché a systemd.

Questo articolo ti è stato utile?

#systemd#troubleshooting#journalctl#exit-codes#linux-fundamentals