systemd: Start request repeated too quickly

안녕하세요, BlueByte입니다. 스스로 재시작하던 서비스가 내려간 채로 남고, systemctl status에는 failed가, 저널에는 Start request repeated too quickly가 찍히는 경우가 있습니다. 이 줄은 systemd의 시작 속도 제한이지 진짜 실패가 아닙니다. 서비스가 연달아 여러 번 죽었고 systemd가 재시도를 멈춘 것입니다. 오늘은 이 제한이 무엇을 세는지, 그 아래 숨은 크래시를 찾는 법, 원인별 해결, 그리고 예방까지 하나씩 짚어보겠습니다.

제한에 걸렸을 때 저널과 systemctl이 보여주는 것

systemd 255(Ubuntu 24.04)에서 프로그램이 1로 종료하고 Restart=on-failure인 유닛으로 재현한 저널입니다:

myapp.service: Scheduled restart job, restart counter is at 5.
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'exit-code'.
Failed to start myapp.service - My App.

systemctl start의 문구는 systemd가 기록한 결과(result)에 따라 달라집니다. 결과가 start-limit-hit이면 다음 문구와 함께 reset-failed를 쓰라는 안내가 나옵니다:

Job for myapp.service failed because start of the service was attempted too often.

제 255 테스트에서는 유닛이 처음 결과인 exit-code를 유지해서 systemctl start가 대신 the control process exited with error code라고 했습니다. 현재 systemd 소스는 여기서 start-limit-hit을 기록하므로, 어떤 문구가 보일지는 버전에 따라 다릅니다. 메시지 하나를 믿기보다 저널에서 repeated too quickly를 검색하세요.

systemd가 재시도를 멈추는 이유

모든 유닛에는 시작 제한이 있습니다. StartLimitIntervalSec= 안에 StartLimitBurst=번보다 많이 시작하면 이후 시작은 거부됩니다. 둘 다 [Unit] 섹션에 두며 기본값은 10초와 5회입니다. systemd.service 매뉴얼은 Restart=도 같은 제한을 받는다고 명시하고, RestartSec=의 기본값은 100ms입니다. 그래서 시작하자마자 죽는 프로그램은 1초도 안 되어 다섯 번을 소진하고, systemd는 포기합니다. 무한 루프를 막는 장치이지 버그가 아닙니다.

원인은 세 갈래입니다:

• 프로그램 자체가 매번 실패합니다: 잘못된 설정, 없는 파일, 사용 중인 포트, 틀린 권한.
• 필요한 것(데이터베이스, 마운트, 네트워크)이 아직 준비되지 않아 잠깐 실패하는데, 100ms 간격으로는 준비될 틈이 없습니다.
• 외부의 무언가가 계속 재시작합니다. Restart=든, 사람이든, 배포 스크립트든 시작은 모두 셉니다.

먼저 속도 제한 아래의 크래시 찾기

외울 필요는 없습니다. 세 명령이면 원인이 갈립니다:

systemctl show myapp -p Result -p NRestarts -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst
journalctl -u myapp -b --no-pager | grep -v 'Scheduled restart' | tail -n 30
systemctl cat myapp

제 테스트는 NRestarts=5, StartLimitIntervalUSec=10s, StartLimitBurst=5를 출력했습니다. 중요한 건 repeated too quickly 위쪽 저널 줄입니다. 프로그램 자체의 오류이거나, ExecStart= 바이너리를 아예 실행하지 못했다는 status=203/EXEC입니다. 시작 사이에 크래시가 없다면 누가 계속 재시작하는지 찾아보세요.

원인별 해결

매번 실패하는 프로그램이라면 오류를 고친 뒤 카운터를 비우고 다시 시작합니다. reset-failed는 카운터만 비울 뿐 그것만으로는 아무것도 바꾸지 않습니다:

sudo systemctl reset-failed myapp
sudo systemctl start myapp
systemctl is-active myapp
# active

아직 준비되지 않은 의존성이 원인이라면 벤더 유닛을 고치지 말고 drop-in으로 재시작 간격을 벌립니다:

sudo systemctl edit myapp

[Service]
Restart=on-failure
RestartSec=5s

어림 규칙은 이렇습니다. RestartSec × StartLimitBurst가 StartLimitIntervalSec보다 길면 재시작만으로는 제한에 걸릴 수 없습니다. 테스트 유닛에 RestartSec=3s를 주었더니 14초 뒤에도 NRestarts=4, SubState=auto-restart로 — failed가 아니라 계속 재시도 중이었습니다. systemd 254 이상에서는 RestartSteps=와 RestartMaxDelaySec=로 고정 지연 대신 점점 늘어나는 back-off를 줄 수 있습니다.

외부 재시작이 원인이라면 스크립트나 타이머를 고치세요. StartLimitBurst=를 올리면 가려질 뿐입니다.

따라 해 보기: PostgreSQL보다 먼저 뜨는 API

API 유닛이 부팅 때 시작해 PostgreSQL에 닿지 못하고 connection refused를 남기고 종료합니다. 100ms 간격 재시작 다섯 번이 데이터베이스가 연결을 받기 전에 끝나 버리고, API는 누군가 로그인할 때까지 failed로 남습니다. 해결은 두 부분입니다. 데이터베이스 뒤로 순서를 잡고, 재시도할 여유를 줍니다:

[Unit]
After=postgresql.service
Wants=postgresql.service
 
[Service]
Restart=on-failure
RestartSec=5s

다음 재부팅 후 systemctl show api -p NRestarts -p ActiveState는 재시작 한두 번과 ActiveState=active를 보여줍니다. 데이터베이스가 연결을 받기까지 시간이 걸리면 순서만으로는 부족하기 때문에 지연도 남겨 둡니다.

끝까지 확인하고 재발 막기

systemctl is-active myapp를 실행한 다음, 일부러 systemctl restart myapp를 한 번 하면서 journalctl -u myapp -f를 지켜보세요. 재발을 막으려면 Restart=가 있는 유닛에는 RestartSec=를 명시하고, 실제 의존성은 After=/Wants=로 선언하고, failed 상태 유닛(systemctl --failed)에 알림을 거세요. StartLimitIntervalSec=0은 제한을 완전히 끕니다. 그러면 고장 난 프로그램이 RestartSec 간격으로 영원히 재시도하니, 적당한 지연과 함께만 쓰세요.

203/EXEC, 시작 타임아웃과 다른 점

status=203/EXEC는 systemd가 ExecStart= 프로그램을 실행하지 못했다는 뜻입니다 — 틀린 경로, 실행 비트 누락. 이 오류 아래 숨은 크래시인 경우가 많습니다. Job for myapp.service failed because a timeout was exceeded는 한 번의 시작이 TimeoutStartSec=보다 오래 걸렸다는 뜻입니다. 빠른 시작 여러 번이 아니라 느린 시작 한 번입니다.

다음에 서비스가 내려간 채로 남으면 이 순서를 거꾸로 따라가 보세요. repeated too quickly 위쪽 저널을 읽고, 그 오류를 고친 다음, 재시작 간격을 바꿔야 할지 판단하세요.