Linux systemd 서비스 등록하면서 꼭 확인해야 할 체크리스트

제가 Linux 서버에 systemd 서비스를 등록하면서 생각보다 삽질을 많이 했어요. 서비스가 안 올라가거나, 재시작이 안 되거나, 설정이 먹히지 않는 경우가 한두 번이 아니었거든요. 그래서 이 글에서는 제가 직접 부딪히고 해결한 경험을 바탕으로, 꼭 확인해야 하는 체크리스트들을 정리해봤습니다.

service 파일 작성부터 등록, 재시작, 권한 문제까지 실제로 제가 겪은 문제 중심으로 차근차근 말씀드릴게요.

개발 환경 / 버전 정보

제가 작업한 환경은 Ubuntu 22.04 LTS이며, systemd 버전은 systemd 249.11입니다. 기본적으로 root 권한 또는 sudo 권한이 필요하니 권한 문제도 함께 체크했습니다.

systemd 서비스 파일 작성할 때 이렇게 하면 됩니다

가장 먼저 서비스 정의 파일을 작성하는데요, 위치는 보통 /etc/systemd/system/에 넣습니다. 여기서 파일 이름은 보통 your-service-name.service로 지정해요.

[Unit]
Description=My Custom Service
After=network.target

[Service]
Type=simple
User=myuser
ExecStart=/usr/bin/myapp --option
Restart=on-failure

[Install]
WantedBy=multi-user.target

여기서 꼭 확인할 것들은 다음과 같아요. Type 지정이 기본적으로 simple인데, 만약 데몬이 별도의 프로세스를 띄우면 forking 타입을 써야 해요. User 권한도 꼭 체크해야 하구요.

✅ 꼭 확인해야 할 systemd 등록 체크리스트

• 서비스 파일 위치: /etc/systemd/system/에 저장했는지, 혹은 /lib/systemd/system/가 아닌지 확인했나요?
• 파일 권한: 서비스 파일 권한이 644여야 하고, 소유자는 root인지 확인하세요.
• ExecStart 경로: 절대 경로를 꼭 써야 하고, 실행 파일에 실행 권한(chmod +x)이 있는지 확인하세요.
• User 지정: root가 아니면 해당 유저 권한으로 실행 가능한 환경(파일 권한, 환경 변수 등)인지 점검합니다.
• Type 설정: 데몬인지 단순 실행인지에 따라 Type=simple 혹은 forking 등으로 정확히 설정했나요?
• 종속성: After=network.target 같은 필요한 타겟이 정확히 지정되어 있어야 합니다.
• Reload 명령어: 서비스 변경 후 sudo systemctl daemon-reload를 꼭 실행했나요?
• 서비스 활성화: sudo systemctl enable your-service 명령어로 부팅시 자동 시작 설정을 했는지 점검하세요.

실제 제가 막혔던 부분과 해결 과정

사실 가장 많이 헷갈린 게 서비스가 멈췄는데 왜 재시작이 안 되지? 였어요. 로그를 봤더니 이런 메시지가 떴거든요.

Failed to start my-service.service: Unit my-service.service not found.

이 에러는 서비스를 등록한 후 daemon-reload를 안 한 경우에 뜨더라고요. 그래서 sudo systemctl daemon-reload를 실행하고 다시 start 하니까 바로 해결됐어요.

또 한 가지는 Permission denied 오류였는데, 서비스가 실행할 파일 권한 문제였어요. 꼭 실행 파일에 chmod +x를 해줘야 하더라고요.

막힌 부분 직접 고친 코드 예시

서비스 파일에서 ExecStart 경로를 절대 경로로 바꾸고, 권한 설정한 예시입니다.

[Unit]
Description=My Custom Service
After=network.target

[Service]
Type=simple
User=myuser
ExecStart=/home/myuser/myapp/start.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target

start.sh 파일에 실행 권한 부여:

chmod +x /home/myuser/myapp/start.sh

이렇게 하니까 실행 권한 문제도 해결됐고, 서비스가 제대로 올라갔어요.

이 부분에서 많이들 틀립니다

많은 분들이 Restart=on-failure 옵션이 있다고 무조건 자동 재시작 된다고 생각하는데, 제 경우엔 Type=forking을 안 맞게 설정해서 재시작이 안 되더라고요. 이 부분은 서비스의 프로세스 생성 방식을 정확히 파악하고 설정해야 합니다.

그리고 User를 지정했을 때는 해당 유저가 실행할 환경 변수나 권한 문제를 반드시 점검해야 해요. 서비스 로그를 꼼꼼히 journalctl -u your-service로 확인하는 게 필수입니다.

자주 물어보시는 것들

Q. 서비스 파일 수정했는데 재시작해도 변경사항이 반영이 안돼요. 왜 그럴까요?

A. 항상 sudo systemctl daemon-reload 명령어를 실행해서 systemd가 변경된 설정을 다시 읽도록 해야 합니다. 이걸 빼먹으면 재시작해도 예전 설정 그대로 실행돼요.

Q. 서비스가 부팅 시 자동 시작이 안 되네요. 뭐가 문제일까요?

A. sudo systemctl enable your-service 명령어로 서비스가 부팅 시 자동으로 시작되게 설정해야 합니다. 그리고 WantedBy=multi-user.target 같은 타겟이 적절히 지정되어 있어야 해요.

Q. 로그를 보니 Permission denied 에러가 뜹니다. 어떻게 해결하나요?

A. 실행 파일 및 스크립트에 실행 권한이 있는지, 그리고 서비스가 실행되는 유저가 해당 파일에 접근 가능한지 chmod와 chown 명령어로 확인하세요.

체크리스트만 잘 확인해도 대부분의 문제는 금방 해결됩니다. 특히 daemon-reload와 권한 문제, 실행 경로 부분은 꼭 놓치지 마세요. systemd 서비스 등록이 조금 까다로울 수 있지만, 이 글과 제 경험담이 도움이 될 거예요.