InfoGrab DocsInfoGrab Docs

macOS에서 Teleport를 launchd 서비스로 실행하기

요약

이 가이드에서는 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
Important

아래 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 아래에서 백그라운드로 실행될 때 로그 출력을 확인할 수 없기 때문에 중요합니다.

Warning

공식 배포판에서 재설치한 후 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
  1. launchd 상태를 확인합니다:
$ sudo launchctl print system/com.teleport.node

출력에서 state = running을 확인합니다.

  1. Teleport 프로세스가 실행 중인지 확인합니다:
$ pgrep -fl 'teleport start'
  1. 노드가 클러스터에 연결되어 있는지 확인합니다:
$ 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
Note

teleport.yaml에 log.output을 구성하면 Teleport가 해당 파일에 직접 기록합니다. plist의 StandardErrorPath 파일은 계속 존재하지만 초기 시작 오류와 같이 Teleport의 로거를 거치지 않는 출력만 저장합니다.

문제 해결#

  1. launchd 로그에서 오류를 확인합니다:
$ sudo log show --last 5m --predicate 'process == "launchd"' --info
  1. 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를 실행합니다.

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
Important

아래 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 아래에서 백그라운드로 실행될 때 로그 출력을 확인할 수 없기 때문에 중요합니다.

Warning

공식 배포판에서 재설치한 후 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
  1. launchd 상태를 확인합니다:
$ sudo launchctl print system/com.teleport.node

출력에서 state = running을 확인합니다.

  1. Teleport 프로세스가 실행 중인지 확인합니다:
$ pgrep -fl 'teleport start'
  1. 노드가 클러스터에 연결되어 있는지 확인합니다:
$ 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
Note

teleport.yaml에 log.output을 구성하면 Teleport가 해당 파일에 직접 기록합니다. plist의 StandardErrorPath 파일은 계속 존재하지만 초기 시작 오류와 같이 Teleport의 로거를 거치지 않는 출력만 저장합니다.

문제 해결#

  1. launchd 로그에서 오류를 확인합니다:
$ sudo log show --last 5m --predicate 'process == "launchd"' --info
  1. 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를 실행합니다.