systemd StartLimitBurst 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

systemd 서비스가 계속 실패하면 Restart=만으로는 충분하지 않을 수 있습니다. 자동 재시작은 장애 복구에 도움이 되지만, 원인이 해결되지 않은 상태에서 너무 빠르게 반복되면 로그와 자원을 소모하고 다른 문제를 가릴 수 있습니다. 이때 보는 설정이 StartLimitIntervalSec=와 StartLimitBurst=입니다.

결론부터 말하면 Restart=on-failure 같은 자동 재시작 정책을 쓸 때는 시작 제한도 함께 확인하는 편이 안전합니다. 기본값만으로도 짧은 실패 루프는 막을 수 있지만, 서비스의 정상 재시도 주기와 장애 대응 방식에 맞게 interval, burst, restart delay를 같이 잡아야 합니다.

StartLimit은 무엇을 제한할까

StartLimitIntervalSec=와 StartLimitBurst=는 일정 시간 안에 허용할 unit 시작 횟수를 정합니다. systemd 공식 문서 기준으로, unit이 interval 안에서 burst보다 많이 시작되면 더 이상 시작이 허용되지 않습니다.

• StartLimitIntervalSec=: 시작 횟수를 세는 시간 창
• StartLimitBurst=: 그 시간 창 안에서 허용되는 시작 횟수
• StartLimitAction=: 시작 제한에 걸렸을 때 추가로 수행할 동작

이 설정은 Restart=로 발생한 자동 재시작에만 적용되는 기능이 아닙니다. 공식 문서는 수동 시작을 포함한 모든 종류의 start에 적용된다고 설명합니다. 다만 실무에서는 반복 실패하는 서비스의 자동 재시작을 제어할 때 가장 자주 마주칩니다.

기본값은 어떻게 정해질까

unit에 별도 값을 쓰지 않으면 manager 설정의 DefaultStartLimitIntervalSec=와 DefaultStartLimitBurst=가 기본값이 됩니다. systemd 공식 systemd-system.conf 문서 기준으로 기본 시작 제한은 DefaultStartLimitIntervalSec=10s, DefaultStartLimitBurst=5입니다.

[Unit]
StartLimitIntervalSec=30s
StartLimitBurst=3

[Service]
Restart=on-failure
RestartSec=5s
ExecStart=/usr/local/bin/example-service

위 예시는 30초 안에 시작을 3회까지만 허용하는 형태입니다. 서비스가 계속 실패하고 Restart=on-failure에 의해 반복 시작되면, 제한에 도달한 뒤에는 새 시작이 거부됩니다.

Restart=와 StartLimit은 역할이 다르다

Restart=는 서비스 종료 결과를 보고 다시 시작할지 결정합니다. RestartSec=는 다시 시작하기 전 기다릴 시간을 정합니다. 반면 StartLimitIntervalSec=와 StartLimitBurst=는 정해진 시간 창 안에서 시작이 너무 많이 발생했는지 검사합니다.

설정	역할	볼 기준
Restart=	실패 후 재시작 여부 결정	실패를 자동 복구할 수 있는 서비스인지
RestartSec=	재시작 전 대기 시간 지정	의존 서비스, 네트워크, 파일 잠금이 회복될 시간
StartLimitIntervalSec=	시작 횟수 집계 시간 창 지정	반복 실패를 어느 기간 안에서 볼지
StartLimitBurst=	시간 창 안의 허용 시작 횟수 지정	일시적 실패를 몇 번까지 허용할지

중요한 점은 RestartSec=가 시작 제한을 없애는 설정이 아니라는 점입니다. 재시도 간격을 길게 잡으면 제한에 도달할 가능성은 줄어들 수 있지만, 허용 횟수와 시간 창은 여전히 StartLimit 설정이 판단합니다.

 

 

제한에 걸리면 어떻게 보일까

시작 제한에 도달하면 unit은 더 이상 시작되지 않습니다. systemctl status나 journal에는 start limit에 걸렸다는 취지의 메시지가 나타날 수 있습니다. systemd의 D-Bus 상태에서도 서비스 결과 값으로 start-limit가 쓰일 수 있습니다.

이 상태에서 바로 값을 크게 늘리는 것보다 먼저 서비스가 왜 반복 실패했는지 확인해야 합니다. 실행 파일 경로, 권한, 환경 변수, 의존 리소스, 포트 충돌, 설정 파일 오류처럼 반복 실패의 원인이 남아 있으면 제한을 늘려도 같은 문제가 더 오래 반복될 뿐입니다.

reset-failed는 언제 필요할까

systemctl reset-failed는 failed 상태를 지우는 명령입니다. systemd 공식 systemctl 문서는 이 명령이 failed 상태뿐 아니라 unit의 start rate limit counter도 0으로 초기화한다고 설명합니다. 그래서 시작 제한에 걸려 다시 시작되지 않는 unit은 원인을 고친 뒤 reset-failed를 사용해 다시 시작 가능하게 만들 수 있습니다.

systemctl status example.service
systemctl reset-failed example.service
systemctl start example.service

이 명령은 문제를 해결하는 명령이 아니라 상태와 카운터를 초기화하는 명령입니다. 따라서 원인 수정 없이 반복 실행하면 같은 제한에 다시 도달할 수 있습니다.

어떤 값이 무난할까

값은 서비스 성격에 따라 달라집니다. 빠르게 뜨는 백그라운드 데몬이 설정 오류로 즉시 종료되는 경우라면 기본값만으로도 실패 루프를 막는 효과가 있습니다. 반대로 외부 의존성이 일시적으로 늦게 준비되는 서비스라면 RestartSec=를 너무 짧게 두지 않는 편이 낫습니다.

• 설정 오류처럼 즉시 실패하는 서비스: 제한을 크게 늘리기보다 원인 확인 우선
• 일시적 의존성 실패가 가능한 서비스: RestartSec=를 충분히 길게 조정
• 반드시 계속 살아 있어야 하는 서비스: 재시작 정책과 알림, 로그 확인 체계를 함께 설계
• 시작 제한을 끄는 설정: StartLimitIntervalSec=0은 신중하게 사용

자주 묻는 질문

StartLimitBurst=5면 실패를 5번 허용한다는 뜻일까

정확히는 interval 안에서 허용되는 start 횟수입니다. 실패 횟수라는 표현은 실무적으로 이해하기 쉽지만, 공식 기준은 start 요청 횟수입니다.

Restart=always면 StartLimit을 무시할까

아닙니다. Restart=는 재시작 여부를 정하고, StartLimit은 시작 빈도를 제한합니다. 자동 재시작 정책이 있어도 시작 제한에 도달하면 새 시작이 허용되지 않을 수 있습니다.

StartLimitAction=은 꼭 써야 할까

대부분의 일반 서비스에서는 꼭 필요하지 않습니다. 공식 문서 기준 기본값은 none이며, 제한에 걸렸을 때 추가 동작 없이 시작만 거부됩니다. 재부팅 같은 강한 동작은 장비 역할과 장애 대응 정책이 분명할 때만 검토해야 합니다.

정리

StartLimitIntervalSec=와 StartLimitBurst=는 systemd 서비스의 반복 시작을 제한하는 안전장치입니다. Restart=가 복구를 위한 설정이라면, StartLimit은 복구 시도가 실패 루프로 번지지 않게 막는 설정입니다.

무난한 기준은 자동 재시작을 켤 때 시작 제한을 함께 확인하고, 제한에 걸렸을 때는 값을 먼저 늘리기보다 실패 원인을 먼저 고치는 것입니다. 그 다음 서비스의 실제 복구 시간에 맞춰 RestartSec=, interval, burst를 함께 조정하는 편이 안정적입니다.