Perché systemd non ha riavviato il tuo servizio
Restart= controlla solo il processo principale: un figlio può morire nello stesso cgroup senza attivare il riavvio. Scopri Type=, limiti e journal.
La risposta breve: le policy di riavvio di systemd monitorano un processo
Le policy di riavvio di systemd monitorano un solo processo per unità: il processo principale. Restart= legge lo stato di uscita di quel processo e dei comandi brevi che systemd esegue direttamente al suo interno, come ExecStartPre=, ExecStartPost= e ExecReload=. Non legge nient'altro. Il control group di un'unità può contenere venti processi; uno di questi può terminare, mentre l'unità resta active (running) perché il processo principale è ancora attivo. Per systemd non si è verificato alcun errore, quindi non viene eseguito alcun riavvio.
systemd conosce anche gli altri processi. Li termina quando l'unità viene arrestata, conteggia la memoria che utilizzano nei limiti dell'unità, applica loro la quota CPU dell'unità e li mostra in systemctl status. Semplicemente, non legge mai il loro stato di uscita. La logica di riavvio e il cgroup sono due elementi distinti, e gran parte di questa guida riguarda la differenza tra i due.
Cosa contiene il cgroup e quali dati legge la logica di riavvio
Un cgroup (control group) è un oggetto del kernel che gestisce un insieme di processi. Ogni unità di servizio ne riceve uno, denominato come l'unità. Un processo non può uscirne. I processi figli ereditano il cgroup del processo padre e un processo non privilegiato non può spostarsi altrove. Per questo systemd può terminare un daemon che esegue due fork, cosa che i vecchi script init non riuscivano a fare in modo affidabile.
Osserva i due dati affiancati:
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Restart -p RestartUSec myapp.servicesystemd-cgls elenca tutti i processi presenti nell'unità. MainPID è l'unico valore letto dalla policy di riavvio. Quando questi due dati non corrispondono al modello mentale, la discrepanza indica il problema. MainPID=0 significa che systemd non dispone di un processo principale da cui leggere lo stato di uscita. Continua comunque a monitorare il cgroup, quindi rileva quando l'ultimo processo al suo interno termina; fino a quel momento, però, la logica di riavvio non dispone di uno stato di uscita da valutare.
Esiste un'effettiva eccezione alla regola del processo principale. Se l'out-of-memory killer del kernel termina un processo qualsiasi all'interno del cgroup dell'unità, systemd lo rileva perché monitora il file memory.events del cgroup. OOMPolicy= decide cosa accade dopo e il valore predefinito è stop: l'intera unità viene arrestata, il risultato viene registrato come oom-kill e questo viene considerato un errore, quindi viene attivato Restart=on-failure. Il journal lo indica chiaramente.
myapp.service: A process of this unit has been killed by the OOM killer.
myapp.service: Failed with result 'oom-kill'.Quindi un processo figlio terminato per esaurimento della memoria arresta l'unità, mentre lo stesso processo figlio terminato da un segmentation fault non la arresta. Se imposti limiti di memoria su un'unità, leggi come MemoryMax e CPUQuota si applicano al cgroup di un'unità prima di configurare la policy di riavvio, perché queste due funzioni interagiscono proprio in questo punto e in nessun altro.
Come Type= seleziona il processo principale
Type= nella sezione [Service] non riguarda soltanto l'ordine di avvio. È la regola che determina quale PID (process ID) diventa MainPID, cioè determina anche ciò che Restart= può vedere.
Type=simpleè il valore predefinito. Il processo che systemd biforca daExecStart=è il processo principale. systemd contrassegna l'unità come avviata immediatamente, prima di sapere seexecha funzionato. Un errore nel percorso del binario produce un job di avvio completato correttamente, seguito daMain process exited, code=exited, status=203/EXECun momento dopo.Type=execsi comporta comesimple, ma il job di avvio attende cheexecabbia avuto esito positivo. In questo modo l'errore nel percorso indicato sopra diventa un errore di avvio effettivo. Richiede systemd 240 o versioni successive. Ubuntu 20.04 e versioni successive e Debian 12 lo includono, mentre Ubuntu 18.04, ancora coperto tramite Ubuntu Pro, distribuisce systemd 237 e non lo include. Quando è disponibile, preferirlo asimple.Type=forkingpresuppone che il processo diExecStart=biforchi un daemon in background e poi termini. systemd attende che il processo padre termini, quindi cerca il daemon effettivo. ImpostarePIDFile=. Senza questo valore,GuessMainPID=(abilitato per impostazione predefinita) funziona soltanto quando nel cgroup rimane esattamente un processo. Se ne rimangono due,MainPIDresta0.Type=notifyindica che il servizio chiamasd_notify(3)e inviaREADY=1quando è pronto a gestire il traffico. Può anche inviareMAINPID=per indicare a systemd un processo diverso da monitorare. ConType=notify,NotifyAccess=viene impostato sumain, salvo diversa scelta; di conseguenza, una notifica inviata da un processo figlio viene ignorata e il journal indica il PID da cui proviene.Type=oneshotnon ha un processo principale persistente. L'unità passa allo stato inattivo non appenaExecStart=termina, a meno che non si impostiRemainAfterExit=yes. QuiRestart=alwayseRestart=on-successvengono rifiutati, con il messaggioService has Restart= set to either always or on-success, which isn't allowed for Type=oneshot services. Refusing.. Gli altri valori, inclusoon-failure, sono accettati.
È utile memorizzare due errori relativi a Type=forking, perché entrambi lasciano un'unità apparentemente non funzionante senza una causa visibile:
myapp.service: Can't open PID file /run/myapp.pid (yet?) after start: No such file or directory
myapp.service: New main PID 4711 does not belong to service, and PID file is not owned by root. Refusing.Il primo indica che il daemon scrive il proprio file PID in un'altra posizione oppure lo scrive dopo che systemd ha eseguito il controllo. Il secondo indica che il file PID specifica un processo esterno al cgroup dell'unità. systemd rifiuta di adottarlo, perché altrimenti un file PID scrivibile potrebbe essere usato per fare in modo che systemd invii segnali a qualsiasi processo presente sul server.
Perché uno script wrapper nasconde la terminazione dei processi figli
Ecco la struttura che porta alla domanda del titolo.
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
waitL'unità è Type=simple, quindi il processo principale è la shell. wait senza argomenti restituisce il controllo solo dopo la terminazione di tutti i processi figli. Terminate il worker: la shell continua ad attendere il processo web, quindi la shell non termina, MainPID non termina e Restart= non viene mai consultato. Il cgroup contiene ora un processo in meno, systemctl status stampa l'albero più corto e l'unità è ancora active (running). systemd non controlla l'albero per rilevare queste modifiche.
Una seconda variante dello stesso errore è più silenziosa:
ExecStart=/bin/sh -c 'export APP_ENV=production; /usr/local/bin/myapp'Il processo principale è la shell, non myapp. Su systemctl stop, systemd invia SIGTERM al processo principale, ma una shell in attesa di un processo figlio in primo piano non inoltra il segnale. L'arresto richiede quindi l'intero TimeoutStopSec, 90 secondi per impostazione predefinita, e termina così:
myapp.service: State 'stop-sigterm' timed out. Killing.
myapp.service: Killing process 4711 (myapp) with signal SIGKILL.La correzione è exec. Scrivete exec /usr/local/bin/myapp: la shell viene sostituita dal programma, quindi MainPID è il programma e i segnali lo raggiungono. Meglio ancora, eliminate la shell e usate Environment= o EnvironmentFile= nell'unità. Questo problema non si manifesta quando la stringa -c contiene un solo comando, perché bash e dash ottimizzano entrambi questo caso eseguendo direttamente exec. Aggiungete un secondo comando alla stringa e la shell rimane in esecuzione davanti al programma.
Riproduzione su una VPS di test in due minuti
Salvate il wrapper precedente come /usr/local/bin/two-children.sh, rendetelo eseguibile con chmod +x e sostituite i due percorsi dei programmi con sleep 3600. Collegate un'unità allo script con Type=simple e Restart=on-failure, quindi eseguite systemctl daemon-reload e avviatela. Eseguite systemd-cgls --unit two-children.service e prendete nota dei tre PID: la shell e i due processi figli. Terminate un processo figlio con sudo kill <pid>. Controllate nuovamente l'unità. L'albero contiene un processo in meno, lo stato è ancora active (running) e il journal non contiene nuovi messaggi. Ora eseguite sudo kill -9 <shell pid>. L'unità entra nello stato di errore, il processo figlio rimasto viene terminato perché KillMode=control-group è il valore predefinito e il journal mostra Scheduled restart job, restart counter is at 1.
Il vocabolario completo di Restart= e quando on-failure è preferibile ad always
Restart= accetta uno dei sette valori. La distinzione fondamentale riguarda ciò che viene considerato un’uscita regolare. systemd considera regolari il codice di uscita 0, tutti i codici elencati in SuccessExitStatus= e, per ogni tipo tranne Type=oneshot, i segnali SIGHUP, SIGINT, SIGTERM e SIGPIPE. Tutto il resto, inclusi SIGKILL e SIGSEGV, è considerato un’uscita anomala.
noè il valore predefinito. L’unità non viene mai riavviata automaticamente. Per questo un’unità senza una direttivaRestart=termina al primo crash e resta arrestata.on-successriavvia l’unità solo dopo un’uscita regolare.on-failureriavvia l’unità dopo un codice di uscita diverso da zero, un segnale anomalo, un timeout durante l’avvio o l’arresto oppure la scadenza del watchdog.on-abnormalriavvia l’unità dopo un segnale anomalo, un timeout o la scadenza del watchdog, ma non dopo un semplice codice di uscita diverso da zero.on-abortriavvia l’unità solo dopo un segnale anomalo, cioè dopo un crash.on-watchdogriavvia l’unità solo quando scadeWatchdogSec=.alwaysriavvia l’unità dopo ogni caso precedente, inclusa un’uscita regolare con stato 0.
on-failure è il valore predefinito corretto per un daemon a esecuzione continua. Riavvia il servizio dopo un crash, ma lascia fermo un exit 0 intenzionale. always è adatto a un programma che termina regolarmente per motivi indipendenti dal servizio, ad esempio un client VPN che restituisce 0 quando il peer remoto si disconnette. Il problema di always è che nasconde gli errori: un servizio che si avvia, legge un file di configurazione non valido, registra l’errore e termina con codice 0 viene semplicemente riavviato. Con l’intervallo predefinito di 100 millisecondi raggiunge rapidamente il limite di frequenza degli avvii descritto di seguito e termina nello stato failed con start-limit-hit. Con un valore RestartSec= sufficientemente lungo da restare sotto tale limite, il servizio entra in un ciclo infinito. L’unico indizio è un contatore dei riavvii in continuo aumento.
SuccessExitStatus= modifica la distinzione tra uscita regolare e anomala. Borg termina con 1 in caso di avvisi e con 2 in caso di errori. Di conseguenza, un’unità di backup senza SuccessExitStatus=1 viene contrassegnata come failed ogni volta che salta un file illeggibile. RestartPreventExitStatus= elenca i codici che impediscono un riavvio anche con always. È il modo corretto con cui un programma può indicare che non deve essere riavviato. RestartForceExitStatus= fa l’opposto. Un job di backup deve essere configurato in un’unità Type=oneshot avviata da un timer, non in un ciclo di riavvio. Per questo caso, copia la struttura di coppia di servizio e timer che esegue un job secondo una pianificazione.
Un’avvertenza sui test. Terminare il servizio con un semplice kill <pid> invia SIGTERM, che appartiene all’elenco dei segnali regolari. Di conseguenza, Restart=on-failure non esegue alcuna operazione e si può concludere erroneamente che la configurazione sia danneggiata. Usa invece kill -9 <pid> o systemctl kill -s SIGKILL myapp.service. Ricorda inoltre che nessun valore di Restart= viene applicato dopo systemctl stop oppure quando l’unità viene arrestata perché una dipendenza BindsTo= o PartOf= non è più disponibile. Un’operazione di arresto non è un errore.
RestartSec e il valore predefinito di 100 millisecondi
RestartSec= è l'intervallo tra l'arresto dell'unità e il nuovo avvio da parte di systemd; il valore predefinito è 100 millisecondi. Verifica il valore effettivamente caricato dall'unità:
systemctl show -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst myapp.serviceUn'unità che non lo ha impostato mostra RestartUSec=100ms, a meno che qualcuno non abbia modificato DefaultRestartSec= in /etc/systemd/system.conf, da cui proviene il valore non impostato. Questo valore predefinito è adeguato per un servizio che si arresta in modo anomalo una volta e poi riparte. È errato per un servizio che non può avviarsi affatto, perché l'avvio iniziale e quattro riavvii rientrano ampiamente in meno di un secondo quando il programma fallisce immediatamente, esaurendo così i cinque avvii consentiti dal limite di frequenza descritto di seguito. Per qualsiasi servizio che attende un database, un mount o una route di rete, imposta RestartSec=5s o un valore superiore.
A ottobre 2026, systemd 254 e versioni successive offrono anche RestartSteps= e RestartMaxDelaySec=, che aumentano il ritardo da RestartSec= fino a un limite massimo nell'arco del numero di tentativi specificato. Ubuntu 24.04 include systemd 255 e supporta queste opzioni. Debian 12 include systemd 252 e non le supporta, anche se bookworm-backports include systemd 254. I ritardi crescenti sono la soluzione corretta quando la dipendenza potrebbe rimanere indisponibile a lungo.
Che cosa significa realmente "start request repeated too quickly"
Questo è lo stato che induce a pensare che systemd rinunci in modo arbitrario. In realtà si tratta di un contatore. La regola è questa: se un'unità viene avviata più di StartLimitBurst= volte nell'intervallo StartLimitIntervalSec=, systemd rifiuta di avviarla di nuovo e la porta nello stato failed. I valori predefiniti sono 5 avvii in 10 secondi.
Il journal mostra la sequenza:
myapp.service: Scheduled restart job, restart counter is at 5.
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.
Failed to start myapp.service - My application.e systemctl start fornisce già il comando per correggere il problema:
Job for myapp.service failed because start of the service was attempted too often. See "systemctl status myapp.service" and "journalctl -xeu myapp.service" for details. To force a start use "systemctl reset-failed myapp.service" followed by "systemctl start myapp.service" again.systemctl reset-failed myapp.service azzera il contatore e lo stato failed. Senza questo comando, un semplice systemctl start continua a essere rifiutato finché non è trascorso l'intervallo StartLimitIntervalSec=, e i riavvii automatici restano disattivati finché qualcosa non avvia di nuovo l'unità. Anche gli avvii manuali vengono conteggiati nel limite, quindi alcune esecuzioni impazienti di systemctl restart mentre modificate un file di configurazione possono far scattare il limite senza che si sia verificato alcun crash.
L'aspetto fuorviante è questo: start-limit-hit non indica mai perché il servizio non riusciva ad avviarsi. Dice soltanto che l'avvio è fallito ripetutamente e in rapida successione. La causa reale si trova nelle righe precedenti del journal.
Entrambe le impostazioni appartengono alla sezione [Unit]. Troverete esempi che le inseriscono in [Service], posizione accettata dalle versioni precedenti di systemd, ed è qui che nasce la confusione. Inseritele in [Unit], quindi chiedete a systemd quali valori ha caricato con systemctl show, perché contano soltanto i valori effettivamente caricati.
[Unit]
Description=My application
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=exec
ExecStart=/usr/local/bin/myapp
Restart=on-failure
RestartSec=10sIn questo modo l'unità dispone di cinque tentativi in un intervallo di cinque minuti prima che systemd rinunci. StartLimitIntervalSec=0 disattiva completamente il limite. Dovete però sapere che cosa comporta questa scelta: un servizio che non riesce mai ad avviarsi verrà ritentato all'infinito e scriverà una voce nel journal a ogni tentativo. I valori predefiniti a livello dell'intero sistema si trovano in /etc/systemd/system.conf, rispettivamente come DefaultStartLimitIntervalSec= e DefaultStartLimitBurst=.
Un'impostazione correlata richiede un'avvertenza. StartLimitAction= stabilisce che cosa accade quando viene raggiunto il limite e accetta valori come reboot, reboot-force e poweroff. Il valore predefinito è none: l'unità passa allo stato failed e il sistema non esegue altre azioni. Su un VPS remoto, poweroff significa che la macchina resta spenta finché non aprite la console del provider.
Una procedura per unità: un processo per ogni unità
Questa è la soluzione nella maggior parte dei casi. Se devono essere eseguiti due programmi, scrivete due unità. In questo modo ciascuna unità ha un processo principale effettivo, un vero stato di uscita e una propria politica di riavvio. Ottenete anche log, limiti delle risorse e contatori dei riavvii separati, come è necessario alle tre del mattino.
Definite la relazione tra le unità nei file delle unità, non in uno script shell.
After=ordina soltanto l'avvio. Non fornisce alcuna informazione sugli errori.Requires=avvia l'altra unità insieme a questa e arresta questa unità se l'altra viene arrestata esplicitamente.BindsTo=equivale aRequires=, ma include il caso che interessa: questa unità viene arrestata quando l'altra si arresta per qualsiasi motivo, incluso un crash. Abbinatelo aAfter=, altrimenti l'ordinamento non è definito.PartOf=propaga verso il basso l'arresto e il riavvio, quindisystemctl restart myapp.targetraggiunge ogni unità che èPartOf=a essa.Upholds=(systemd 249 e versioni successive, quindi Ubuntu 22.04 e versioni successive) mantiene in esecuzione l'unità indicata: se si arresta, systemd la avvia nuovamente. È soggetta allo stesso limite sulla frequenza di avvio applicato a tutte le altre unità.
Un worker che non deve mai essere eseguito senza il relativo server API e che systemd mantiene attivo ogni volta che l'API è attiva:
# /etc/systemd/system/myapp-api.service
[Unit]
Description=myapp API server
Wants=network-online.target
After=network-online.target
Upholds=myapp-worker.service
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp serve
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target# /etc/systemd/system/myapp-worker.service
[Unit]
Description=myapp background worker
BindsTo=myapp-api.service
After=myapp-api.service
StartLimitIntervalSec=120
StartLimitBurst=5
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp worker
Restart=on-failure
RestartSec=5sIl worker non ha una sezione [Install] e non viene mai abilitato manualmente. L'unità API lo include con Upholds=, quindi systemctl enable --now myapp-api.service è l'unico comando da eseguire. Ricaricate la configurazione e verificate come systemd ha gestito la coppia:
sudo systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp-worker.service
systemctl list-dependencies myapp-api.servicesystemd-analyze verify non stampa nulla quando il file è corretto. Qualsiasi output indica un problema, di solito una chiave che systemd non riconosce nella sezione in cui è stata scritta oppure una dipendenza da un'unità inesistente.
Correzione 2: Type=notify, così systemd conosce più del solo PID
Se il programma supporta il protocollo di notifica di systemd, usalo. Con Type=notify il servizio comunica a systemd quando è pronto. In questo modo l'ordinamento riflette lo stato reale, invece di basarsi su un'ipotesi. Il servizio può inoltre inviare MAINPID= per indicare a systemd il processo corretto, anziché un processo launcher.
WatchdogSec= è la parte che giustifica il lavoro. Impostandolo, il servizio deve inviare WATCHDOG=1 tramite sd_notify(3) almeno con questa frequenza. Quando i messaggi si interrompono, systemd termina il servizio con SIGABRT e lo contrassegna come non riuscito. Di conseguenza, Restart=on-failure o Restart=on-watchdog lo riavvia. Questo è l'unico meccanismo integrato per riavviare un processo ancora attivo ma bloccato. Nessuna politica basata sul codice di uscita può rilevarlo.
[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/myapp serve
WatchdogSec=30s
Restart=on-failure
RestartSec=5sNel journal, l'attivazione del watchdog appare come myapp.service: Watchdog timeout (limit 30s)!, seguita dalla terminazione del processo. Se invece l'unità rimane in activating (start) finché TimeoutStartSec non scade, READY=1 non è mai arrivato oppure non è stato conteggiato. Il programma potrebbe non supportare il protocollo. In alternativa, NotifyAccess=main potrebbe rifiutare una notifica proveniente da un processo figlio; il journal riporta entrambi i PID. Un altro caso è quello in cui un processo helper invia il messaggio e termina prima che systemd possa determinare da quale unità provenga. Quest'ultimo messaggio viene ignorato anche con NotifyAccess=all. La correzione deve essere apportata al programma: deve chiamare sd_notify_barrier() prima che il processo helper termini.
Per il software che espone un endpoint HTTP di health check ma non supporta sd_notify, le opzioni corrette sono due: usare una piccola unità timer che interroga l'endpoint e chiama systemctl restart, oppure lasciare i controlli a un runtime per container. È questo lo scopo di health check di Compose e relativo comportamento di riavvio.
Correzione tre: un supervisore all'interno dell'unità, solo quando non c'è alternativa
Alcuni software vengono effettivamente distribuiti come un insieme di processi gestiti da un launcher che non può essere suddiviso. In questo caso si esegue un supervisore all'interno dell'unità e se ne accetta la conseguenza: systemd monitora il supervisore, il supervisore monitora tutti gli altri processi e la politica di riavvio viene quindi definita in due file.
Il caso più comune è rappresentato da un runtime per container. Un'unità docker compose o podman segue esattamente questo modello: la politica di riavvio del singolo container è definita nel file Compose, mentre l'unità systemd mantiene in esecuzione soltanto il runtime. Se questo è il tuo caso, l'unità che avvia uno stack Compose all'avvio mostra la configurazione corretta e spiega anche perché Type=oneshot con RemainAfterExit=yes è in genere la scelta appropriata.
Il cgroup continua a essere utile. Tutto ciò che il supervisore avvia rimane nel cgroup dell'unità, quindi MemoryMax=, CPUQuota= e la pulizia eseguita al momento dell'arresto coprono ancora l'intero albero dei processi. Viene delegata soltanto la decisione sul riavvio.
Qualunque supervisore si scelga, non impostare Restart=always sull'unità esterna e una politica di riavvio aggressiva al suo interno senza valutarne le conseguenze. Due livelli di logica di riavvio, ciascuno con il proprio backoff, possono mantenere il servizio in stato di flapping per diversi minuti e produrre un journal che non spiega la causa.
ExitType=cgroup non significa «riavviare quando termina un processo qualsiasi»
ExitType= (systemd 250 e versioni successive, quindi presente sia in Ubuntu 24.04 sia in Debian 12) è l'impostazione che si trova cercando una soluzione a questo problema, ma fa l'opposto di quanto suggerisce il nome. Il valore predefinito, ExitType=main, indica che il servizio viene considerato arrestato quando termina il processo principale. ExitType=cgroup indica invece che il servizio viene considerato in esecuzione finché non termina l'ultimo processo del cgroup.
Di conseguenza, ExitType=cgroup rende un'unità meno sensibile alla terminazione di un singolo processo, non più sensibile. È l'impostazione corretta per un programma che crea un worker effettivo tramite fork e termina il processo padre senza scrivere un file PID, impedendo a Type=forking di individuare il demone. È invece l'impostazione sbagliata per il problema descritto qui.
Non esiste un valore Restart= con il significato di «riavviare l'unità quando termina un processo qualsiasi del cgroup». Se è necessario questo comportamento, occorre usare un processo per unità. Se non è possibile separare il programma e si controlla lo script wrapper, l'alternativa più vicina è wait -n, che restituisce il controllo non appena termina il primo processo figlio:
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait -n
exit 1La terminazione di un processo figlio ora causa l'arresto del wrapper con uno stato diverso da zero, quindi Restart=on-failure interviene. È un compromesso, non una correzione. Si continua ad avere un solo contatore dei riavvii per due programmi, un unico flusso di log e nessuna possibilità di riavviare autonomamente la parte che ha avuto l'errore.
Come verificare che cosa è successo realmente
Quattro comandi, in questo ordine.
systemctl status myapp.service
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Result -p ExecMainStatus myapp.service
journalctl -u myapp.service -b -o short-precisesystemctl status mostra lo stato, il PID principale e l'albero cgroup in un'unica schermata. Un'unità in condizioni normali mostra Active: active (running), con una riga Main PID: che indica il processo previsto. Se l'albero in fondo elenca processi che non riconosci oppure non include un processo che invece ti aspetti, hai già trovato la risposta.
systemd-cgls --unit stampa lo stesso albero senza troncare l'output. Questo diventa importante quando un'unità gestisce più di una manciata di processi.
systemctl show restituisce dati leggibili dalle macchine. NRestarts= è il contatore dei riavvii ed è il modo più rapido per distinguere un servizio che è stato riavviato quaranta volte da uno attivo dall'avvio del sistema. Result= contiene il motivo dell'ultimo errore: exit-code, signal, timeout, oom-kill, watchdog o start-limit-hit. ExecMainStatus= è lo stato di uscita grezzo dell'ultimo processo principale.
Il journal conserva la sequenza degli eventi. Queste sono le tre righe da cercare:
myapp.service: Main process exited, code=exited, status=1/FAILURE
myapp.service: Failed with result 'exit-code'.
myapp.service: Scheduled restart job, restart counter is at 1.code=exited, status=N significa che il programma ha scelto di restituire N, quindi il problema riguarda il programma o la relativa configurazione. code=killed, signal=SEGV significa che il programma è andato in crash. code=killed, signal=TERM indica in genere che un altro componente ha richiesto l'arresto; non è un errore e non attiverà Restart=on-failure. code=dumped significa che il programma ha lasciato un file core, che coredumpctl list mostrerà quando systemd-coredump è installato.
Su più macchine, NRestarts è il valore che conviene raccogliere con una pianificazione. Un'unità il cui contatore aumenta ogni giorno sta fallendo ogni giorno, anche se nessuno se ne è accorto. Quando gestisci più di due o tre server, un metodo coerente per eseguire un comando su ogni server trasforma un'ipotesi in un report.
FAQ
Perché systemctl indica che il servizio è attivo anche se il processo è terminato?
systemd tiene traccia di un processo per ogni unità di servizio, cioè del processo principale, e Restart= legge soltanto il codice di uscita di quel processo. Tutti gli altri processi avviati dall'unità appartengono allo stesso cgroup. systemd termina questi processi quando l'unità si arresta, ma non ne controlla mai l'uscita. Eseguire systemctl show -p MainPID myapp.service e confrontare il numero con systemd-cgls --unit myapp.service. Se il processo terminato compare nell'albero ma non è MainPID, systemd si è comportato esattamente come previsto. La correzione consiste nell'usare un processo per unità e nel definire la relazione tra le unità con BindsTo= e Upholds=.
Che cosa significa "start request repeated too quickly"?
Significa che l'unità è stata avviata più di StartLimitBurst= volte nell'intervallo StartLimitIntervalSec=, che per impostazione predefinita consente 5 avvii in 10 secondi. Per questo systemd ha smesso di tentare l'avvio. Si tratta di un limite di frequenza e non indica mai perché il servizio non riusciva ad avviarsi. Leggere quindi le righe del journal precedenti al messaggio. Cancellare lo stato con systemctl reset-failed myapp.service, quindi correggere il problema sottostante. Se il servizio attende l'avvio di una dipendenza lenta, aumentare RestartSec=. L'intervallo predefinito di 100 millisecondi esaurisce infatti tutti e cinque i tentativi in meno di un secondo.
Devo usare Restart=always o Restart=on-failure?
Usare on-failure nella maggior parte dei casi. Riavvia il servizio dopo un crash, un'uscita con codice diverso da zero, un timeout o l'intervento del watchdog, ma lascia terminare normalmente un exit 0 intenzionale. Usare always soltanto quando il programma termina correttamente per motivi indipendenti dal suo controllo, ad esempio quando un client restituisce 0 dopo la disconnessione del peer. Lo svantaggio di always è che un servizio che legge una configurazione non valida, registra un errore e termina con codice 0 viene riavviato continuamente. Con l'intervallo predefinito fallisce presto con start-limit-hit. Con un RestartSec= più lungo può entrare in un ciclo indefinito, mentre NRestarts aumenta in systemctl show come unico sintomo visibile.
Perché terminare manualmente il mio processo non attiva un riavvio?
Perché, per ogni tipo tranne Type=oneshot, systemd considera SIGHUP, SIGINT, SIGTERM e SIGPIPE come uscite normali, mentre un semplice kill <pid> invia SIGTERM. Con Restart=on-failure, un'uscita normale non è considerata un errore. Di conseguenza non viene eseguito alcun riavvio e la configurazione sembra non funzionare, anche se è corretta. Eseguire il test con kill -9 <pid> o systemctl kill -s SIGKILL myapp.service, che causano una terminazione anomala e attivano la policy. La stessa regola spiega perché systemctl stop non interferisce mai con la policy di riavvio.
Dove devono essere inseriti StartLimitIntervalSec e StartLimitBurst?
Nella sezione [Unit]. La documentazione precedente e le versioni meno recenti di systemd li inserivano in [Service], perciò gli esempi copiati possono essere discordanti. Non dedurre quale sezione venga riconosciuta dalla propria versione. Dopo systemctl daemon-reload, chiedere a systemd quali impostazioni ha caricato con systemctl show -p StartLimitBurst -p StartLimitIntervalUSec myapp.service e considerare questi valori come riferimento. systemd-analyze verify /etc/systemd/system/myapp.service individua le chiavi che systemd non riconosce affatto e non stampa nulla quando il file è corretto.