Kennisbank / systemd troubleshooting

systemd troubleshooting: services, dependencies en restart-beleid

Auteur: DEWOLF.IT

Bij systemd troubleshooting is de melding ‘failed’ het begin van de diagnose. De oorzaak kan in de applicatie liggen, maar ook in het serviceaccount, een mount, een verkeerde unit of een dependency. Eerst bewijs verzamelen maakt een restart een gerichte handeling.

Scope: RHEL 8/9 systemd; gebruik de lokaal geïnstalleerde manpages voor ondersteunde opties.

Toepassing. systemd op RHEL 8/9. De voorbeeldunit betreft een fictieve, langlopende applicatie die in de voorgrond draait. Pas account, binary, paths en timeouts aan jouw service aan.

Probleem en achtergrond: start, readiness en gezondheid verschillen

‘Active’ betekent niet automatisch dat een applicatie bruikbaar is. Een proces kan draaien maar geen databaseverbinding hebben. Omgekeerd kan een service zijn gestopt omdat de unit fout is, ook al werkt de binary wanneer een beheerder hem handmatig start. Scheid daarom unitstatus, processtatus en functionele gezondheid.

Leg eerst het incidentvenster vast: wanneer werkte de functie voor het laatst, wat is veranderd en welke afhankelijkheid is betrokken? Verzamel bewijs vóór een restart. Anders verdwijnen processtatus, tijdelijke bestanden of de omstandigheden die de fout veroorzaakten.

1. Lees de effectieve unit en de eerste fout

sudo systemctl status example-app.service --no-pager -l
sudo systemctl cat example-app.service
sudo systemctl show example-app.service -p Result -p ExecMainCode -p ExecMainStatus -p FragmentPath -p DropInPaths
sudo journalctl -u example-app.service -b --no-pager -n 200
sudo journalctl -u example-app.service --since '30 minutes ago' -o short-iso --no-pager

systemctl cat toont de basisunit en drop-ins; show geeft properties van de geladen unit. Controleer of de fout uit ExecStartPre, de hoofdapplicatie of een timeout komt. Kijk in het journal naar de eerste fout vóór de reeks restarts. De laatste regel ‘start request repeated too quickly’ kan slechts het gevolg van de echte fout zijn.

De Red Hat systemd-gids behandelt status en servicemanagement. Voor logselectie en bootfilters kun je daarnaast de journalctl-handleiding raadplegen.

2. Controleer de uitvoercontext

Vergelijk de servicecontext met je interactieve shell: User, Group, WorkingDirectory, EnvironmentFile, PATH en beschikbare mounts. Gebruik absolute paden voor binaries en controleer toegang tot parent directories. Een service krijgt niet vanzelf het shellprofiel of de credentials van de beheerder.

sudo systemctl show example-app.service -p User -p Group -p WorkingDirectory -p EnvironmentFiles
namei -l /opt/example/bin/server
findmnt /srv/example-data
sudo journalctl -b -p warning --no-pager

namei laat rechten op padcomponenten zien. Een permission denied kan afkomstig zijn van Unix-rechten, SELinux of unit-sandboxing. Een fout over een ontbrekend bestand kan ook betekenen dat een mount nog niet beschikbaar is. Verifieer iedere hypothese met de bijbehorende laag; voeg niet tegelijk rechten, policy en dependencies toe.

3. Gebruik dependencies voor hun eigen betekenis

After bepaalt volgorde als beide units deelnemen aan de transactie; het start de andere unit niet. Wants trekt een dependency in zonder dezelfde harde vereiste als Requires. Ook een gestarte dependency is geen garantie dat een externe applicatiefunctie klaar is. Zie de upstream unitdocumentatie.

network-online.target is een synchronisatiemoment tijdens startup met een passende wait-online-service. Het is geen doorlopende bewaking van een database of een externe API. Bouw waar nodig begrensde retries en foutmelding in de applicatie. Voor een noodzakelijke mount kan RequiresMountsFor de benodigde mountdependencies vastleggen; test het bootgedrag in de echte storageketen.

4. Ontwerp een begrensd restart-beleid

# /etc/systemd/system/example-app.service
[Unit]
Description=Example application
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/srv/example-data
StartLimitIntervalSec=300
StartLimitBurst=5

[Service]
Type=simple
User=exampleapp
Group=exampleapp
WorkingDirectory=/srv/example-data
ExecStart=/opt/example/bin/server
Restart=on-failure
RestartSec=10s
TimeoutStopSec=60s

[Install]
WantedBy=multi-user.target

Dit is een sjabloon: account, executable en opslag moeten bestaan. Type=simple past bij een proces dat niet daemoniseert. Bij een applicatie die systemd-readinessmelding ondersteunt kan Type=notify geschikter zijn; kies dat niet zonder applicatieondersteuning. Restart=on-failure herstart bij fouten volgens de servicecriteria, maar niet na een expliciete systemctl stop. Raadpleeg de upstream servicedocumentatie.

De startlimieten begrenzen een lus, geen totaal aantal starts over de hele levensduur. Een permanent foute configuratie wordt niet gezond door sneller te herstarten. Koppel een failed-status en de applicatiehealthcheck aan monitoring, zodat de begrenzing een zichtbaar incident oplevert.

5. Pas wijzigingen toe en verifieer het resultaat

Wijzig pakketgeleverde units onder /usr/lib niet rechtstreeks. Gebruik een eigen unit of een drop-in onder /etc. Controleer de unit voordat je de geladen configuratie vervangt. Een daemon-reload herleest unitbestanden; het herstart de applicatie niet en leest ook niet automatisch haar configuratie opnieuw.

sudo systemd-analyze verify /etc/systemd/system/example-app.service
sudo systemctl daemon-reload
sudo systemctl reset-failed example-app.service
sudo systemctl restart example-app.service
sudo systemctl status example-app.service --no-pager -l

De reset-failed en restart horen pas na correctie en binnen het toegestane wijzigingsvenster. Test een functionele request, stop/start en het afgesproken rebootscenario. Controleer ook hoe lang de applicatie nodig heeft om een transactie netjes af te ronden. Een te korte stoptimeout kan werk afbreken.

Enterprise-aandachtspunten en valkuilen

Bewaar de oorspronkelijke unit/drop-in en een terugdraai-instructie. Versioneer de configuratie en leg de reden voor restart- en dependencykeuzes vast. Het activeren bij boot en het nu starten zijn verschillende acties; controleer beide als ze in de beheerafspraak staan.

Zet secrets niet rechtstreeks in een openbaar leesbare unit of in procesargumenten. Stem logretentie af op de tijd die je nodig hebt om incidenten te onderzoeken. Structurele betrouwbaarheid vraagt tenslotte een functionele healthcheck: alleen ‘service running’ mist storingen achter een nog levend proces.

Bronnen en versiecontrole

Technische referenties geraadpleegd op 30 september 2026. Controleer bij uitvoering de documentatie en manpages van de geïnstalleerde versie.

RHEL — systemd beheren
journalctl
Upstream systemd.unit
Upstream systemd.service
RHEL — netwerk-targets

Gerelateerde artikelen

SELinux AVC-denials oplossen: contexts, booleans en policy
Podman in beheer: rootless containers, Quadlet en Docker-migratie
Linux performance: CPU, geheugen en I/O systematisch onderzoeken

Ondersteuning bij jouw platform

Wil je deze aanpak vertalen naar jouw omgeving? Bekijk Linux Consultancy of neem contact op met DEWOLF.IT.