systemd 유닛 시작 실패 원인 분석 및 해결 방법
systemctl status 명령어로 종료 코드를 확인하는 방법을 설명합니다. 203/EXEC 및 226/NAMESPACE 오류의 의미와 유닛이 즉시 종료되는 원인을 분석하여 문제 해결의 핵심 기준을 제시합니다.
systemd unit이 시작되지 않는 이유
시작되지 않는 systemd unit은 한 필드에 그 이유를 표시한다. systemctl status <unit>를 실행하고, 실패를 보고하는 줄에서 code=와 status=를 확인한다. 200번대 상태 번호는 거의 항상 systemd가 프로그램에 도달하지 못했다는 뜻이다. unit file에서 요청한 환경을 구성하는 중에 실패한 것이다. 해당 줄에 code=exited이 표시되고 상태 번호가 200 미만이면 프로그램이 실제로 실행된 후 자체적으로 종료한 것이다. 따라서 unit file은 대체로 올바르고 애플리케이션에 문제가 있다. code=killed은 signal이 프로세스를 종료했다는 뜻이다. 이는 문서 마지막 부분에서 별도로 다룬다.
이 구분이 판단 기준이다. 아래 내용은 숫자가 나타나는 순서에 따라 이 기준에서 파생된다.
어떤 순서로 세 명령을 실행해야 하는가
systemctl status myapp.service
journalctl -u myapp.service -b --no-pager
systemd-analyze verify /etc/systemd/system/myapp.servicesystemctl status은 최종 상태를 보여 준다. 먼저 Loaded: 줄을 읽어야 한다. 이 줄은 systemd가 실제로 구문 분석한 파일을 표시하고, 해당 unit이 활성화되었는지, 마스킹되었는지, 아니면 전혀 찾을 수 없는지 알려 준다. 그런 다음 Active: 줄과 그 아래의 code= 및 status= 쌍을 읽는다.
journalctl -u myapp.service -b --no-pager는 세부 정보를 보여 준다. -u는 해당 unit 하나만 필터링하고, -b은 현재 부팅 세션의 출력으로 제한하므로 지난주에 발생한 실패를 읽지 않게 한다. --no-pager은 결과를 터미널에 바로 출력하므로 grep로 파이프할 수 있다. status는 최근 로그 몇 줄만 표시하고 긴 줄을 잘라서 보여 준다. journal에는 프로그램이 종료하기 전에 출력한 내용이 모두 기록되며, 이것이 보통 실제 오류다. -n이 없으면 이번 부팅 세션의 모든 항목을 가져온다. 최신 100개만 유지하려면 -n 100을 추가한다. 또는 두 번째 터미널에서 unit을 재시작하는 동안 -f와 함께 실행한다.
systemd-analyze verify은 unit 파일을 실행하지 않고 불러온다. 알 수 없는 섹션과 지시어가 있으면 경고하고, 실행할 수 없는 ExecStart=의 명령도 표시한다. 이 명령은 조용히 발생하는 두 가지 오류를 찾아낸다. 하나는 철자가 틀린 키다. systemd는 로드 시 이 키를 무시하면서 경고를 남기지만, 대부분의 사용자는 그 경고를 읽지 않는다. 다른 하나는 존재하지 않는 경로다.
unit 파일을 편집한 뒤에는 sudo systemctl daemon-reload를 실행한다. 이 작업을 하기 전까지 systemd는 이전에 불러온 복사본을 계속 사용하며, systemctl status은 디스크의 파일이 변경되었다는 경고를 추가한다. "아무것도 하지 않은" 것처럼 보이는 수정은 systemd가 아직 읽지 않은 수정인 경우가 많다.
추가로 두 명령을 알아 두면 유용하다. systemctl cat myapp.service은 유효한 unit 정의를 출력한다. 여기에는 기본 파일과 /etc/systemd/system/myapp.service.d/ 아래의 모든 drop-in이 포함된다. systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory은 systemd가 구문 분석한 값으로 출력하므로 실제로 실행될 내용을 확인할 수 있다.
status=203/EXEC는 무엇을 의미합니까?
203/EXEC은 systemd가 설정을 완료하고 execve()를 호출했으나 커널이 이를 거부했음을 의미합니다. 프로그램은 자신의 코드를 단 한 줄도 실행하지 못했습니다. 거의 모든 사례는 다음 네 가지 원인 중 하나에 해당합니다.
ExecStart=에 지정된 경로가 잘못되었거나 절대 경로가 아닙니다. 유닛 파일에 적힌 정확한 문자열과ls -l의 결과를 비교하여 확인하십시오.- 파일에 실행 권한(execute bit)이 없습니다.
sudo chmod +x /opt/myapp/run.sh로 이 문제를 해결할 수 있습니다. 아카이브에서 압축을 풀거나 다른 머신에서 복사한 파일은 종종 이 권한을 잃어버립니다. - 셰뱅(shebang) 라인이 깨졌습니다. 커널은 스크립트의 첫 번째 줄을 읽어 지정된 인터프리터를 실행합니다. 따라서 서비스의 PATH에
python3이 없으면#!/usr/bin/env python3은 실패합니다. 또한 Windows 줄 바꿈 문자로 저장된 파일은/bin/bash\r이라는 이름의 인터프리터를 찾으려 시도하는데, 이는 존재하지 않으므로 실패합니다. - 파일이 현재 머신에서 실행할 수 없는 형식입니다. 아키텍처가 맞지 않거나, 셰뱅이 없는 텍스트 파일인 경우입니다.
설정을 변경하기 전에 서비스 사용자 권한으로 직접 명령을 실행하여 재현해 보십시오.
sudo -u appuser /opt/myapp/run.sh
file /opt/myapp/run.sh
head -1 /opt/myapp/run.sh | cat -Afile는 아키텍처를 명시하며, 줄 바꿈 문자가 문제일 경우 "with CRLF line terminators"라는 메시지를 출력합니다. cat -A은 동일한 문제를 ^M이 포함된 형태로 보여줍니다. sed -i 's/\r$//' /opt/myapp/run.sh를 사용하여 이를 제거하십시오.
종료 코드 범위에 대한 주의 사항이 하나 있습니다. 200 이상의 값은 관례일 뿐 보장되는 것은 아닙니다. 애플리케이션이 직접 203을 종료 코드로 사용할 수 있으며, 이 경우 systemd는 시스템 오류와 애플리케이션의 종료 코드를 구분할 수 없습니다. systemd-analyze exit-status 203은 코드의 이름과 클래스를 출력하여 표를 읽는 데 도움을 주지만, 애플리케이션이 199 이상의 종료 코드를 사용한다면 이를 변경하는 것이 좋습니다.
217/USER 또는 216/GROUP이 표시되는 이유는 무엇입니까?
217/USER은 일반적으로 서비스가 시작되는 시점에 User=에 지정된 계정이 존재하지 않음을 의미합니다. 이 코드는 PrivateUsers= 같은 샌드박싱 옵션에 필요한 사용자 네임스페이스 설정에 실패한 경우에도 표시됩니다. 이 경우 저널에는 존재하지 않는 사용자를 표시하는 대신 "Failed to set up user namespacing"이 기록됩니다. 216/GROUP은 Group= 또는 SupplementaryGroups=에 해당하는 동일한 실패입니다. 각각 한 번의 명령으로 확인할 수 있습니다.
getent passwd appuser
getent group appgroup각 명령은 한 줄을 출력하거나 아무것도 출력하지 않고 0이 아닌 값을 반환합니다. 아무것도 출력되지 않으면 해당 이름을 시스템에서 인식하지 못한다는 뜻입니다. 따라서 systemd가 해당 계정으로 전환할 수 없고 exec 전에 중지됩니다. 해결 방법은 계정을 생성하는 것입니다. User=root을 설정하는 것이 아닙니다. 최소 권한을 적용한 전용 시스템 계정으로 하나의 서비스를 실행하는 것이 해당 지시문의 목적입니다.
sudo useradd --system --no-create-home --shell /usr/sbin/nologin appuserDynamicUser=yes은 systemd가 시작할 때마다 임시 계정을 할당하도록 하여 이 문제를 피합니다. 상태를 유지하지 않는 서비스에 적합합니다. 파일을 쓰는 서비스에는 반드시 StateDirectory=도 함께 지정해야 합니다. 시작할 때마다 사용자 ID가 바뀌므로 일반 경로 아래의 파일은 더 이상 존재하지 않는 계정이 소유하게 됩니다.
226/NAMESPACE란 무엇입니까?
226/NAMESPACE은 샌드박싱 지시어에서 비롯됩니다. 유닛이 ProtectSystem=, ProtectHome=, PrivateTmp=, ReadWritePaths= 또는 이와 유사한 설정을 지정하면, systemd는 프로그램을 실행하기 전에 해당 서비스를 위한 전용 마운트 네임스페이스를 생성합니다. 여기서 네임스페이스란 하나의 프로세스가 바라보는 파일 시스템의 독립적인 뷰를 의미합니다. 해당 계획 중 어떤 마운트라도 실패하면, 서비스 시작은 226 오류와 함께 실패하며 프로그램은 실행되지 않습니다.
일반적인 원인은 ReadWritePaths=에 존재하지 않는 경로가 포함된 경우입니다. ProtectSystem=strict은 전체 파일 시스템을 읽기 전용으로 마운트하며, ReadWritePaths=은 지정된 경로를 쓰기 가능하도록 다시 엽니다. systemd는 존재하지 않는 디렉터리를 다시 열 수 없습니다. 두 가지 해결책이 있습니다. StateDirectory=를 사용하여 systemd가 시작할 때마다 /var/lib/<name>을 생성하고 이를 서비스 사용자에게 할당하도록 하거나, 경로 앞에 -을 붙여 원본이 없을 경우 해당 항목을 무시하도록 systemd에 지시하는 것입니다. 보안 설정을 삭제하는 것은 좋지 않은 해결책이며, 이는 5분이면 해결할 문제를 영구적인 문제로 바꿉니다.
[Service]
ProtectSystem=strict
ProtectHome=yes
StateDirectory=myapp
ReadWritePaths=-/srv/uploads어떤 줄이 원인인지 알 수 없을 때는 보안 설정 블록 전체를 제거한 뒤, 설정을 다시 불러오고 서비스를 시작하십시오. 서비스가 정상적으로 실행된다면, 제거했던 줄을 하나씩 다시 추가하면서 매번 재시작하여 확인하십시오. 이 계열의 설정 중 233/RUNTIME_DIRECTORY와 238/STATE_DIRECTORY이 있습니다. 이들은 systemd가 RuntimeDirectory= 또는 StateDirectory=에 명시된 디렉터리를 생성하거나 소유권을 가져올 수 없을 때 발생하며, 보통 해당 경로가 이미 존재하고 다른 사용자의 소유일 때 나타납니다.
WorkingDirectory가 올바른데도 200/CHDIR이 발생하는 이유는 무엇입니까?
200/CHDIR은 WorkingDirectory=로의 chdir()이 실패했음을 의미합니다. 해당 디렉터리가 없거나, 서비스 사용자가 해당 디렉터리에 진입할 수 없는 경우입니다. 디렉터리에 진입하려면 해당 디렉터리와 상위의 모든 경로에 대해 실행 권한이 필요합니다. 따라서 /home/deploy이 700 모드이고 서비스가 appuser로 실행되는 경우, 완벽하게 읽기 가능한 /home/deploy/app이라 하더라도 접근할 수 없습니다.
sudo -u appuser test -x /srv/myapp && echo ok
namei -l /srv/myappnamei -l은 경로의 모든 구성 요소에 대한 소유자와 모드를 출력하며, 이는 경로를 차단하는 디렉터리를 찾는 가장 빠른 방법입니다. WorkingDirectory=-/srv/myapp를 작성하면 디렉터리가 없어도 치명적인 오류가 발생하지 않습니다. 이는 시작 위치가 중요하지 않은 프로그램에는 적합하지만, 상대 경로로 파일을 여는 프로그램에는 적절하지 않습니다.
서비스가 시작한 뒤 1초 후에 중지되는 이유
여기에는 200 계열 코드가 없고, 오류 메시지도 전혀 없는 경우가 많다. unit은 시작 직후 inactive (dead)를 표시하거나 activating (auto-restart)을 반복한다. systemd는 환경을 올바르게 구성했다. 문제는 프로그램의 실제 동작과 Type=에서 약속한 동작이 일치하지 않는 데 있다.
기본값인 Type=simple는 프로그램이 포그라운드에 계속 실행된다는 의미다. 백그라운드로 fork한 뒤 종료하는 daemon을 지정하면 systemd는 주 프로세스가 종료된 것으로 판단하고 서비스를 완료된 상태로 처리한다. 대부분의 daemon에는 포그라운드에서 계속 실행하는 옵션이 있으며, 예를 들어 nginx -g 'daemon off;'와 같다.
Type=forking는 첫 번째 프로세스가 자식 프로세스가 준비되면 종료된다는 의미다. 포그라운드 프로그램을 지정하면 시작 작업은 TimeoutStartSec=가 소진될 때까지 기다린다. 기본값은 90초다. 이후 systemd가 프로그램을 종료하고 timeout을 로그에 기록한다.
Type=notify는 프로그램이 sd_notify()을 호출해 준비 완료를 알린다는 의미다. 이 기능을 지원하지 않는 프로그램은 아무것도 알리지 않는다. 따라서 시작 작업이 timeout되고 journal에는 그 결과가 protocol failure로 기록된다.
프로그램의 실제 동작에 맞춰 type을 선택해야 한다. simple, forking, oneshot, notify의 차이를 확인하면 이 유형의 장애를 해결할 한 가지 선택을 할 수 있다.
서비스가 계속 종료되면 systemd는 재시도를 중단하고 시작 요청이 너무 빠르게 반복되었다고 보고한다. 이후 unit은 failed 상태로 유지되며 systemd는 자동으로 다시 시작하지 않는다. rate limit interval이 지난 뒤 수동으로 시작하거나 sudo systemctl reset-failed myapp.service을 실행하면 된다. 이 명령은 failed 상태와 restart counter를 초기화하므로 즉시 수동 시작을 수행할 수 있다. limit을 높이는 것은 증상만 감출 뿐이다. 마지막 장애가 아니라 첫 번째 장애부터 journal을 확인해야 한다. 변경하기 전에 Restart=on-failure가 실제로 무엇을 다시 시도하는가도 확인한다.
왜 유닛이 오류 없이 비활성 상태인가요?
유닛은 시작되는 대신 건너뛰어질 수 있습니다. Condition* 지시어는 설계상 조용하게 작동합니다. 검사가 실패하면 systemd는 작업을 성공으로 표시하고 아무런 동작도 하지 않습니다. ConditionPathExists=/etc/myapp/config.yml을 포함한 유닛은 해당 파일이 없으면 절대 시작되지 않으며, 오류 또한 보고하지 않습니다.
systemctl show myapp.service -p ConditionResult -p ConditionTimestamp
journalctl -u myapp.service -b --no-pager | grep -i conditionConditionResult=no은 건너뛰기 상태를 확인해주며, 저널에는 충족되지 않은 검사 항목이 기록됩니다. 필수 조건이 누락되었을 때 명확하게 실패 처리를 해야 한다면 대신 Assert* 지시어를 사용하십시오. 조건, 단언 및 유닛 순서에서 각 검사가 어디에 적합한지 다룹니다.
이 외에도 조용하게 실패하는 몇 가지 경우가 더 있습니다. "찾을 수 없음(could not be found)" 오류는 보통 파일이 잘못된 디렉터리에 있거나 설정을 다시 불러오지 않았음을 의미합니다. 직접 작성한 유닛 파일은 /etc/systemd/system/에 위치해야 합니다. 마스킹된 유닛은 sudo systemctl unmask myapp.service으로 해제하기 전까지 모든 시작 요청을 거부합니다. 또한 systemctl enable은 [Install] 섹션이 없는 유닛에서 실패하므로, 해당 유닛에 WantedBy=multi-user.target 섹션을 추가하십시오.
실패한 것이 아니라 종료된 경우에는 어떻게 해야 하는가?
code=killed는 code=exited와 다른 문제다. 프로세스 외부의 무언가가 프로세스를 종료했다. status=9/KILL는 대개 out of memory (OOM) killer를 가리키며, 이 경우 journal에 선택된 프로세스가 기록된다. 그러나 SIGKILL만으로는 누가 보냈는지 알 수 없다. systemd도 SIGTERM을 받은 중지 중인 서비스가 TimeoutStopSec= 이후에도 종료되지 않으면 SIGKILL을 보낸다. 따라서 메모리를 원인으로 단정하기 전에 중지나 재시작이 진행 중이었는지 확인해야 한다. 직접 설정한 제한도 cgroup (control group) 내부에서 같은 방식으로 작동한다. free -m로 호스트의 가용 메모리를 확인하고, unit에 MemoryMax=가 설정되어 있는지 확인한다. MemoryMax, CPUQuota 및 기타 cgroup 제한에서는 어떤 제한이 프로세스를 종료하고 어떤 제한이 프로세스 실행만 느리게 하는지 설명한다.
시작을 시도한 직후 status=15/TERM가 표시되면 대개 systemd가 시작 제한 시간을 초과해 프로세스를 종료했다는 뜻이다. 이 경우 Type=로 돌아가 확인해야 한다.
이러한 장애 대부분을 방지하는 두 가지 습관
모든 곳에서 절대 경로를 사용합니다. systemd는 로그인 셸을 실행하지 않으므로 .bashrc도 없고 .profile도 없으며 활성화된 가상 환경도 없습니다. 시스템 서비스의 $PATH는 짧은 기본 목록일 뿐이므로 /opt이나 언어 버전 관리자의 shim을 포함하지 않습니다. /usr/bin/python3 또는 /opt/myapp/venv/bin/python를 전체 경로로 작성합니다. 셸에서 command -v myapp을 실행하면 붙여 넣을 경로가 출력됩니다. 같은 규칙을 WorkingDirectory=, EnvironmentFile= 및 ReadWritePaths=의 모든 경로에도 적용합니다.
ExecStart=는 셸이 아닙니다. systemd는 해당 줄을 단어로 분할한 다음 execve()을 직접 호출합니다. 파이프, 리디렉션, glob, &&, 백틱 및 ~은 의미가 없습니다. 이러한 요소는 리터럴 인수로 프로그램에 전달됩니다. ExecStart=/usr/bin/myapp --flag > /tmp/out.log은 >와 /tmp/out.log을 myapp에 전달하고, 그러면 myapp가 사용법 오류와 함께 종료됩니다. 이 오류는 systemd 문제와 전혀 다른 형태로 보입니다. 셸 기능이 필요하면 셸을 명시적으로 호출합니다.
ExecStart=/bin/sh -c '/usr/bin/myapp --flag | /usr/bin/tee -a /var/log/myapp.log'출력만 필요하다면 셸을 사용할 필요가 없습니다. 서비스 출력은 기본적으로 journal로 전송되며, StandardOutput=append:/var/log/myapp.log는 셸 없이 파일에 기록합니다.
변수 확장에도 같은 제한이 적용됩니다. $MYVAR과 ${MYVAR}은 Environment=, EnvironmentFile= 및 systemd가 직접 설정하는 일부 변수(예: $USER)를 사용해 치환됩니다. % 지정자도 확장되며, 예를 들어 %i가 이에 해당합니다. 로그인 셸의 변수는 확장되지 않습니다. $HOME은 unit에 User=가 있을 때만 SetLoginEnvironment=의 기본값을 통해 설정됩니다. 따라서 User= 없이 root로 실행되는 서비스에는 $HOME이 없으며, 필요하면 직접 설정해야 합니다. EnvironmentFile=도 셸 스크립트가 아닙니다. 그 안에 export를 작성할 수 없고 인용 규칙도 bash와 다릅니다. 또한 -을 경로 앞에 붙이지 않으면 파일이 없을 때 치명적인 오류가 발생합니다.
운영 서버에서 문제 해결하기
코드를 읽고, 원인을 증명하고, 한 가지를 변경한 뒤, 재시작하십시오. 이 순서는 모든 수치를 외우는 것보다 중요합니다. 세 가지 추측성 수정을 한꺼번에 적용하여 무엇이 문제를 해결했는지 놓치는 상황을 방지하기 때문입니다. 직접 작성하지 않은 유닛에도 동일한 경로를 적용할 수 있습니다. 실행되지 않는 타이머는 시작되지 않은 서비스와 같습니다. 따라서 먼저 서비스를 디버깅하십시오. systemd 타이머와 그 타이머가 트리거하는 서비스는 위에서 언급한 방식과 정확히 동일한 방식으로 실패하며, 저널에서 로그를 요청하기 전까지는 타이머가 출력을 숨깁니다.
FAQ
systemctl status에서 status=203/EXEC는 무엇을 의미합니까?
systemd는 unit이 요청한 설정을 모두 적용했지만 execve() 호출이 실패했으므로 프로그램이 시작되지 않았습니다. 다음 4가지를 순서대로 확인합니다. ExecStart=에 지정한 경로가 존재하는 절대 경로인지 확인합니다. 파일에 실행 권한이 있는지 확인합니다. shebang이 service PATH에 존재하는 인터프리터를 지정하는지 확인합니다. 파일이 Unix 줄바꿈을 사용하는지 확인합니다. 마지막 항목은 file에서 "with CRLF line terminators"로 표시됩니다. 이 경우 인터프리터 이름이 /bin/bash\r로 변환되어 커널이 실행을 거부합니다.
서비스가 시작된 직후 중지되는 이유는 무엇입니까?
unit 파일이 프로그램에 실제로 없는 동작을 지정하고 있기 때문입니다. Type=simple를 사용하면 systemd는 프로그램이 foreground에서 계속 실행되기를 기대합니다. 따라서 daemon이 background로 fork하면 fork하는 즉시 종료된 것으로 인식합니다. Type=forking을 사용하면 systemd는 첫 번째 프로세스가 종료될 때까지 기다립니다. 따라서 foreground 프로그램을 사용하면 TimeoutStartSec=이 만료될 때까지 start job이 멈춘 것처럼 보입니다. Type=을 프로그램의 동작에 맞추고, 프로그램이 foreground flag를 제공한다면 기본값인 Type=simple와 함께 해당 flag를 사용합니다.
짧은 상태 출력이 아닌 실제 오류를 확인하려면 어떻게 합니까?
systemctl status은 journal의 마지막 몇 줄만 출력하고 긴 줄은 잘라냅니다. journalctl -u myapp.service -b --no-pager을 실행하면 현재 부팅에서 unit이 기록한 전체 내용을 확인할 수 있습니다. 최신 200줄만 유지하려면 -n 200를 추가하거나, 출력을 grep으로 pipe합니다. 애플리케이션이 자체 log file에 기록한다면 해당 파일도 확인해야 합니다. systemd는 프로그램이 standard output과 standard error로 보낸 내용만 수집하기 때문입니다.
오류 메시지 없이 unit이 inactive 상태인 이유는 무엇입니까?
대부분은 Condition* directive가 unit을 건너뛰었기 때문입니다. 이러한 검사는 조용히 수행됩니다. condition이 실패해도 start job은 성공으로 표시됩니다. systemctl show myapp.service -p ConditionResult를 실행하고 ConditionResult=no을 찾은 다음, 해당 검사를 명시하는 journal 줄을 확인합니다. 또 다른 일반적인 원인은 masked unit입니다. masked unit은 sudo systemctl unmask이 해제할 때까지 모든 start 요청을 거부합니다.
unit 파일을 변경할 때마다 daemon-reload가 필요합니까?
unit 파일이나 drop-in을 수정했다면 필요합니다. sudo systemctl daemon-reload은 systemd가 디스크의 파일을 다시 읽도록 하고, sudo systemctl restart myapp.service은 변경된 설정을 실행 중인 서비스에 적용합니다. systemctl edit 뒤에는 필요하지 않습니다. 이 명령이 자동으로 reload를 수행하기 때문입니다. 또한 systemd가 아닌 애플리케이션에 속한 configuration file을 변경한 경우에도 필요하지 않습니다.