Infograb logo
Teleport Connect 사용

Teleport Connect는 SSH 서버, 데이터베이스, 애플리케이션 및 Kubernetes 클러스터에 대한 쉽고 안전한 액세스를 제공합니다.

설치 및 업그레이드

가장 최근 버전을 다운로드하려면 Downloads 페이지로 가십시오. Teleport Connect는 macOS, Linux 및 Windows를 지원합니다.

다운로드한 .dmg 파일을 두 번 클릭하고 Teleport Connect 아이콘을 Applications 폴더로 드래그하십시오.

Teleport Connect를 새 버전으로 업그레이드하려면 새 버전을 Applications 폴더로 드래그하십시오.

DEB (Debian 기반 배포판) 또는 RPM (RHEL 기반 배포판) 패키지를 다운로드하고 패키지 관리자를 사용하여 설치하십시오. 제자리 업그레이드를 위해 이 과정을 반복하십시오.

프로젝트를 tar.gz 파일로 다운로드하여 추출하고 제자리에 실행할 수도 있습니다:

tar -xf teleport-connect-17.0.0-dev-linux-*.tar.gz

설치 프로그램 .exe 파일을 다운로드하고 실행하십시오. 추가 사용자 입력 없이 Teleport Connect를 설치하고 열 것입니다.

업그레이드를 위해 최신 버전으로 이 과정을 반복하십시오.

/S 플래그와 함께 설치 프로그램을 실행하여 무음 설치를 수행할 수 있습니다. 이는 진행 표시줄을 숨기고 설치가 완료된 후 앱을 시작하는 것을 건너뜁니다.

"Teleport Connect Setup-17.0.0-dev.exe" /S

사용자 인터페이스

Teleport Connect의 상단 바는 다음으로 구성됩니다:

  • 프로필 선택기 (오른쪽 상단): 다양한 Teleport 클러스터에서 프로필을 전환하고 클러스터에 로그인하거나 로그아웃할 수 있습니다.
  • 연결 목록 (왼쪽 상단): 최근 연결을 표시하여 원활하게 전환할 수 있습니다.
  • 검색창 (중앙): 클러스터 전반에 걸쳐 리소스를 검색할 수 있습니다.
  • 클러스터 선택기 (검색창 왼쪽): 신뢰할 수 있는 클러스터를 설정하고 루트 클러스터에 연결된 리프 클러스터가 있을 때만 표시됩니다. 리프 클러스터 리소스를 탐색할 수 있습니다. 또한, "새 터미널 열기" 작업은 선택한 클러스터에 새 터미널 탭을 바인딩합니다.
  • 추가 작업 메뉴 (프로필 선택기 왼쪽): 구성 파일 열기 또는 엔터프라이즈 클러스터에서 액세스 요청 생성과 같은 옵션이 포함되어 있습니다.

하단의 상태 표시줄은 왼쪽 하단에 클러스터 탐색 경로를 표시하여 현재 탭이 바인딩된 클러스터를 나타내며, 오른쪽 하단에는 피드백 공유 버튼이 있습니다.

SSH 서버에 연결하기

  1. 탭 바의 오른쪽 끝에 있는 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T 를 눌러도 같은 결과를 얻을 수 있습니다.
  2. 연결하려는 SSH 서버를 찾아서 연결 버튼을 클릭하십시오.
  3. 로그인할 SSH 사용자를 선택하거나 입력하고 Enter 를 누르십시오.

선택한 서버에서 셸 세션이 있는 새 탭이 열립니다.

대안으로, 검색창에서 서버를 찾아 Enter 를 눌러 연결할 수도 있습니다.

로컬 터미널 열기

로컬 셸 세션으로 터미널을 열려면 추가 작업 메뉴에서 "새 터미널 열기"를 선택하거나 Ctrl+Shift+` 키를 누릅니다.

탭 내에서 실행되는 모든 tsh 명령은 현재 클러스터를 대상으로 합니다. Teleport Connect는 이 세션에 대해 환경 변수 TELEPORT_PROXYTELEPORT_CLUSTER 를 설정하여 이를 수행합니다. 추가로, Teleport Connect는 tsh 바이너리가 포함된 디렉토리를 세션의 PATH 환경 변수에 추가합니다. 이는 tsh가 전역적으로 사용 가능하지 않더라도 적용됩니다.

신뢰할 수 있는 클러스터를 사용할 경우, 클러스터 선택기를 통해 셸 세션이 바인딩될 클러스터를 결정할 수 있습니다. 선택한 클러스터는 탭 제목과 상태 표시줄 모두에 반영됩니다.

터미널 셸 변경

기본적으로 Teleport Connect는 macOS/Linux에서는 사용자 셸을, Windows에서는 PowerShell을 시작합니다. 다른 셸로 전환하려면 터미널 탭(로컬 터미널 또는 Kubernetes 세션)에 마우스 오른쪽 버튼을 클릭합니다. 메뉴에서 미리 정의된 셸(Windows의 경우) 또는 사용자 정의 셸의 경로를 입력합니다.

선택한 셸은 해당 탭에서만 사용되며 기본값으로 설정하지 않는 한 다른 탭에는 적용되지 않습니다.

Windows에서 Teleport Connect의 터미널 셸 변경

구성은 terminal.shellterminal.customShell 구성 속성 아래에 저장됩니다. 자세한 내용은 구성 섹션을 참조하십시오.

Kubernetes 클러스터에 연결

  1. 탭 바의 오른쪽 끝에 있는 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다.
    동일한 결과를 얻으려면 Ctrl+Shift+T/Cmd+T 를 누를 수도 있습니다.
  2. 연결할 클러스터를 찾고 연결 버튼을 클릭합니다.

또는 검색창에서 클러스터를 찾고 Enter 를 눌러 연결할 수 있습니다.

새 로컬 터미널 탭이 열리며, 지정된 클러스터에 대해 KUBECONFIG 환경 변수가 설정됩니다. KUBECONFIG 환경 변수를 존중하는 모든 도구(kubectl , helm 등)는 추가 구성 없이 작동합니다. 다른 도구에서 사용할 이 구성을 식별하려면 KUBECONFIG 환경 변수의 값을 확인하십시오.

KUBECONFIG 환경 변수의 값은 앱 재시작 간에 지속되지만, Kubernetes 클러스터가 왼쪽 상단의 연결 목록에서 제거되거나 Teleport Connect가 닫힐 경우 이 구성 파일은 사용 가능하지 않습니다.

데이터베이스에 연결

  1. 탭 바 끝에 있는 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다.
    동일한 결과를 얻으려면 Ctrl+Shift+T/Cmd+T 를 누를 수도 있습니다.
  2. 연결할 데이터베이스 서버를 찾고 연결 버튼을 클릭합니다.
  3. 사용하려는 데이터베이스 사용자를 선택하거나 입력한 후 Enter 를 누릅니다.

새 탭이 열리며 귀하의 장치와 데이터베이스 서버 간의 새로운 연결이 설정됩니다.

또는 검색창에서 데이터베이스를 찾고 Enter 를 눌러 연결할 수 있습니다.

이 연결은 연결 종료 버튼을 클릭하거나 Teleport Connect를 닫을 때까지 활성 상태로 유지됩니다. 포트 번호는 앱 재시작 간에 지속됩니다. 따라서 포트가 갑자기 변경되는 것에 대한 걱정 없이 선호하는 클라이언트를 설정할 수 있습니다.

GUI 클라이언트를 사용하여

GUI 클라이언트를 사용하여 연결하려면, 데이터베이스 연결 탭 아래의 GUI로 연결 섹션의 지침을 따르십시오.

CLI 클라이언트를 사용하여

데이터베이스 연결 탭에서는 데이터베이스에 연결하는 데 사용할 수 있는 명령어를 보여줍니다. 연결의 데이터베이스 이름을 수정한 후, 실행 버튼을 클릭하여 해당 명령이 실행된 새 터미널 탭을 엽니다.

애플리케이션에 연결하기

Teleport Connect는 브라우저에서 애플리케이션을 실행할 수 있도록 지원하며, 웹 및 TCP 애플리케이션을 위한 인증된 터널을 생성합니다.

Application Access로 보호된 클라우드 API의 경우, Teleport Connect는 브라우저에서 AWS 콘솔을 실행할 수 있지만, 다른 CLI 애플리케이션은 로컬 터미널 탭에서 tsh를 통해서만 사용할 수 있습니다.

브라우저에서 애플리케이션 실행하기

Teleport Connect는 브라우저에서 웹 앱을 열 수 있습니다. 브라우저와 Teleport Connect는 인증 데이터를 공유하지 않으므로, 앱에 접근하기 전에 웹 UI에 로그인해야 합니다.

  1. 탭 바의 끝에 있는 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T 를 눌러서도 동일한 결과를 얻을 수 있습니다.
  2. 열고자 하는 애플리케이션을 찾아 실행 버튼(웹 앱 및 AWS 콘솔) 또는 로그인 버튼(SAML 앱)을 클릭합니다.

대안으로, 검색창에서 애플리케이션을 찾아 Enter 를 눌러 브라우저에서 실행할 수 있습니다.

macOS에서 VNet을 사용하여 TCP 앱에 연결하기

VNet은 Teleport Connect에서 사용할 수 있는 가상 네트워크 에뮬레이션 도구입니다. 이 도구는 컴퓨터에서 실행 중인 모든 프로그램이 Teleport에 의해 보호된 TCP 애플리케이션에 연결할 수 있도록 하며, 프로그램 자체에는 추가적인 변경이 필요하지 않습니다. TCP 애플리케이션을 위한 터널을 수동으로 생성할 필요가 없습니다.

이는 TCP 앱에 연결하는 권장 방법입니다.

  1. Teleport 클러스터에 로그인합니다.
  2. VNet 옆의 연결 아이콘을 클릭하여 연결 목록을 엽니다.
  3. 이제 정규 공용 주소를 통해 TCP 앱에 접근할 수 있습니다.

VNet은 사용자 인증서를 사용하여 연결을 자동으로 인증합니다. 더 많은 세부사항은 VNet 사용하기를 참조하십시오.

인증된 터널 만들기

Teleport Connect는 장치의 임의의 포트에서 인증된 터널을 설정할 수 있습니다. 그 터널로 이루어진 모든 연결은 귀하의 자격 증명으로 인증됩니다.

HTTP API에 접근해야 하는 경우(주소가 https://로 시작하는 웹 앱으로 Teleport에 추가된 경우), 장치에 대한 관리자 권한이 없거나 VNet이 시스템에서 사용할 수 없는 경우 이 방법을 사용하십시오.

  1. 탭 바의 끝에 있는 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T 를 눌러서도 동일한 결과를 얻을 수 있습니다.
  2. 연결하려는 애플리케이션을 찾습니다.
    • TCP 애플리케이션의 경우, 연결 버튼을 클릭합니다.
      • macOS에서는 대신 세 개의 점을 클릭하고 "로컬 포트에 연결"을 선택합니다.
    • 웹 애플리케이션의 경우, 실행 버튼 옆의 세 개의 점을 클릭하고 "연결 설정"을 선택합니다.

대안으로, Windows와 Linux에서는 검색창에서 TCP 애플리케이션을 찾고 Enter 를 눌러 그에 대한 연결을 설정할 수 있습니다.

새로운 탭이 열리면서 귀하의 장치와 애플리케이션 사이에 새로운 연결이 설정됩니다.

이 연결은 연결 종료 버튼을 클릭하거나 Teleport Connect를 닫을 때까지 활성 상태로 유지됩니다. 포트 번호는 애플리케이션을 재시작해도 유지됩니다. 포트가 갑자기 변경될 걱정 없이 좋아하는 클라이언트를 설정할 수 있습니다.

애플리케이션 연결 탭은 애플리케이션에 쿼리하는 데 사용할 수 있는 예제 명령을 보여줍니다. 표시된 주소에서 전송된 요청은 인증된 터널을 통해 애플리케이션으로 프록시됩니다.

여러 클러스터에 연결하기

Teleport Connect를 사용하면 여러 클러스터에 동시에 로그인할 수 있습니다. 첫 번째 클러스터에 로그인한 후 오른쪽 상단의 프로필 선택기를 열고 +Add another cluster 버튼을 클릭하세요. 여러 가지 방법으로 활성 프로필 간에 전환할 수 있습니다:

  1. 오른쪽 상단의 프로필 선택기 버튼을 클릭합니다.
  2. 단축키 (Ctrl+Shift+I/Cmd+I )로 프로필 선택기를 엽니다.
  3. 연결 목록에서 연결을 선택하여 자동으로 올바른 프로필로 전환합니다.

현재 Teleport Connect는 클러스터당 하나의 사용자만 지원합니다. 다른 사용자로 로그인하려면 먼저 클러스터에서 로그아웃해야 합니다.

재시작 및 재연결

Teleport Connect를 닫기 전에 세션 종료 시 열려 있었던 탭을 기억합니다. 다음에 앱을 열면, Connect는 이러한 탭을 다시 열려면 원하는지 물어봅니다. 동의하면, Connect는 앱을 닫기 전 활성화된 모든 자원에 대한 연결을 복원합니다.

터미널 탭을 복원할 때, Teleport Connect는 앱이 종료될 때 진행 중이던 명령을 재실행하려고 하지 않습니다. 해당 탭의 작업 디렉토리만 복원합니다.

내 컴퓨터 연결

내 컴퓨터 연결을 통해 몇 번의 클릭만으로 개인 컴퓨터를 Teleport 클러스터에 추가할 수 있습니다.

Teleport의 기능을 탐색하든, Teleport가 지원하는 홈 랩에서 사용할 수 있도록 하든, 클러스터에 컴퓨터를 추가하는 가장 쉬운 방법입니다.

내 컴퓨터 연결은 터미널을 사용하지 않고 Connect에 의해 완전히 관리되는 Teleport 에이전트를 설정할 수 있습니다. 또한 에이전트의 수명 주기를 제어하기 위해 systemctl 과 같은 도구가 필요하지 않습니다.

전제 조건

  • macOS 또는 Linux 장치.
  • Teleport Connect v14.1+, Teleport Proxy 서비스 버전과 동일한 주요 버전 또는 한 단계 이전 버전. 버전 호환성을 참조하십시오.
  • 로컬 Teleport 사용자: 자격 증명 또는 비밀번호 없는 로그인으로 인증해야 하며, SSO로는 인증할 수 없습니다.
  • 조인 토큰을 생성할 수 있는 권한 (자원 token 에 대한 동사 create ).
  • 백엔드에서 사용자 객체를 읽고 업데이트할 수 있는 권한 (자원 [user](../reference/access-controls/roles.mdx)에 대해 readupdate 동사).
  • 백엔드에서 역할을 읽고, 업데이트하고, 생성할 수 있는 권한 (자원 [role](../reference/access-controls/roles.mdx)에 대해 read , update , 및 create 동사).

에이전트는 현재 시스템 사용자로 실행되며, 루트로 실행되지 않습니다. 따라서 다른 시스템 사용자로 로그인하거나 호스트 사용자 생성과 같은 일부 기능은 사용할 수 없습니다.

설정 및 사용 방법

설정을 시작하려면 왼쪽 상단의 노트북 아이콘을 클릭하고 "내 컴퓨터 연결"을 선택하세요. 새로운 탭이 상호작용 없이 설정을 안내합니다. "연결"을 클릭하여 설정을 시작하세요.

상단 바의 내 컴퓨터 연결

설정은 현재 시스템 사용자로서 장치에 대한 액세스를 부여하는 새로운 역할을 클러스터에 생성합니다. 그런 다음 역할이 사용자 객체에 추가됩니다.

Warning

이 역할은 Connect My Computer에 의해 관리되는 노드에 대한 시스템 사용자로서의 SSH 액세스를 부여하는 것에만 책임이 있습니다. 노드는 클러스터의 다른 SSH 노드와 마찬가지로 RBAC의 적용을 받습니다.

이것은 관리 권한이 있는 사용자가 노드에 대한 액세스를 부여하는 또 다른 역할을 사용자 정의하거나, Connect My Computer 역할을 자신에게 부여하는 방식으로 이루어질 수 있음을 의미합니다.

Connect My Computer는 다른 사용자가 노드에 접근할 수 없다고 가정하는 시나리오에서만 사용하시기 바랍니다. 예를 들어 Teleport 클러스터를 단독 사용자로 탐색하는 경우나 홈 랩에서 사용 시에 적합합니다.

다음으로, 설정은 사용자의 플랫폼에 맞는 Teleport 에이전트를 다운로드하고 현재 클러스터를 향해 teleport node configure 를 실행합니다. 완료되면, Connect My Computer는 에이전트를 시작하고 클러스터에서 SSH 노드로 나타나기를 기다립니다.

내 컴퓨터 연결 설정

에이전트가 클러스터에 조인한 후, 탭은 에이전트의 상태를 표시하도록 전환됩니다. 여기에서 에이전트가 제공하는 노드에 연결하고, 에이전트를 중지 및 시작하며, 완전히 제거할 수 있습니다. 클러스터에서 수동으로 로그아웃하면 에이전트도 제거됩니다.

내 컴퓨터 연결 상태

Teleport Connect가 열려 있는 동안 귀하의 컴퓨터는 공유됩니다. 공유를 중지하려면 Teleport Connect를 닫거나 내 컴퓨터 연결 탭을 통해 에이전트를 중지하세요. 앱을 다시 시작하면 공유가 재개되지만, 종료하기 전에 에이전트를 중지하면 안 됩니다. Teleport Connect가 예기치 않게 충돌하면 에이전트는 즉시 중지됩니다.

에이전트 유지 관리

Teleport Connect에서 다운로드한 에이전트의 버전은 항상 Teleport Connect의 버전과 일치합니다. Teleport Connect를 업그레이드한 후, Connect My Computer는 에이전트를 시작하기 전에 일치하는 에이전트 버전을 자동으로 다운로드하려고 시도합니다.

Connect My Computer는 디스크에 항상 단일 버전의 에이전트만 저장합니다.

에이전트는 ~/Library/Caches/Teleport Connect/teleport/teleport 에 저장됩니다.

기본적으로 에이전트는 ~/.cache/Teleport Connect/teleport/teleport 에 저장됩니다. 경로는 $XDG_CACHE_HOME 을 준수합니다.

Connect My Computer 문제 해결

에이전트 로그에 접근하기

설정이 완료된 후, Connect My Computer 탭을 열고, 탭 내의 세 점 메뉴에서 "에이전트 로그 디렉토리 열기"를 선택합니다.

로그는

~/Library/Application Support/Teleport Connect/agents/<cluster>/logs

에 저장됩니다.

로그는 ~/.config/Teleport Connect/agents/<cluster>/logs에 저장됩니다.

Connect My Computer 아이콘이 상단 바에 표시되지 않음

아이콘은 설정이 다음 요구 사항을 충족할 때만 표시됩니다:

  • macOS 또는 Linux 장치.
  • Teleport Connect v14.1+, Teleport Proxy 서비스 버전과 동일한 주요 버전 또는 한 단계 이전 버전. 버전 호환성을 참조하십시오.
  • 로컬 Teleport 사용자: 자격 증명 또는 비밀번호 없는 로그인으로 인증해야 하며, SSO로는 인증할 수 없습니다.
  • 조인 토큰을 생성할 수 있는 권한 (자원 token 에 대한 동사 create ).

Connect My Computer 탭에 에이전트가 실행 중이라고 표시되지만 컴퓨터가 클러스터에 표시되지 않음

Connect My Computer 탭에서 "연결"을 클릭하십시오. 새 탭의 오류 메시지가 "접근이 거부됨"이라고 나타나면, 클러스터 사용자의 역할 중 하나가 Connect My Computer 노드에 대한 접근을 거부하고 있을 가능성이 높습니다. 특정 로그인이나 필드 node_labels 를 통해 노드에 대한 접근을 거부할 수 있습니다. 이 문제를 해결하려면, 웹 UI의 관리 섹션에서 역할 목록을 검사하십시오. 먼저 사용자 객체에 할당된 역할을 확인한 다음 각 역할을 검사하십시오. 광범위한 deny 규칙이 있는 역할을 찾으십시오.

오류 메시지에 노드 또는 터널이 발견되지 않았다고 언급되면, 클러스터가 에이전트의 캐시된 뷰를 가지고 있지만 에이전트가 아직 클러스터에 조인하지 않았음을 의미합니다. 몇 초 동안 기다렸다가 노드에 다시 연결해보십시오. 문제가 지속되면 에이전트 로그를 확인하십시오.

시스템 사용자 이름 변경 후 Connect My Computer 작동하지 않음

Connect My Computer를 구성할 당시 사용한 시스템 사용자 이름은 연결된 클러스터 사용자에 대한 Connect My Computer 역할에 보존됩니다. Connect My Computer 노드에 접근을 다시 얻으려면, 역할의 logins 섹션에 새 시스템 사용자 이름을 추가하십시오. 역할은 connect-my-computer-<클러스터 사용자 이름> 형식의 이름으로 식별할 수 있습니다.

또 다른 해결 방법은 설정을 다시 시작하는 것입니다.

에이전트가 클러스터에 조인할 수 없고 로그에 토큰 유효 기간 만료 또는 발견되지 않음

이 경우, 에이전트가 시작될 때 다음과 같은 로그를 출력합니다:

INFO [PROC:1]    Joining the cluster with a secure token. pid:54364.1 service/connect.go:460
INFO [AUTH]      Attempting registration via proxy server. auth/register.go:279
ERRO [PROC:1]    Can not join the cluster as node, the token expired or not found. Regenerate the token and try again. pid:54364.1 service/connect.go:106

설정 중에 Connect My Computer는 클러스터에 조인하기 위해 유효 기간이 최대 5분인 조인 토큰을 생성합니다. 로그에 토큰이 만료되었다고 표시되면, 이는 클러스터에 조인하려는 첫 번째 시도가 실패하고 그 후에 5분이 지나서 또 다른 시도를 시작했음을 의미합니다.

이 문제를 해결하려면 에이전트를 제거하고 설정을 다시 수행하십시오.

설정 다시 시작하기

Teleport 노드는 완전히 무상태이기 때문에, 에이전트를 시작하거나 클러스터에 조인하는 데 문제가 발생한 경우 설정을 다시 실행해 볼 수 있습니다. 설정이 실패한 경우 "Retry"를 클릭하거나 에이전트가 성공적으로 구성된 후 "Connect My Computer" 탭 내의 세 점 메뉴에서 "Remove agent"를 선택하십시오.

Connect My Computer에 대한 사용자 접근 방지

클러스터 사용자가 "Connect My Computer"를 사용하지 못하도록 하려면, 새로운 조인 토큰을 생성할 수 있는 권한이 없도록 해야 합니다. 이는 token 리소스에 대한 create 동사로 제어됩니다. 이 권한을 명시적으로 거부하거나 처음부터 부여하지 마십시오. 자세한 내용은 Access Controls Reference Documentation를 참조하십시오. 이 권한을 거부하면 상단 바에서 아이콘이 숨겨집니다.

이미 에이전트를 설정한 사용자는 조인 토큰 생성 권한이 거부된 후에도 해당 에이전트를 관리할 수 있습니다. 이는 악의적인 관리자가 사용자가 에이전트를 설정하게 한 다음 사용자를 에이전트 제거에서 잠기게 하지 못하도록 하기 위함입니다.

클러스터에 이미 조인한 에이전트에 대한 접근을 즉시 철회하려면, teleport.dev/connect-my-computer/owner 레이블이 붙은 노드를 찾아서 해당 노드에 잠금을 설정하십시오.

tctl nodes ls -v --query='labels["teleport.dev/connect-my-computer/owner"] != ""'
tctl lock --server-id=Node UUID --message="Using Connect My Computer is forbidden"

Teleport Connect 외부에서 tsh 사용하기

Teleport Connect는 자체 번들 버전의 tsh를 제공합니다. Teleport Connect는 애플리케이션 내에서 수행되는 모든 작업에 대해 항상 이 버전의 tsh를 사용합니다.

Teleport Connect는 선택한 터미널에서 tsh를 사용할 수 있도록 합니다. 현재 tsh와 Teleport Connect는 서로 다른 프로필 세트를 사용하고 있으므로 주의하십시오. Teleport Connect는 환경 변수 TELEPORT_HOME 를 통해 사용자 정의 홈 위치를 설정합니다. 예를 들어, tsh를 통해 새로운 클러스터에 로그인해도 해당 클러스터는 Teleport Connect에 표시되지 않습니다.

tshPATH 에 추가하려면, 추가 작업 메뉴를 열고 "Install tsh in PATH"를 선택하십시오. 이렇게 하면 tsh가 /usr/local/bin 에 심볼릭 링크로 연결됩니다. "Remove tsh from PATH"를 선택하여 심볼릭 링크를 제거할 수 있습니다.

이전에 tsh macOS .pkg 설치 프로그램을 사용한 경우, 이 작업은 해당 설치 프로그램에 의해 생성된 심볼릭 링크를 덮어씁니다.

설치 중 Teleport Connect는 teleport 패키지를 이미 설치하지 않은 경우 /usr/local/bin/tsh 에 tsh에 대한 심볼릭 링크를 자동으로 추가합니다.

설치 중 Teleport Connect는 설치 디렉토리의 resources\bin 폴더를 Path 사용자 환경 변수에 자동으로 추가합니다.

하드웨어 키 지원

Teleport Connect는 하드웨어 기반 키로 인증하는 기능을 지원합니다. 키는 하드웨어 장치에 직접 생성 및 저장되어, 파일 시스템에 저장하는 것보다 더 큰 보안을 제공합니다. 자세한 내용은 하드웨어 키 지원 가이드를 참조하십시오.

PIV 지원

하드웨어 키 지원은 사용자가 PIV 호환 하드웨어 키를 사용해야 합니다. 현재 이 기능은 YubiKey 시리즈 5+를 보장하여 지원합니다.

하드웨어 키로 로그인하려면, 역할 또는 클러스터 구성이 이를 활성화해야 합니다. 강제 적용되면, Teleport Connect는 하드웨어 키가 연결되어 있어야 하며, 탭과/또는 PIV PIN을 요청할 수 있습니다:

처음 로그인할 때 즉시 다시 로그인을 요청받습니다.

키가 기본 PIV PIN으로 설정되어 있는 경우, 이 단계에서 변경하라는 요청을 받을 수 있습니다. 기본 또는 빈 PIN을 입력하면 업데이트를 위한 대화 상자가 열립니다.

구성

Teleport Connect는 처음 실행할 때 생성되는 app_config.json 파일을 편집하여 구성할 수 있습니다.
구성 파일을 열려면 추가 작업 메뉴에서 "구성 파일 열기"를 선택합니다.
파일은 기본 편집기에서 열립니다.

참고

구성 파일에 대한 변경 사항은 다음 실행 시에 적용됩니다.

아래는 지원되는 구성 속성 목록입니다.

속성기본값설명
themesystem앱의 색상 테마. 사용 가능한 모드: light , dark , system .
terminal.fontFamilymacOS에서는 Menlo, Monaco, monospace
Windows에서는 Consolas, monospace
Linux에서는 'Droid Sans Mono', monospace
터미널의 글꼴 패밀리입니다.
terminal.fontSize15터미널의 글꼴 크기입니다.
terminal.windowsBackendautoauto 는 사용 가능한 경우 현대 ConPTY 시스템을 사용하며, 이는 Windows 10 (19H1) 이상을 요구합니다. ConPTY 사용 가능 시 winpty 로 설정하면 winpty를 사용합니다.
terminal.shellmacOS/Linux의 기본 사용자 셸, Windows의 pwsh.exe /powershell.exe기본 터미널 셸입니다. custom 으로 설정하여 terminal.customShell 에서 셸 경로를 가져올 수 있습니다. UI(터미널 탭에서 마우스 우클릭 > 기본 셸)로 설정하는 것이 가장 좋습니다.
terminal.customShellterminal.shellcustom 으로 설정된 경우 사용되는 사용자 정의 셸의 경로입니다. UI(터미널 탭에서 마우스 우클릭 > 사용자 정의 셸…)로 설정하는 것이 가장 좋습니다.
terminal.rightClickmacOS/Linux에서는 menu
Windows에서는 copyPaste
paste 는 클립보드 콘텐츠를 붙여넣고, copyPaste 는 텍스트가 선택된 경우 복사하고 그렇지 않으면 붙여넣습니다, menu 는 컨텍스트 메뉴를 표시합니다.
terminal.copyOnSelectfalse선택한 텍스트를 클립보드에 자동으로 복사합니다.
usageReporting.enabledfalse익명 사용 데이터를 수집할 수 있도록 활성화합니다 (자세한 내용은 Telemetry 참조).
keymap.tab1 - keymap.tab9macOS에서는 Command+1 - Command+9
Windows에서는 Ctrl+1 - Ctrl+9
Linux에서는 Alt+1 - Alt+9
탭 1–9를 여는 단축키입니다.
keymap.closeTabmacOS에서는 Command+W
Windows/Linux에서는 Ctrl+Shift+W
탭을 닫는 단축키입니다.
keymap.newTabmacOS에서는 Command+T
Windows/Linux에서는 Ctrl+Shift+T
새 탭을 여는 단축키입니다.
keymap.newTerminalTabControl+Shift+` macOS
Ctrl+Shift+` Windows/Linux
새 터미널 탭을 여는 단축키입니다.
keymap.terminalCopymacOS에서는 Command+C
Windows/Linux에서는 Ctrl+Shift+C
터미널에서 텍스트를 복사하는 단축키입니다.
keymap.terminalPastemacOS에서는 Command+V
Windows/Linux에서는 Ctrl+Shift+V
터미널에서 텍스트를 붙여넣는 단축키입니다.
keymap.previousTabmacOS에서는 Control+Shift+Tab
Windows/Linux에서는 Ctrl+Shift+Tab
이전 탭으로 이동하는 단축키입니다.
keymap.nextTabmacOS에서는 Control+Tab
Windows/Linux에서는 Ctrl+Tab
다음 탭으로 이동하는 단축키입니다.
keymap.openConnectionsmacOS에서는 Command+P
Windows/Linux에서는 Ctrl+Shift+P
연결 목록을 여는 단축키입니다.
keymap.openClustersmacOS에서는 Command+E
Windows/Linux에서는 Ctrl+Shift+E
클러스터 선택기를 여는 단축키입니다.
keymap.openProfilesmacOS에서는 Command+I
Windows/Linux에서는 Ctrl+Shift+I
프로파일 선택기를 여는 단축키입니다.
keymap.openSearchBarmacOS에서는 Command+K
Windows/Linux에서는 Ctrl+Shift+K
검색 표시줄을 여는 단축키입니다.
headless.skipConfirmfalseHeadless WebAuthn 승인을 위한 확인 프롬프트를 건너뛰고 즉시 WebAuthn을 요청합니다.
ssh.noResumefalseSSH 연결 재개를 비활성화합니다.
ssh.forwardAgentfalse에이전트 포워딩을 활성화합니다.
sshAgent.addKeysToAgentauto키가 로컬 SSH 에이전트에 추가되는 방식을 제어합니다. "auto"는 에이전트가 SSH 인증서를 지원하는 경우에만 키를 추가하고, "no"는 절대 시도하지 않으며, "yes"는 항상 추가를 시도하고, "only"는 항상 에이전트에 키를 추가를 시도하지만 디스크에 저장하지 않습니다.
참고

구성 파일에 있는 추가 $schema 속성은 텍스트 편집기가 자동 완성을 제공할 수 있도록 합니다. 수정해서는 안 됩니다.

키보드 단축키 구성

유효한 단축키는 최소한 하나의 수정자와 단일 키 코드로 구성되어야 하며, 예를 들어 Shift+Tab 처럼 사용됩니다. F1 과 같은 기능 키는 수정자가 필요하지 않습니다.
수정자와 키 코드는 + 문자를 사용하여 결합해야 합니다.

사용 가능한 수정자:

  • macOS에서는 Control , Option , Shift , Command 입니다.
  • Windows와 Linux에서는 Ctrl , Alt , Shift 입니다.

사용 가능한 키 코드:

  • 0 에서 9
  • A 에서 Z
  • F1 에서 F24
  • ,, ., /, \, `, -, =, ;, ', [, ]
  • Space , Tab , CapsLock , NumLock , ScrollLock , Backspace , Delete , Insert , Enter , Up , Down , Left , Right , Home , End , PageUp , PageDown , Escape , IntlBackslash

텔레메트리

앱을 처음 시작할 때, Teleport Connect는 텔레메트리 데이터를 수집하고 전송할 수 있는 권한을 요청합니다.
여기에는 다음과 같은 이벤트 추적이 포함됩니다:

  • 클러스터에 로그인
  • SSH, 데이터베이스, 애플리케이션 또는 Kubernetes 세션 시작
  • SSH 세션 중 파일 전송
  • 접근 요청 생성
  • 접근 요청 검토
  • 접근 요청 수용

로그인 시, 우리는 몇 가지 장치 관련 데이터도 수집합니다:

  • 운영 체제 및 버전
  • 앱 버전
  • 프로세서 아키텍처

추가로, 우리는 직무 역할에 대한 질문을 합니다(응답은 선택 사항입니다).

이벤트 및 수집된 데이터의 전체 목록은 Teleport 소스의 프로토콜 버퍼 메시지로 정의됩니다.
우리는 이러한 이벤트의 세부 사항을 추적하지 않으며 단지 해당 이벤트가 발생했다는 사실만 기록합니다. 각 이벤트에는 클러스터 이름과 사용자 이름이 포함되며, 클러스터의 내부 무작위 UUID를 키로 사용하여 HMAC으로 익명화됩니다. 특정 클러스터나 사용자와 이를 연관짓는 것은 클러스터의 내부 데이터 저장소에 대한 접근 없이는 불가능합니다.

텔레메트리 비활성화

처음에 텔레메트리 데이터 공유에 동의했으나 이제 옵트 아웃하려면, 구성에서 usageReporting.enabledfalse 로 설정해야 합니다 (자세한 내용은 구성 참조):

"usageReporting.enabled": false

변경 사항은 다음 실행 시 적용됩니다.

문제 해결

앱 상태를 재설정하면 Teleport Connect가 비정상 상태에 빠져 발생하는 UI 충돌에 도움이 될 수 있습니다. 이는 Teleport Connect를 다운그레이드하거나 상당한 서버 측 변경을 수행한 후 발생할 수 있습니다. 이러한 UI 충돌은 일반적으로 빈 창 또는 내부 오류 경고로 나타납니다.

특정 클러스터와 관련된 상태를 재설정하려면:

  1. 클러스터에서 로그아웃합니다.
  2. Teleport Connect를 닫습니다.
  3. Teleport Connect를 열고 클러스터에 다시 로그인합니다.

앱 상태를 완전히 지우려면:

  1. Teleport Connect를 닫습니다.
  2. 내부 tsh 폴더와 app_state.json 파일을 제거하여 모든 클러스터에서 로그아웃하고 모든 기억된 탭 및 연결을 지웁니다.
rm -rf ~/Library/Application\ Support/Teleport\ Connect/ {(tsh, app_state.json)}
rm -rf ~/.config/Teleport\ Connect/{(tsh, app_state.json)}
rmdir /s /q C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\tsh
del C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\app_state.json

문제 제출

문제를 제출하려면, 오른쪽 하단에 있는 피드백 제출 버튼(말풍선 기호)을 클릭하고 버그 제출 링크를 따르십시오.

로그를 첨부해야 하며, 이는 앱 메뉴의 도움말 -> 로그 디렉토리 열기에서 찾을 수 있습니다. 로그는 ~/Library/Application Support/Teleport Connect/logs 에 저장됩니다.

앱 버전은 앱 메뉴의 Teleport Connect -> Teleport Connect 정보에서 확인할 수 있습니다.

자세한 로그를 보려면 --connect-debug 플래그와 함께 Teleport Connect를 실행하십시오:

macOS 오픈 유틸리티 사용:

open -a "Teleport Connect" --args --connect-debug

실행 파일을 직접 실행:

/Applications/Teleport\ Connect.app/Contents/MacOS/Teleport\ Connect --connect-debug

로그를 첨부해야 하며, Alt 키를 눌러 앱 메뉴에 접근한 후 도움말 -> 로그 디렉토리 열기를 선택하여 찾을 수 있습니다. 로그는 ~/.config/Teleport Connect/logs 에 저장됩니다.

앱 버전은 도움말 -> Teleport Connect 정보에서 확인할 수 있습니다.

자세한 로그를 보려면 --connect-debug 플래그와 함께 Teleport Connect를 실행하십시오:

teleport-connect --connect-debug

로그를 첨부해야 하며, Alt 키를 눌러 앱 메뉴에 접근한 후 도움말 -> 로그 디렉토리 열기를 선택하여 찾을 수 있습니다. 로그는 C:\Users\%UserName%\AppData\Roaming\Teleport Connect\logs 에 저장됩니다. 숨겨진 파일 및 폴더를 보기 방식을 조정해야 할 수 있습니다.

앱 버전은 도움말 -> Teleport Connect 정보에서 확인할 수 있습니다.

자세한 로그를 보려면 명령 프롬프트에서 --connect-debug 플래그와 함께 Teleport Connect를 여십시오:

"%LocalAppData%\Programs\teleport-connect\Teleport Connect.exe" --connect-debug

로컬 셸 환경 업데이트

Teleport Connect는 새 셸 세션을 시작할 때가 아니라 앱 재시작 시 로컬 셸 환경을 업데이트하고 캐시합니다. 셸 시작 파일에 새 환경 변수를 추가하는 경우, Connect는 앱을 재시작한 후에만 이를 인식합니다.

TLS 인증서 검증 건너뛰기

Teleport Connect를 불안전 모드로 열 수 있으며, 이는 Teleport Proxy Service와 통신할 때 TLS 인증서 검증을 건너뜁니다. 이는 자체 서명된 인증서가 있는 테스트 환경이나 데모 목적으로 유용합니다. 운영 환경에서는 이 모드를 사용하는 것을 권장하지 않습니다.

불안전 모드에서 앱을 실행하려면 먼저 터미널을 열어야 합니다. 거기에서 다음 두 가지 방법 중 하나로 앱을 실행할 수 있습니다:

macOS 오픈 유틸리티 사용:

open -a "Teleport Connect" --args --insecure

실행 파일을 직접 실행:

/Applications/Teleport\ Connect.app/Contents/MacOS/Teleport\ Connect --insecure

터미널에서 --insecure 플래그와 함께 Teleport Connect를 엽니다:

teleport-connect --insecure

명령 프롬프트에서 --insecure 플래그와 함께 Teleport Connect를 엽니다:

"%LocalAppData%\Programs\teleport-connect\Teleport Connect.exe" --insecure

Teleport Connect 제거

이 명령으로 애플리케이션 디렉토리에서 macOS의 Teleport Connect를 제거합니다:

sudo rm -rf /Applications/Teleport\ Connect.app

로컬 사용자 데이터 디렉토리를 제거하려면:

rm -rf ~/Library/Application\ Support/Teleport\ Connect

Teleport Connect는 제어판의 "앱 및 기능" 섹션에서 제거할 수 있습니다.

참고로, Teleport Connect 바이너리는 %LOCALAPPDATA%\Programs\teleport-connect 에 설치됩니다.

로컬 사용자 데이터 디렉토리를 제거하려면:

$ rmdir /s /q "%APPDATA%\Teleport Connect"

DEB 설치의 경우 APT를 사용하여 Teleport Connect를 제거합니다:

sudo apt remove teleport-connect

RPM 설치의 경우 YUM을 사용하여 Teleport Connect를 제거합니다:

sudo yum remove teleport-connect

tarball을 기반으로 한 설치는 teleport-connect 디렉토리 및 복사/링크된 실행 파일을 제거해야 합니다.

Teleport 원문 보기