systemd OnFailure 기준 정리

systemd OnFailure 기준 정리

OnFailure=는 어떤 유닛이 failed 상태에 들어갔을 때 다른 유닛을 함께 시작하도록 연결하는 systemd의 [Unit] 지시어다. 2026년 7월 16일 기준 systemd 260.1 공식 문서에 따르면, 이 옵션은 "실패한 뒤 무엇을 추가로 실행할지"를 정의하는 용도에 가깝다. 장애 알림 서비스, 정리 작업, 별도 복구 유닛을 이어 붙일 때 주로 의미가 생긴다.

핵심은 두 가지다. 첫째, 아무 start 실패처럼 보이는 상황이 모두 OnFailure=를 트리거하지는 않는다. 둘째, 이것은 시스템 전체를 재부팅하는 FailureAction=과는 성격이 다르다. 어떤 실패에 후속 유닛을 붙일지, 아니면 매니저 액션 자체를 걸지 먼저 구분하는 편이 안전하다.

OnFailure=는 언제 실행될까?

systemd 260.1 공식 문서는 OnFailure=를 "이 유닛이 failed 상태에 들어가면 활성화할 유닛 목록"으로 설명한다. 따라서 기준은 단순한 종료가 아니라 실제로 대상 유닛이 failed 상태로 이동했는지다.

[Unit]
Description=Example worker
OnFailure=notify-admin@%n.service cleanup-worker@%n.service

이 예시는 Example worker가 실패 상태에 들어가면 두 개의 후속 유닛을 시작한다. 템플릿 유닛을 함께 쓰면 실패한 원래 유닛 이름을 %n 같은 specifier로 전달해 알림 메시지나 정리 범위를 분기하기 쉽다.

무엇이 OnFailure=를 트리거하지 않을까?

같은 공식 문서는 조건식과 assert를 별도로 설명한다. 유닛 시작 전에 Condition...= 검사가 맞지 않으면 시작은 mostly silently skipped 되고, Assert...=가 맞지 않으면 에러 메시지와 함께 시작이 중단된다. 하지만 둘 다 유닛을 failed 상태로 옮기지는 않는다.

상황	문서상 기본 동작	OnFailure= 관점
서비스 프로세스가 실패 상태로 종료	유닛이 failed 상태로 이동	후속 유닛 시작 대상이 될 수 있음
Condition...= 불만족	시작을 건너뜀	failed 상태가 아니므로 기대와 다를 수 있음
Assert...= 불만족	에러와 함께 시작 중단	failed 상태로 이동하지 않으므로 별도 해석 필요
정상 종료 후 inactive 전이	실패가 아니라 정상 정지	OnSuccess= 검토 대상

이 차이 때문에 "조건이 맞지 않으면 알림 보내기" 같은 요구를 OnFailure= 하나로 처리하려 하면 어긋날 수 있다. 조건 불만족은 실패가 아니라 적용 대상이 아님을 뜻하는 경우가 많기 때문이다.

OnFailureJobMode=는 왜 같이 봐야 할까?

OnFailure=가 어떤 유닛을 실행할지 정한다면, OnFailureJobMode=는 그 유닛들을 어떤 job mode로 큐에 넣을지 정한다. systemd 260.1 공식 문서 기준 기본값은 replace다. 즉 기존 충돌 job을 대체하는 일반적인 방식이 기본이다.

문서에는 fail, flush, replace, replace-irreversibly, isolate, ignore-dependencies, ignore-requirements 같은 값이 나열된다. 다만 일반적인 장애 후속 처리에서는 기본값 replace를 유지하는 편이 안전하고, 특별한 트랜잭션 제어가 필요한 경우에만 바꾸는 쪽이 무난하다.

[Unit]
Description=Example worker
OnFailure=notify-admin@%n.service
OnFailureJobMode=replace

FailureAction=과는 무엇이 다를까?

FailureAction=은 유닛이 실패 상태에 들어갔을 때 매니저 차원에서 재부팅, 종료, halt 같은 액션을 취하도록 설정한다. 반면 OnFailure=는 다른 유닛을 활성화하는 연결 규칙이다. 둘 다 실패 상태를 기준으로 하지만, 범위와 영향이 다르다.

옵션	대상	무난한 쓰임새
OnFailure=	다른 유닛 시작	알림, 정리 작업, 복구 워커 호출
FailureAction=	서비스 매니저 액션	복구보다 강제 재부팅·종료 정책이 필요한 경우

대부분의 애플리케이션 서비스에서는 먼저 OnFailure=로 후속 처리 경로를 두고, 정말 시스템 차원의 강한 조치가 필요한 유닛에서만 FailureAction=을 검토하는 편이 보수적이다.

실전에서는 어떻게 나누는 편이 좋을까?

실패 사실을 알리고 로그를 수집하는 정도라면 별도의 oneshot 서비스나 템플릿 유닛을 OnFailure=에 연결하는 구성이 단순하다. 반대로 장애가 발생하면 노드 자체를 재부팅해야 하는 특수 어플라이언스 성격의 시스템이라면 FailureAction=이 더 직접적일 수 있다.

또한 공식 문서에 따르면 조건 불만족은 start rate limit에도 집계되지 않는다. 즉 어떤 서비스가 조건 때문에 건너뛰어졌다면, 그것을 실패 횟수로 보고 OnFailure= 후속 처리나 start-limit 대응을 기대하는 설계는 맞지 않는다.

FAQ

Q. 서비스가 시작되지 않았는데도 OnFailure=가 안 돌 수 있나?

그럴 수 있다. 공식 문서 기준 Condition...= 불만족은 skip으로 처리되고 failed 상태로 가지 않기 때문이다.

Q. 알림 유닛 여러 개를 한 번에 연결할 수 있나?

가능하다. OnFailure=는 공백으로 구분한 유닛 목록을 받을 수 있다. 다만 후속 유닛끼리도 의존성이나 순서가 필요하면 각 유닛 정의 안에서 별도로 표현하는 편이 명확하다.

Q. 정상 종료 뒤 후속 작업을 붙이고 싶다면?

그 경우는 OnSuccess=가 더 맞다. OnFailure=는 이름 그대로 실패 상태 진입을 기준으로 한다.

정리

OnFailure=는 systemd에서 "실패한 유닛 뒤에 무엇을 실행할지"를 연결하는 기본 도구다. 2026년 7월 16일 기준 systemd 260.1 공식 문서만 기준으로 보면, 이 옵션은 failed 상태 전이를 기준으로 동작하며 조건 불만족이나 assert 실패처럼 유닛을 failed로 만들지 않는 경우와는 분리해서 봐야 한다.

판단 기준은 세 가지면 충분하다. 첫째, 정말 failed 상태 뒤의 후속 유닛이 필요한지 본다. 둘째, 단순 후속 처리인지 시스템 차원 액션인지 구분해 OnFailure=와 FailureAction=을 나눈다. 셋째, 특별한 이유가 없다면 OnFailureJobMode=replace 기본값을 유지한다.

참고 자료

• systemd 260.1 공식 문서: systemd.unit