macOS에서 Teleport를 launchd 서비스로 실행하기
Teleport v18.11요약
이 가이드에서는 macOS에서 Teleport를 지속적으로 실행되는 launchd 서비스로 구성하는 방법을 설명합니다. 이 페이지는 macOS 서비스 관리에만 초점을 맞추며, 노드 등록이 완료되었고 유효한 /etc/teleport.yaml 구성 파일이 이미 있다고 가정합니다.
이 가이드에서는 macOS에서 Teleport를 지속적으로 실행되는
launchd 서비스로 구성하는 방법을 설명합니다. macOS 머신을 Teleport 노드로
운영하면서 Teleport 데몬이 부팅 시 자동으로 시작되고
클러스터에 계속 연결된 상태를 유지하도록 하려는 관리자를 대상으로 합니다.
이 페이지는 macOS 서비스 관리에만 초점을 맞추며,
노드 등록이 완료되었고 유효한 /etc/teleport.yaml
구성 파일이 이미 있다고 가정합니다. 자세한 내용은
구성 레퍼런스 페이지를 참고합니다.
작동 방식#
launchd 서비스는 Mac이 부팅될 때 Teleport 데몬이
자동으로 시작되고, 예기치 않게 종료되면 다시 시작되도록 보장합니다. 이를 통해
수동 개입 없이 노드가 Teleport 클러스터에 계속 연결된 상태를 유지합니다.
처음 조인에 성공한 후 Teleport는 호스트 아이덴티티를 구성된 data_dir(기본값은 /var/lib/teleport)에
저장합니다. 이후 launchd의 자동 재시작을 포함한 모든 시작에서 Teleport는
저장된 아이덴티티를 사용하여 조인 토큰 없이 클러스터에 다시 연결합니다.
사전 요구사항#
- Mac에
teleport바이너리가 설치되어 있습니다. 설치 방법은 macOS에 Teleport 설치하기를 참고합니다. - 유효한
/etc/teleport.yaml구성 파일이 있고 노드가 클러스터에 성공적으로 조인했습니다. - 다음 명령으로 Teleport가 정상적으로 실행되는지 확인했습니다:
$ sudo teleport start --config=/etc/teleport.yaml
Teleport가 올바르게 시작되는지 확인한 후 launchd를 사용하여
시스템 시작 시 자동으로 실행되도록 구성할 수 있습니다. 이렇게 하면
Teleport가 부팅 시 시작되고, 종료되면 자동으로 다시 시작되며,
노드가 클러스터에 계속 연결된 상태를 유지합니다.
1/4단계. Teleport 바이너리 경로 확인#
공식 Teleport 배포판(예: macOS .pkg 설치 프로그램 또는 공식 tarball)으로 설치한
teleport 바이너리의 위치를 확인합니다:
$ which teleport
# /usr/local/bin/teleport
아래 LaunchDaemon 구성에는 which teleport가 반환한 경로를 그대로 사용합니다.
경로가 올바르지 않으면 서비스를 로드할 수 없습니다.
2/4단계. LaunchDaemon 만들기#
Teleport는 root로 실행되어야 합니다. LaunchAgent가 아닌 LaunchDaemon으로 구성합니다. LaunchAgent는 사용자 세션에서 실행되며 Teleport 서비스에 필요한 권한이 없습니다.
다음 내용으로 /Library/LaunchDaemons/com.teleport.node.plist 파일을
생성합니다. 설치 경로가 다르면 바이너리 경로를 바꿉니다:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.goteleport.node</string>
<key>UserName</key>
<string>root</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/teleport</string>
<string>start</string>
<string>--config=/etc/teleport.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/var/log/teleport.out.log</string>
<key>StandardErrorPath</key>
<string>/var/log/teleport.err.log</string>
</dict>
</plist>
StandardOutPath 및 StandardErrorPath 키는 Teleport 출력을
디스크의 로그 파일로 보냅니다. Teleport는 기본적으로 stderr로 로그를 기록하므로,
이 키가 없으면 서비스가 launchd 아래에서 백그라운드로 실행될 때
로그 출력을 확인할 수 없기 때문에 중요합니다.
공식 배포판에서 재설치한 후 teleport 바이너리 경로가 변경되면
plist의 ProgramArguments 경로를 업데이트하고
서비스를 다시 로드합니다.
3/4단계. 필요한 권한 설정#
LaunchDaemon은 소유자가 root:wheel이고 모드가 644여야 합니다.
권한을 설정하고 plist를 검증합니다:
$ sudo chown root:wheel /Library/LaunchDaemons/com.teleport.node.plist
$ sudo chmod 644 /Library/LaunchDaemons/com.teleport.node.plist
$ sudo plutil -lint /Library/LaunchDaemons/com.teleport.node.plist
4/4단계. 서비스 로드#
macOS 12(Monterey) 이상에서는 bootstrap을 사용하여 서비스를 로드합니다:
$ sudo launchctl bootstrap system /Library/LaunchDaemons/com.teleport.node.plist
$ sudo launchctl enable system/com.teleport.node
$ sudo launchctl kickstart -k system/com.teleport.node
LaunchDaemon이 처음 등록되면 macOS가 “Background Items Added” 알림을 표시합니다. 별도의 조치는 필요하지 않습니다. 시작 시 이 알림을 표시하지 않으려면 System Settings -> General -> Login Items에서 언제든지 이 동작을 관리할 수 있습니다.
plist를 변경한 후 다시 로드하려면 다음을 실행합니다:
$ sudo launchctl bootout system /Library/LaunchDaemons/com.teleport.node.plist
$ sudo launchctl bootstrap system /Library/LaunchDaemons/com.teleport.node.plist
launchd상태를 확인합니다:
$ sudo launchctl print system/com.teleport.node
출력에서 state = running을 확인합니다.
- Teleport 프로세스가 실행 중인지 확인합니다:
$ pgrep -fl 'teleport start'
- 노드가 클러스터에 연결되어 있는지 확인합니다:
$ tsh ls
다음은 문제 해결 팁입니다:
- 상태가
running이 아니면/var/log/teleport.err.log에서 오류를 확인합니다. launchd가 로드 실패를 보고하면ls -la /Library/LaunchDaemons/com.teleport.node.plist로 plist의 소유자와 권한을 확인합니다.- Teleport 프로세스가 시작되었다가 즉시 종료되면
sudo teleport start --config=/etc/teleport.yaml을 직접 실행하여 오류 출력을 확인합니다.
로깅 구성#
Teleport는 기본적으로 stderr로 로그를 기록합니다. 위의 plist 구성은
StandardErrorPath 키를 통해 이 출력을 /var/log/teleport.err.log에 저장합니다.
plist 리디렉션에 의존하지 않고 모든 Teleport 로그를 하나의 파일로 통합하려면
/etc/teleport.yaml에 다음을 추가합니다:
teleport:
log:
output: /var/log/teleport.log
severity: INFO
변경한 후 서비스를 다시 시작합니다:
$ sudo launchctl kickstart -k system/com.teleport.node
teleport.yaml에 log.output을 구성하면 Teleport가
해당 파일에 직접 기록합니다. plist의 StandardErrorPath 파일은 계속 존재하지만
초기 시작 오류와 같이 Teleport의 로거를 거치지 않는 출력만 저장합니다.
문제 해결#
launchd로그에서 오류를 확인합니다:
$ sudo log show --last 5m --predicate 'process == "launchd"' --info
- Teleport가 시작되었지만 곧 실패하면 오류 로그를 tail로 확인합니다:
$ sudo tail -f /var/log/teleport.err.log
다음은 문제 해결 팁입니다:
- plist의 바이너리 경로가
which teleport의 출력과 일치하는지 확인합니다. sudo teleport configure --test /etc/teleport.yaml을 실행하여/etc/teleport.yaml이 존재하고 유효한지 확인합니다.service already loaded가 표시되면 다시 bootstrap하기 전에sudo launchctl bootout system/com.teleport.node를 실행합니다.