Dlaczego systemd nie restartuje usługi po awarii
Dyrektywa Restart= monitoruje wyłącznie główny proces jednostki. Awaria procesu potomnego w cgroup nie wyzwala restartu. Dowiedz się, jak Type= i limity wpływają na proces.
Krótka odpowiedź: polityki restartu systemd monitorują jeden proces
Polityki restartu systemd monitorują jeden proces na jednostkę: proces główny. Restart= odczytuje kod wyjścia tego jednego procesu oraz krótkich poleceń, które systemd uruchamia samodzielnie w jego otoczeniu, takich jak ExecStartPre=, ExecStartPost= oraz ExecReload=. Nie odczytuje niczego innego. Grupa kontrolna (cgroup) jednostki może zawierać dwadzieścia procesów; jeden z nich może ulec awarii, a jednostka pozostanie w stanie active (running), ponieważ proces główny nadal istnieje. Z punktu widzenia systemd nie wystąpiła żadna awaria, więc nic nie jest restartowane.
systemd posiada wiedzę o pozostałych procesach. Zamyka je, gdy jednostka jest zatrzymywana, wlicza ich zużycie pamięci do limitów jednostki, nakłada na nie przydziały CPU oraz wyświetla je w systemctl status. Systemd po prostu nigdy nie odczytuje ich kodu wyjścia. Logika restartu oraz cgroup to dwie różne kwestie, a niniejszy przewodnik w dużej mierze dotyczy rozbieżności między nimi.
Zawartość cgroup a logika restartu
Cgroup (control group) to obiekt jądra systemu, który zarządza grupą procesów. Każda jednostka usługi otrzymuje własną grupę, nazwaną zgodnie z nazwą jednostki. Proces nie może opuścić przypisanej grupy. Procesy potomne dziedziczą cgroup po procesie nadrzędnym, a proces bez uprawnień nie może przenieść się do innej grupy. Dzięki temu systemd skutecznie czyści demony wykonujące podwójne forkowanie, czego stare skrypty init nie potrafiły wykonać w sposób niezawodny.
Należy zestawić oba fakty:
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Restart -p RestartUSec myapp.servicesystemd-cgls wyświetla wszystkie procesy w jednostce. MainPID to pojedyncza liczba, którą odczytuje polityka restartu. Jeśli te dwa elementy nie zgadzają się z modelem mentalnym, rozbieżność ta jest błędem. MainPID=0 oznacza, że systemd nie posiada głównego procesu, z którego mógłby odczytać kod zakończenia. System nadal monitoruje cgroup, więc wykrywa moment, w którym znika ostatni proces, jednak do tego czasu logika restartu nie dysponuje kodem zakończenia, na podstawie którego mogłaby podjąć decyzję.
Istnieje jeden istotny wyjątek od zasady głównego procesu. Jeśli mechanizm OOM killer jądra systemu zakończy jakikolwiek proces wewnątrz cgroup jednostki, systemd odnotuje to zdarzenie, ponieważ monitoruje plik memory.events danej grupy. OOMPolicy= decyduje o dalszych krokach, a wartością domyślną jest stop: cała jednostka zostaje zatrzymana, wynik jest rejestrowany jako oom-kill, co jest traktowane jako awaria, więc uruchamiana jest procedura Restart=on-failure. Dziennik systemowy informuje o tym w sposób bezpośredni.
myapp.service: A process of this unit has been killed by the OOM killer.
myapp.service: Failed with result 'oom-kill'.Zatem proces potomny zakończony z powodu braku pamięci powoduje zatrzymanie jednostki, podczas gdy ten sam proces kończący się naruszeniem ochrony pamięci (segmentation fault) – nie. W przypadku ustawiania limitów pamięci dla jednostki, należy zapoznać się z sposobem stosowania MemoryMax oraz CPUQuota do cgroup jednostki przed dostosowaniem polityki restartu, ponieważ te dwie funkcje łączą się właśnie w tym miejscu.
Jak Type= wybiera główny proces
Type= w sekcji [Service] nie dotyczy tylko kolejności uruchamiania. Jest to reguła decydująca o tym, który PID (identyfikator procesu) staje się MainPID, co jest równoznaczne z określeniem, co Restart= jest w stanie monitorować.
Type=simpleto ustawienie domyślne. Proces, który systemd uruchamia przez fork zExecStart=, jest procesem głównym. systemd oznacza jednostkę jako uruchomioną natychmiast, zanim jeszcze sprawdzi, czyexecw ogóle zadziałało. Literówka w ścieżce do pliku binarnego powoduje, że zadanie startowe kończy się sukcesem, a następnieMain process exited, code=exited, status=203/EXECchwilę później.Type=execzachowuje się jaksimple, z tą różnicą, że zadanie startowe czeka, ażexeczakończy się powodzeniem. Zamienia to powyższą literówkę w uczciwy błąd uruchomienia. Wymaga systemd w wersji 240 lub nowszej. Ubuntu 20.04 i nowsze oraz Debian 12 posiadają tę wersję, ale Ubuntu 18.04, wciąż wspierane przez Ubuntu Pro, dostarcza systemd 237 i jej nie posiada. Wszędzie tam, gdzie jest to możliwe, należy preferować to ustawienie zamiastsimple.Type=forkingoczekuje, że proces zExecStart=utworzy proces potomny (fork) działający w tle, a następnie zakończy działanie. systemd czeka na zakończenie procesu nadrzędnego, a następnie szuka właściwego demona. Należy podaćPIDFile=. Bez niegoGuessMainPID=(domyślnie włączone) działa tylko wtedy, gdy w cgroup pozostaje dokładnie jeden proces. Pozostawienie dwóch procesów sprawia, żeMainPIDpozostaje w stanie0.Type=notifyoznacza, że usługa wywołujesd_notify(3)i wysyłaREADY=1, gdy jest gotowa do obsługi ruchu. Może również wysłaćMAINPID=, aby przekazać systemd inny proces do śledzenia. PrzyType=notify,NotifyAccess=jest ustawione namain, chyba że wybrano inaczej, więc powiadomienie wysłane przez proces potomny jest ignorowane, a w dzienniku (journal) widnieje PID, z którego ono pochodzi.Type=oneshotnie posiada trwałego procesu głównego. Jednostka przechodzi w stan nieaktywny, gdy tylkoExecStart=zakończy działanie, chyba że ustawionoRemainAfterExit=yes.Restart=alwaysorazRestart=on-successsą tutaj odrzucane z komunikatemService has Restart= set to either always or on-success, which isn't allowed for Type=oneshot services. Refusing.. Pozostałe wartości, w tymon-failure, są akceptowane.
Warto zapamiętać dwa błędy Type=forking, ponieważ każdy z nich pozostawia jednostkę, która wygląda na uszkodzoną bez widocznej przyczyny:
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.Pierwszy oznacza, że demon zapisuje plik PID w innym miejscu lub zapisuje go później, niż systemd go szuka. Drugi oznacza, że plik PID wskazuje na proces spoza cgroup jednostki, co systemd odmawia zaakceptować, ponieważ zapisywalny plik PID mógłby stać się sposobem na wymuszenie przez systemd wysyłania sygnałów do dowolnego procesu w systemie.
Dlaczego skrypt opakowujący maskuje zakończenie pracy procesów potomnych
Oto schemat, który prowadzi do pytania zawartego w tytule.
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
waitJednostką jest Type=simple, więc głównym procesem jest powłoka. wait bez argumentów kończy działanie dopiero po zakończeniu wszystkich procesów potomnych. Po zabiciu procesu roboczego powłoka nadal oczekuje na proces sieciowy, więc powłoka nie kończy pracy, przez co MainPID nie kończy działania, a Restart= nigdy nie jest sprawdzane. Grupa kontrolna (cgroup) zawiera teraz o jeden proces mniej, systemctl status wypisuje krótsze drzewo, a jednostka nadal ma status active (running). Żaden mechanizm w systemd nie monitoruje zmian w tym drzewie.
Druga wersja tego samego błędu jest mniej oczywista:
ExecStart=/bin/sh -c 'export APP_ENV=production; /usr/local/bin/myapp'Głównym procesem jest powłoka, a nie myapp. W momencie systemctl stop, systemd wysyła sygnał SIGTERM do głównego procesu, a powłoka oczekująca na proces potomny w pierwszym planie nie przekazuje tego sygnału dalej. Zatrzymanie trwa wtedy pełne TimeoutStopSec, domyślnie 90 sekund, i kończy się w następujący sposób:
myapp.service: State 'stop-sigterm' timed out. Killing.
myapp.service: Killing process 4711 (myapp) with signal SIGKILL.Rozwiązaniem jest exec. Należy użyć exec /usr/local/bin/myapp, dzięki czemu powłoka zostanie zastąpiona przez program, a MainPID będzie bezpośrednio tym programem, do którego dotrą sygnały. Jeszcze lepiej jest usunąć powłokę i użyć Environment= lub EnvironmentFile= w jednostce. Należy zauważyć, że ten błąd jest maskowany, gdy ciąg -c zawiera tylko jedno polecenie, ponieważ zarówno bash, jak i dash optymalizują ten przypadek do bezpośredniego exec. Dodanie drugiego polecenia do ciągu sprawia, że powłoka pozostaje aktywna przed uruchomionym programem.
Odtworzenie problemu na testowym VPS w dwie minuty
Zapisz powyższy skrypt opakowujący jako /usr/local/bin/two-children.sh, nadaj mu uprawnienia do wykonywania za pomocą chmod +x i zastąp dwie ścieżki programów za pomocą sleep 3600. Wskaż jednostkę na ten plik za pomocą Type=simple i Restart=on-failure, a następnie wykonaj systemctl daemon-reload i uruchom ją. Uruchom systemd-cgls --unit two-children.service i zanotuj trzy identyfikatory PID: powłokę oraz jej dwa procesy potomne. Zabij jeden proces potomny za pomocą sudo kill <pid>. Sprawdź ponownie jednostkę. Drzewo jest krótsze o jeden proces, stan to nadal active (running), a w dzienniku nie ma żadnych nowych wpisów. Teraz uruchom zamiast tego sudo kill -9 <shell pid>. Jednostka zgłasza błąd, pozostały proces potomny zostaje usunięty, ponieważ KillMode=control-group jest wartością domyślną, a dziennik pokazuje Scheduled restart job, restart counter is at 1.
Pełny słownik Restart= oraz sytuacje, w których on-failure jest lepsze niż always
Restart= przyjmuje jedną z siedmiu wartości, a kluczowe znaczenie ma definicja poprawnego zakończenia pracy. systemd traktuje kod wyjścia 0, każdy kod wymieniony w SuccessExitStatus= oraz – dla każdego typu poza Type=oneshot – sygnały SIGHUP, SIGINT, SIGTERM i SIGPIPE jako poprawne zakończenie. Wszystko inne, w tym SIGKILL i SIGSEGV, jest uznawane za niepoprawne.
noto wartość domyślna. Jednostka nigdy nie restartuje się automatycznie, dlatego jednostka bez liniiRestart=kończy działanie przy pierwszej awarii i pozostaje wyłączona.on-successrestartuje tylko po poprawnym zakończeniu pracy.on-failurerestartuje w przypadku kodu wyjścia innego niż zero, niepoprawnego sygnału, przekroczenia limitu czasu startu lub stopu albo wygaśnięcia watchdog.on-abnormalrestartuje w przypadku niepoprawnego sygnału, przekroczenia limitu czasu lub wygaśnięcia watchdog, ale nigdy w przypadku zwykłego kodu wyjścia innego niż zero.on-abortrestartuje tylko w przypadku niepoprawnego sygnału, co oznacza awarię.on-watchdogrestartuje tylko wtedy, gdy wygaśnieWatchdogSec=.alwaysrestartuje po każdym z powyższych przypadków, w tym po poprawnym zakończeniu z kodem 0.
on-failure jest właściwym ustawieniem domyślnym dla długo działającego demona. Przywraca działanie po awarii i pozostawia w spokoju proces, który zakończył się celowo exit 0. always jest przeznaczone dla programu, który kończy pracę poprawnie z przyczyn od niego niezależnych, na przykład klienta tunelu, który zwraca 0, gdy zdalny koniec rozłącza połączenie. Kosztem always jest ukrywanie błędów: usługa, która startuje, odczytuje uszkodzony plik konfiguracyjny, loguje błąd i kończy pracę z kodem 0, jest po prostu uruchamiana ponownie. Przy domyślnym odstępie 100 milisekund szybko osiąga limit częstotliwości startów opisany poniżej i kończy działanie ze statusem start-limit-hit. Przy RestartSec= wystarczająco długim, aby nie przekroczyć tego limitu, usługa zapętla się w nieskończoność, a jedynym objawem jest rosnący licznik restartów.
SuccessExitStatus= przesuwa granicę między poprawnym a niepoprawnym zakończeniem. Borg zwraca 1 dla ostrzeżeń i 2 dla błędów, więc jednostka kopii zapasowej bez SuccessExitStatus=1 jest oznaczana jako nieudana za każdym razem, gdy pominie jeden nieczytelny plik. RestartPreventExitStatus= wymienia kody, które blokują restart nawet w przypadku always, co jest poprawnym sposobem na poinformowanie programu, że nie powinien wracać. RestartForceExitStatus= działa odwrotnie. Zadanie kopii zapasowej powinno znajdować się w jednostce Type=oneshot sterowanej przez timer, a nie w pętli restartów; para usługi i timera uruchamiająca zadanie według harmonogramu to wzorzec, który należy tu skopiować.
Jedno ostrzeżenie dotyczące testowania. Zabicie usługi za pomocą zwykłego kill <pid> wysyła sygnał SIGTERM, który znajduje się na liście poprawnych zakończeń, więc Restart=on-failure słusznie nie podejmuje żadnych działań, a użytkownik może błędnie wywnioskować, że konfiguracja jest uszkodzona. Zamiast tego należy użyć kill -9 <pid> lub systemctl kill -s SIGKILL myapp.service. Należy również pamiętać, że żadna wartość Restart= nie zadziała po systemctl stop lub gdy jednostka została zatrzymana, ponieważ zależność BindsTo= lub PartOf= przestała istnieć. Zadanie zatrzymania nie jest awarią.
RestartSec oraz domyślne 100 milisekund
RestartSec= to pauza między zatrzymaniem jednostki a jej ponownym uruchomieniem przez systemd, a wartość domyślna wynosi 100 milisekund. Sprawdź, co faktycznie wczytała Twoja jednostka:
systemctl show -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst myapp.serviceJednostka, w której nie ustawiono tej wartości, wyświetla RestartUSec=100ms, chyba że ktoś zmienił DefaultRestartSec= w /etc/systemd/system.conf, skąd pochodzi nieustawiona wartość. To ustawienie domyślne jest odpowiednie dla usługi, która ulega awarii raz i wraca do działania. Jest ono błędne dla usługi, która w ogóle nie może wystartować, ponieważ pierwsze uruchomienie i cztery restarty mieszczą się w czasie poniżej sekundy w przypadku programu, który natychmiast kończy działanie, co wyczerpuje pięć startów dozwolonych przez limit częstotliwości opisany poniżej. Dla wszystkiego, co oczekuje na bazę danych, punkt montowania lub trasę sieciową, ustaw RestartSec=5s lub więcej.
Od października 2026 roku systemd 254 i nowsze oferują również RestartSteps= oraz RestartMaxDelaySec=, które zwiększają opóźnienie z RestartSec= do wartości maksymalnej w trakcie określonej liczby prób. Ubuntu 24.04 zawiera systemd 255 i posiada te funkcje. Debian 12 zawiera systemd 252 i ich nie posiada, chociaż bookworm-backports oferuje systemd 254. Rosnące opóźnienia są właściwym rozwiązaniem, gdy zależność może być niedostępna przez dłuższy czas.
Co w rzeczywistości oznacza komunikat "start request repeated too quickly"
Jest to stan, w którym systemd przestaje podejmować próby uruchomienia usługi. Mechanizm opiera się na liczniku. Zasada jest następująca: jeśli jednostka zostanie uruchomiona więcej niż StartLimitBurst= razy w ciągu StartLimitIntervalSec=, systemd odmawia kolejnego startu i przełącza ją w stan awarii. Domyślne ustawienia to 5 uruchomień w ciągu 10 sekund.
Dziennik zdarzeń pokazuje następującą sekwencję:
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.a systemctl start zawiera odpowiedź z gotowym rozwiązaniem:
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 zeruje licznik i czyści stan awarii. Bez tego polecenia zwykłe systemctl start będzie odrzucane, dopóki nie upłynie okno czasowe StartLimitIntervalSec=, a automatyczne restarty pozostaną wyłączone, dopóki ktoś ręcznie nie uruchomi jednostki ponownie. Ręczne uruchomienia również wliczają się do limitu, więc kilka niecierpliwych wywołań systemctl restart w trakcie edycji pliku konfiguracyjnego może wywołać ten stan bez faktycznej awarii aplikacji.
Elementem wprowadzającym w błąd jest to, że start-limit-hit nigdy nie informuje, dlaczego usługa zawiodła. Komunikat wskazuje jedynie, że usługa zawiodła wielokrotnie i w krótkim czasie. Rzeczywista przyczyna znajduje się w liniach dziennika znajdujących się powyżej.
Oba ustawienia powinny znajdować się w sekcji [Unit]. Można natrafić na przykłady umieszczające je w [Service], co starsze wersje systemd akceptowały, co jest źródłem zamieszania. Należy umieszczać je w [Unit], a następnie sprawdzić, co załadował systemd za pomocą systemctl show, ponieważ tylko załadowana wartość jest wiążąca.
[Unit]
Description=My application
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=exec
ExecStart=/usr/local/bin/myapp
Restart=on-failure
RestartSec=10sPowyższa konfiguracja pozwala jednostce na pięć prób w ciągu pięciu minut, zanim systemd zrezygnuje. StartLimitIntervalSec=0 całkowicie wyłącza limit. Należy mieć świadomość konsekwencji: usługa, która nie może wystartować, będzie ponawiać próby w nieskończoność, zapisując wpisy w dzienniku przy każdej z nich. Domyślne ustawienia dla całego systemu znajdują się w /etc/systemd/system.conf jako DefaultStartLimitIntervalSec= oraz DefaultStartLimitBurst=.
Jedno z powiązanych ustawień wymaga ostrzeżenia. StartLimitAction= decyduje o tym, co stanie się po osiągnięciu limitu. Akceptuje ono wartości takie jak reboot, reboot-force oraz poweroff. Wartością domyślną jest none, która oznacza przejście jednostki w stan awarii bez ingerencji w działanie maszyny. W przypadku zdalnego serwera VPS, ustawienie poweroff oznacza, że maszyna pozostanie wyłączona do momentu interwencji przez konsolę dostawcy.
Rozwiązanie pierwsze: jeden proces na jednostkę
Jest to odpowiedź w niemal każdym przypadku. Jeśli muszą działać dwa programy, należy utworzyć dwie jednostki. Każda z nich posiada wtedy rzeczywisty proces główny, rzeczywisty status zakończenia oraz własną politykę restartu. Otrzymuje się również oddzielne logi, oddzielne limity zasobów oraz oddzielne liczniki restartów, co jest pożądane o trzeciej nad ranem.
Relacje między jednostkami należy wyrazić w plikach jednostek, a nie w skrypcie powłoki.
After=określa tylko kolejność uruchamiania. Nie mówi nic o awariach.Requires=uruchamia drugą jednostkę wraz z tą pierwszą i zatrzymuje tę pierwszą, jeśli druga zostanie jawnie zatrzymana.BindsTo=toRequires=oraz przypadek, który jest istotny: ta jednostka zatrzymuje się, gdy druga zatrzyma się z jakiegokolwiek powodu, w tym z powodu awarii. Należy połączyć to zAfter=, w przeciwnym razie kolejność będzie niezdefiniowana.PartOf=propaguje zatrzymanie i restart w dół, więcsystemctl restart myapp.targetdociera do każdej jednostki, która jestPartOf=względem niej.Upholds=(systemd 249 i nowsze, czyli Ubuntu 22.04 i późniejsze) utrzymuje wskazaną jednostkę w stanie uruchomionym: jeśli się zatrzyma, systemd uruchamia ją ponownie. Podlega ona temu samemu limitowi częstotliwości uruchamiania co wszystko inne.
Proces roboczy, który nigdy nie może działać bez swojego serwera API i który systemd utrzymuje przy życiu, gdy API działa:
# /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=5sProces roboczy nie posiada sekcji [Install] i nigdy nie jest włączany ręcznie. Jednostka API pobiera go za pomocą Upholds=, więc systemctl enable --now myapp-api.service jest jedynym poleceniem, które należy wykonać. Przeładuj i sprawdź, jak systemd zinterpretował tę parę:
sudo systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp-worker.service
systemctl list-dependencies myapp-api.servicesystemd-analyze verify nie wyświetla niczego, gdy plik jest poprawny. Każdy komunikat wyjściowy oznacza problem, zazwyczaj klucz, którego systemd nie rozpoznaje w sekcji, w której został umieszczony, lub zależność od jednostki, która nie istnieje.
Poprawka druga: Type=notify, czyli systemd wie więcej niż tylko PID
Jeśli program obsługuje protokół powiadomień systemd, należy go użyć. Dzięki Type=notify usługa informuje systemd o gotowości, co sprawia, że kolejność uruchamiania jest rzeczywista, a nie oparta na założeniach. Można również wysłać MAINPID=, aby wskazać systemd właściwy proces, zamiast polegać na procesie uruchamiającym.
WatchdogSec= to element warty wysiłku. Po jego ustawieniu usługa musi wysyłać WATCHDOG=1 przez sd_notify(3) co najmniej tak często. Gdy komunikaty przestaną docierać, systemd kończy działanie usługi za pomocą SIGABRT i oznacza ją jako nieudaną, dzięki czemu Restart=on-failure lub Restart=on-watchdog przywracają ją do działania. Jest to jedyny wbudowany sposób na restart procesu, który działa, ale zawiesił się, czego nie wykryje żadna polityka oparta na kodzie wyjścia.
[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/myapp serve
WatchdogSec=30s
Restart=on-failure
RestartSec=5sZadziałanie mechanizmu watchdog jest widoczne w dzienniku jako myapp.service: Watchdog timeout (limit 30s)!, po którym następuje przerwanie procesu. Jeśli jednostka pozostaje w stanie activating (start) do momentu upłynięcia TimeoutStartSec, oznacza to, że READY=1 nigdy nie dotarło lub nie zostało naliczone. Przyczyną jest brak obsługi protokołu przez program, odrzucenie powiadomienia przez NotifyAccess=main z powodu pochodzenia od procesu potomnego (co dziennik raportuje z użyciem obu PID-ów) lub sytuacja, w której proces pomocniczy wysłał komunikat i zakończył działanie, zanim systemd zdążył przypisać go do jednostki. Ten ostatni komunikat jest ignorowany nawet przy NotifyAccess=all, a poprawka musi zostać wprowadzona w kodzie programu: powinien on wywołać sd_notify_barrier() przed zakończeniem procesu pomocniczego.
W przypadku oprogramowania udostępniającego punkt końcowy stanu zdrowia HTTP, ale nieposiadającego wsparcia dla sd_notify, uczciwymi rozwiązaniami są: mała jednostka typu timer, która sonduje punkt końcowy i wywołuje systemctl restart, lub powierzenie sondowania środowisku uruchomieniowemu kontenerów, do czego służy Compose healthchecks and their restart behaviour.
Rozwiązanie trzecie: nadzorca wewnątrz jednostki, tylko w ostateczności
Niektóre oprogramowanie jest dostarczane jako pakiet procesów uruchamianych przez launcher, którego nie można rozdzielić. W takim przypadku należy uruchomić nadzorcę wewnątrz jednostki i zaakceptować konsekwencje: systemd monitoruje nadzorcę, nadzorca monitoruje resztę, a polityka restartu jest zdefiniowana w dwóch różnych plikach.
Typowym przykładem jest środowisko uruchomieniowe kontenerów. Jednostka docker compose lub podman realizuje dokładnie ten wzorzec, gdzie polityka restartu dla poszczególnych kontenerów jest określona w pliku Compose, a jednostka systemd odpowiada jedynie za utrzymanie działania środowiska uruchomieniowego. Jeśli taka jest struktura systemu, jednostka uruchamiająca stos Compose podczas startu przedstawia działającą wersję, wyjaśniając również, dlaczego Type=oneshot z RemainAfterExit=yes jest tam zazwyczaj właściwym wyborem.
Grupy kontrolne (cgroups) nadal działają na korzyść administratora. Wszystkie procesy uruchomione przez nadzorcę pozostają wewnątrz cgroup jednostki, więc MemoryMax=, CPUQuota= oraz czyszczenie zasobów podczas zatrzymywania nadal obejmują całe drzewo procesów. Delegowana jest jedynie decyzja o restarcie.
Niezależnie od wybranego nadzorcy, nie należy bez przemyślenia ustawiać Restart=always dla jednostki zewnętrznej przy jednoczesnym stosowaniu agresywnej polityki restartu wewnątrz niej. Dwie warstwy logiki restartu, z których każda posiada własny mechanizm opóźnień (backoff), prowadzą do niestabilnej pracy usługi przez wiele minut oraz dziennika zdarzeń, który nie wyjaśnia przyczyny problemu.
ExitType=cgroup nie oznacza "restartuj, gdy zginie dowolny proces"
ExitType= (systemd 250 i nowsze, dostępne w Ubuntu 24.04 oraz Debian 12) to ustawienie, które użytkownicy znajdują podczas szukania rozwiązania tego problemu, a działa ono odwrotnie, niż sugeruje nazwa. Wartość domyślna, ExitType=main, oznacza, że usługa jest uznawana za zatrzymaną, gdy kończy się proces główny. ExitType=cgroup oznacza, że usługa jest uznawana za działającą, dopóki nie zakończy się ostatni proces w cgroup.
Zatem ExitType=cgroup sprawia, że jednostka jest mniej, a nie bardziej wrażliwa na śmierć pojedynczego procesu. Jest to właściwe ustawienie dla programu, który uruchamia proces potomny (fork) i kończy proces nadrzędny bez zapisywania pliku PID, przez co Type=forking nie może odnaleźć demona. Jest to błędne ustawienie dla opisanego tutaj przypadku awarii.
Nie istnieje wartość Restart= oznaczająca "restartuj jednostkę, gdy zginie dowolny proces w cgroup". Jeśli wymagane jest takie zachowanie, należy przypisać jeden proces do jednej jednostki. Jeśli nie można rozdzielić programu, a użytkownik zarządza skryptem opakowującym (wrapper), najbliższym rozwiązaniem jest wait -n, który kończy działanie natychmiast po wyjściu pierwszego procesu potomnego:
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait -n
exit 1Śmierć dowolnego procesu potomnego powoduje teraz zakończenie skryptu opakowującego z niezerowym statusem, dzięki czemu Restart=on-failure podejmuje działanie. Jest to kompromis, a nie poprawka. Nadal występuje jeden licznik restartów dla dwóch programów, jeden strumień logów oraz brak możliwości zrestartowania tylko tej części, która uległa awarii.
Jak sprawdzić, co faktycznie się wydarzyło
Cztery polecenia, w tej kolejności.
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 wyświetla stan, główny PID oraz drzewo cgroup na jednym ekranie. Poprawnie działająca jednostka ma stan Active: active (running) z linią Main PID: wskazującą na oczekiwany proces. Jeśli drzewo na dole zawiera nierozpoznane procesy lub brakuje w nim tych oczekiwanych, przyczyna problemu jest już znana.
systemd-cgls --unit wyświetla to samo drzewo bez skracania, co staje się istotne, gdy jednostka zarządza większą liczbą procesów.
systemctl show dostarcza dane w formacie czytelnym dla maszyny. NRestarts= to licznik restartów; jest to najszybszy sposób na odróżnienie usługi, która zrestartowała się czterdzieści razy, od tej, która działa od momentu uruchomienia systemu. Result= zawiera przyczynę ostatniej awarii: exit-code, signal, timeout, oom-kill, watchdog lub start-limit-hit. ExecMainStatus= to surowy kod wyjścia ostatniego głównego procesu.
Dziennik zdarzeń przechowuje sekwencję działań. Oto trzy linie, których należy szukać:
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 oznacza, że program zwrócił kod N, więc błąd leży po stronie programu lub jego konfiguracji. code=killed, signal=SEGV oznacza awarię (crash). code=killed, signal=TERM zazwyczaj oznacza, że inny proces wymusił zatrzymanie, co nie jest błędem i nie wywoła Restart=on-failure. code=dumped oznacza, że utworzono plik zrzutu pamięci (core file), który coredumpctl list wyświetli, jeśli zainstalowano systemd-coredump.
W przypadku wielu maszyn, NRestarts to wartość, którą warto zbierać według harmonogramu. Jednostka, której licznik rośnie każdego dnia, ulega awarii codziennie, niezależnie od tego, czy ktoś to zauważył. Gdy zarządzasz więcej niż dwoma lub trzema serwerami, spójny sposób na uruchomienie polecenia na każdym serwerze pozwala zamienić domysły w raport.
FAQ
Dlaczego systemctl twierdzi, że usługa jest aktywna, mimo że proces zakończył działanie?
systemd śledzi jeden proces na jednostkę usługi, czyli proces główny, a Restart= odczytuje status zakończenia tylko tego procesu. Wszystkie pozostałe procesy uruchomione przez jednostkę znajdują się w tej samej grupie kontrolnej (cgroup) i systemd zakończy je podczas zatrzymywania jednostki, ale nie monitoruje ich pod kątem zakończenia pracy. Uruchom systemctl show -p MainPID myapp.service i porównaj wynik z systemd-cgls --unit myapp.service. Jeśli proces, który zakończył działanie, widnieje w drzewie, ale nie jest MainPID, systemd zachował się zgodnie z projektem. Rozwiązaniem jest przypisanie jednego procesu do jednej jednostki oraz zdefiniowanie relacji między jednostkami za pomocą BindsTo= i Upholds=.
Co oznacza komunikat "start request repeated too quickly"?
Oznacza to, że jednostka była uruchamiana więcej niż StartLimitBurst= razy w ciągu StartLimitIntervalSec=, co domyślnie wynosi 5 prób w 10 sekund, więc systemd zaprzestał dalszych prób. Jest to limit częstotliwości, który nie informuje o przyczynie awarii usługi, dlatego należy sprawdzić wpisy w dzienniku powyżej tego komunikatu. Wyczyść stan za pomocą systemctl reset-failed myapp.service, a następnie usuń przyczynę awarii. Jeśli usługa oczekuje na powolne uruchomienie zasobu, zwiększ RestartSec=, ponieważ domyślny odstęp 100 milisekund wyczerpuje limit pięciu prób w czasie krótszym niż sekunda.
Czy używać Restart=always czy Restart=on-failure?
W większości przypadków należy używać on-failure. Restartuje ono usługę w przypadku awarii, wyjścia z kodem innym niż zero, przekroczenia limitu czasu oraz wyzwolenia mechanizmu watchdog, pozostawiając celowe exit 0 bez zmian. Używaj always tylko wtedy, gdy program kończy pracę w sposób prawidłowy z przyczyn niezależnych od niego, na przykład gdy klient zwraca 0 po rozłączeniu się z drugą stroną. Kosztem always jest to, że usługa odczytująca błędną konfigurację, logująca jeden błąd i kończąca pracę z kodem 0, będzie uruchamiana ponownie. Przy domyślnym odstępie szybko wystąpi błąd start-limit-hit, a przy dłuższym RestartSec= usługa może zapętlić się w nieskończoność, gdzie jedynym widocznym objawem będzie wzrost NRestarts w systemctl show.
Dlaczego ręczne zabicie procesu nie wyzwala restartu?
Ponieważ dla każdego typu poza Type=oneshot, systemd traktuje sygnały SIGHUP, SIGINT, SIGTERM oraz SIGPIPE jako poprawne zakończenie pracy, a zwykłe kill <pid> wysyła sygnał SIGTERM. W ramach Restart=on-failure poprawne zakończenie nie jest traktowane jako awaria, więc usługa nie jest restartowana, co sprawia wrażenie błędnej konfiguracji, mimo że taka nie jest. Testuj za pomocą kill -9 <pid> lub systemctl kill -s SIGKILL myapp.service, co stanowi niepoprawne zakończenie i wyzwala politykę restartu. Ta sama zasada wyjaśnia, dlaczego systemctl stop nie koliduje z polityką restartu.
Gdzie umieścić StartLimitIntervalSec oraz StartLimitBurst?
W sekcji [Unit]. Starsze materiały i starsze wersje systemd umieszczały je w [Service], dlatego skopiowane przykłady są ze sobą sprzeczne. Nie zgaduj, którą sekcję obsługuje Twoja wersja. Po wykonaniu systemctl daemon-reload sprawdź, co załadował systemd za pomocą systemctl show -p StartLimitBurst -p StartLimitIntervalUSec myapp.service i traktuj te wartości jako wiążące. systemd-analyze verify /etc/systemd/system/myapp.service wykrywa klucze, których systemd nie rozpoznaje, i nie wyświetla niczego, gdy plik jest poprawny.