systemd ConditionPathExists 기준 정리

systemd ConditionPathExists 기준 정리

ConditionPathExists=는 systemd가 유닛을 시작하기 직전에 특정 절대 경로가 존재하는지 확인하는 조건식이다. 2026년 7월 12일 기준 systemd 261.1 공식 문서에 따르면 조건이 맞지 않으면 유닛 시작은 실패 처리보다 "건너뛰기"에 가깝게 동작한다. 파일이 없는 환경에서는 조용히 실행을 생략하고, 파일이 있는 환경에서만 같은 유닛을 켜고 싶을 때 쓰기 좋다.

핵심은 이것이 의존성 대체 수단이 아니라 "시작 직전 가드"라는 점이다. systemd는 조건과 assert를 큐에 넣는 시점이 아니라 실제 시작 잡을 실행하는 시점에 평가한다. 그래서 어떤 파일이 있어야만 서비스를 켠다는 요구에는 잘 맞지만, 의존성 그래프 자체를 조건부로 바꾸는 용도로 보면 어긋난다.

ConditionPathExists=는 정확히 어떻게 동작할까?

공식 문서 기준 이 옵션은 지정한 절대 경로가 존재하면 통과하고, 존재하지 않으면 조건이 실패한다. 경로 앞에 !를 붙이면 의미가 반대로 바뀌어서 "그 경로가 없어야 시작"이라는 조건이 된다.

[Unit]
ConditionPathExists=/etc/myapp/config.yaml

이 예시는 /etc/myapp/config.yaml이 있을 때만 유닛을 시작한다. 반대로 초기화 작업처럼 "특정 마커 파일이 없어야 한 번 실행" 같은 흐름은 다음처럼 쓸 수 있다.

[Unit]
ConditionPathExists=!/var/lib/myapp/.initialized

실패와 skip은 무엇이 다를까?

systemd 261.1 문서는 조건이 맞지 않으면 유닛 시작이 mostly silently skipped 되고, assert가 맞지 않으면 에러 메시지와 함께 start job이 중단된다고 설명한다. 중요한 점은 둘 다 유닛을 곧바로 failed 상태로 옮기는 방식은 아니라는 점이다.

항목	조건 불만족 시 동작	쓰기 좋은 상황
ConditionPathExists=	시작을 건너뜀	환경에 따라 조용히 비활성화돼도 되는 서비스
AssertPathExists=	에러 메시지와 함께 시작 잡 중단	파일이 없으면 운영자가 바로 알아야 하는 필수 전제조건

예를 들어 선택 기능을 켜는 서비스라면 ConditionPathExists=가 더 자연스럽다. 반대로 핵심 인증서나 필수 데이터 디렉터리가 없으면 반드시 조치가 필요하다면 AssertPathExists= 쪽이 더 분명하다.

절대 경로만 쓰면 될까?

공식 문서는 ConditionPathExists=에 절대 경로를 넘긴다고 설명한다. 상대 경로를 기준으로 현재 작업 디렉터리를 해석해 주는 옵션이 아니므로, 서비스 정의에서는 /etc, /var/lib, /run 같은 실제 절대 경로를 그대로 적는 편이 맞다.

또한 systemd는 ConditionPathIsSymbolicLink=를 제외한 path 계열 조건에서 심볼릭 링크를 따라간다고 설명한다. 즉 ConditionPathExists=는 "최종 대상이 존재하는가"를 보는 쪽에 가깝다.

비슷한 path 조건과는 어떻게 구분할까?

옵션	확인 대상	언제 더 적합한가
ConditionPathExists=	정확한 경로 존재 여부	단일 파일이나 디렉터리 존재만 확인하면 충분할 때
ConditionPathExistsGlob=	glob 패턴에 맞는 항목이 하나라도 있는지	로그 파일, 장치 노드, 드롭인 파일처럼 패턴 기반 확인이 필요할 때
ConditionPathIsDirectory=	경로가 디렉터리인지	단순 존재보다 디렉터리 타입 보장이 필요할 때
ConditionPathIsReadWrite=	해당 파일시스템이 읽기/쓰기 가능한지	읽기 전용 마운트에서는 실행하면 안 되는 작업일 때
ConditionPathIsSymbolicLink=	경로가 심볼릭 링크인지	링크 자체 존재 여부가 의미를 가질 때

존재만 보면 되는 상황에 ConditionPathIsDirectory=나 ConditionPathIsReadWrite=를 섞어 쓰면 의도가 불필요하게 좁아질 수 있다. 필요한 보장 수준만 고르는 편이 유지보수에 유리하다.

여러 조건을 함께 쓰면 어떻게 평가될까?

systemd 공식 문서 기준 여러 Condition...=를 나란히 쓰면 기본적으로 AND로 평가된다. 즉 모두 참이어야 유닛이 시작된다. 여기에 |를 붙인 triggering condition을 섞으면, 일반 조건은 모두 참이어야 하고 triggering condition 중 하나 이상이 참이면 시작할 수 있다.

[Unit]
ConditionPathExists=/etc/myapp/config.yaml
ConditionPathExists=|/run/myapp/override.flag
ConditionPathExists=|/run/myapp/fallback.flag

이 구조는 공통 전제 하나와 선택 전제 여러 개를 조합할 때 유용하다. 다만 이런 조건식도 결국 "시작 직전 평가"일 뿐이므로, 유닛 의존성을 조건부로 바꾸는 기능으로 오해하면 안 된다.

언제 AssertPathExists=로 올려야 할까?

경로가 없으면 단순히 기능을 생략해도 되는 경우는 ConditionPathExists=가 적합하다. 반대로 경로가 없다는 사실 자체가 잘못된 배포, 잘못된 마운트, 잘못된 초기화 상태를 뜻한다면 AssertPathExists=가 더 맞다.

상황	무난한 선택	이유
선택 기능용 설정 파일이 있을 때만 실행	ConditionPathExists=	없어도 시스템 오류로 볼 필요가 없기 때문
필수 인증서나 키 파일이 반드시 있어야 함	AssertPathExists=	누락을 운영 이슈로 명확히 드러내야 하기 때문
첫 실행 전 마커 파일 부재를 확인	ConditionPathExists=!...	초기화 이후에는 자연스럽게 건너뛰게 만들 수 있기 때문

테스트는 어떻게 하는 편이 안전할까?

systemd 261.1 공식 문서는 systemd-analyze condition 명령으로 Condition*=과 Assert*= 표현식을 평가할 수 있다고 설명한다. 실제 서비스 재시작 전에 조건식 자체가 원하는 값으로 판정되는지 먼저 보는 데 유용하다.

systemd-analyze condition \
  'ConditionPathExists=/etc/myapp/config.yaml' \
  'AssertPathExists=/etc/os-release'

또한 --unit=UNIT 옵션을 쓰면 특정 유닛 파일 안의 조건과 assert를 한 번에 평가할 수 있다. 운영 중인 서비스를 바로 재기동하기 전에 조건식만 점검하고 싶다면 이 경로가 더 안전하다.

FAQ

Q. 이 옵션으로 의존성 자체를 조건부로 만들 수 있을까?

그렇게 보는 것은 정확하지 않다. 공식 문서 기준 조건과 assert는 실제 start job 실행 시점에 평가되며, conditionalizing unit dependencies에는 적합하지 않다.

Q. 파일이 없으면 서비스가 failed 상태가 되나?

공식 문서 기준 조건 불만족은 skip에 가깝고, assert 불만족도 unit state를 곧바로 failed로 바꾸는 방식은 아니다. 다만 assert는 에러 메시지와 함께 시작 잡을 중단시켜 운영자가 더 빨리 눈치채게 만든다.

Q. 심볼릭 링크 경로를 넣으면 링크 자체를 검사하나?

대부분의 path 조건은 심볼릭 링크를 따라간다. 링크 자체인지 확인하려면 예외적으로 ConditionPathIsSymbolicLink=를 써야 한다.

정리

ConditionPathExists=는 systemd 유닛을 "특정 절대 경로가 있을 때만 시작"하도록 만드는 가장 단순한 가드다. 2026년 7월 12일 기준 systemd 261.1 공식 문서만 기준으로 보면, 이 옵션은 실패보다 skip 의미가 강하고, 파일 부재를 치명 오류로 볼지 여부에 따라 AssertPathExists=와 구분해서 쓰는 것이 핵심이다.

판단 기준은 세 가지면 충분하다. 첫째, 파일 부재가 정상적인 환경 차이인지 운영 오류인지 구분한다. 둘째, 존재만 보면 되는지 디렉터리·쓰기 가능 여부·glob 매칭 같은 더 강한 path 조건이 필요한지 본다. 셋째, 실제 적용 전에는 systemd-analyze condition으로 판정을 먼저 확인한다.

참고 자료

• systemd 261.1 공식 문서: systemd.unit
• systemd 261.1 공식 문서: systemd-analyze