Teleport Connect는 SSH 서버, 데이터베이스, 애플리케이션, MCP 서버, Windows 데스크톱, Kubernetes 클러스터에 쉽고 안전하게 접근할 수 있게 해줍니다.

설치 및 업그레이드#

다운로드 페이지에서 최신 버전을 다운로드하세요. Teleport Connect는 macOS, Linux, Windows를 지원합니다.

$ tar -xf  teleport-connect-(=teleport.version=)-linux-*.tar.gz

$ "Teleport Connect Setup-(=teleport.version=).exe" /S

관리형 업데이트#

Teleport Connect는 Teleport 클라이언트 도구 관리형 업데이트를 지원합니다. 클러스터에서 활성화된 경우, 앱은 로그인 시 사용 가능한 업데이트를 확인하고, 자동으로 다운로드하며, 재시작 메시지를 표시합니다. Windows와 Linux에서는 설치를 완료하기 위해 관리자 자격 증명을 입력해야 할 수 있습니다.

추가 작업 메뉴의 "업데이트 확인…"을 통해 수동으로 업데이트를 확인할 수도 있습니다.

여러 클러스터#

여러 클러스터에 연결된 경우, Teleport Connect는 Teleport 컴포넌트 호환성 규칙에 따라 모든 클러스터에서 호환되는 가장 높은 클라이언트 버전을 선택합니다. 클러스터가 호환되지 않는 버전을 요구하거나 다른 클러스터가 업데이트를 관리하도록 하려면, 추가 작업 메뉴에서 제공되는 "업데이트 확인…" 대화상자에서 클러스터를 수동으로 선택할 수 있습니다.

관리형 업데이트 구성#

CLI 도구와 마찬가지로 Teleport Connect는 TELEPORT_CDN_BASE_URL 및 TELEPORT_TOOLS_VERSION 환경 변수를 지원합니다.

TELEPORT_CDN_BASE_URL을 사용하면 사설 네트워크에서 커스텀 빌드를 사용하거나 CDN을 미러링할 수 있습니다 (예: https://example.com).

TELEPORT_TOOLS_VERSION은 클라이언트 도구 업데이트를 제어합니다:

• 관리형 업데이트를 완전히 비활성화하려면 off로 설정하세요.
• 클러스터에서 제공하는 버전을 재정의하려면 특정 버전(예: 18.0.1)으로 설정하세요 (예: 알려진 문제를 우회하기 위해).

Teleport Connect에서 환경 변수를 사용하려면 터미널을 열고 변수를 제공하면서 앱을 실행하세요. 해당 세션에만 적용되므로 시스템 전체 구성에 영향을 주지 않고 설정을 테스트하거나 클러스터에서 제공하는 업데이트를 재정의할 수 있습니다. 영구적인 설정을 위해서는 아래 지침을 따르세요:

$ launchctl set env TELEPORT_TOOLS_VERSION X.Y.Z

$ setx TELEPORT_TOOLS_VERSION X.Y.Z

$ setx TELEPORT_TOOLS_VERSION ""

Exec=env TELEPORT_TOOLS_VERSION=X.Y.Z "/opt/Teleport Connect/teleport-connect" %U

사용자 인터페이스#

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

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

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

백그라운드 모드#

Teleport Connect는 백그라운드(메뉴 바 또는 시스템 트레이를 통해)에서 실행될 수 있으므로, 메인 창을 열지 않고도 VNet 및 데이터베이스, Kubernetes 클러스터, 앱에 대한 연결을 계속 사용할 수 있습니다.

처음 창을 닫을 때, 앱은 백그라운드 모드로 실행할지 창을 닫을 때 종료할지 묻습니다. 나중에 이 동작을 변경하려면 구성 옵션 runInBackground를 참조하세요.

SSH 서버에 연결#

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

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

또는 검색 바에서 서버를 찾아 Enter를 눌러 연결할 수 있습니다.

서드파티 SSH 클라이언트나 편집기의 원격 개발 기능으로 SSH 서버에 연결하려면, VNet 가이드를 읽어 방법을 알아보세요.

로컬 터미널 열기#

로컬 셸 세션이 있는 터미널을 열려면 추가 작업 메뉴에서 "새 터미널 열기"를 선택하거나 Ctrl+Shift+`를 누르세요.

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

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

터미널 셸 변경#

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

선택한 셸은 기본값으로 설정하도록 선택하지 않는 한 해당 탭에만 사용됩니다.

구성은 terminal.shell 및 terminal.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 클라이언트 사용#

데이터베이스 연결 탭에는 데이터베이스에 연결하는 데 사용할 수 있는 명령이 표시됩니다. 연결의 데이터베이스 이름을 수정한 다음 실행 버튼을 클릭하여 해당 명령이 실행된 새 터미널 탭을 열 수 있습니다.

Windows 데스크톱에 연결#

1. 탭 바 끝의 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T를 눌러도 동일한 결과를 얻을 수 있습니다.
2. 연결하려는 데스크톱을 찾아 연결 버튼을 클릭합니다.
3. 사용할 사용자를 선택하고 Enter를 누릅니다.

원격 데스크톱 세션이 있는 새 탭이 열립니다.

또는 검색 바에서 데스크톱을 찾아 Enter를 눌러 연결할 수 있습니다.

원격 세션 중에 역할에서 허용된 경우 클립보드와 로컬 디렉터리를 공유할 수 있습니다.

애플리케이션에 연결#

Teleport Connect는 브라우저에서 애플리케이션을 실행하고 웹 및 TCP 애플리케이션에 대한 인증된 터널을 생성하는 것을 지원합니다.

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

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

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

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

또는 검색 바에서 애플리케이션을 찾아 Enter를 눌러 브라우저에서 실행할 수 있습니다.

VNet으로 TCP 앱에 연결#

VNet은 macOS 및 Windows의 Teleport Connect에서 사용 가능한 가상 네트워크 에뮬레이션 도구입니다. 프로그램 자체에 별도 변경 없이도 컴퓨터의 모든 프로그램이 Teleport로 보호된 TCP 애플리케이션에 연결할 수 있게 합니다. TCP 애플리케이션에 대한 터널을 수동으로 생성할 필요가 없어집니다.

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

1. Teleport 클러스터에 로그인합니다.
2. VNet을 시작하려면 왼쪽 상단의 연결 목록을 열고 VNet 오른쪽의 연결 아이콘을 클릭합니다.
3. 이제 일반 공개 주소를 통해 TCP 앱에 접근하세요.

VNet은 사용자 인증서로 연결을 자동으로 인증합니다. 자세한 내용은 VNet 사용을 참조하세요.

인증된 터널 생성#

Teleport Connect는 장치의 임의 포트에 인증된 터널을 설정할 수 있습니다. 해당 터널에 연결되는 모든 연결은 사용자 자격 증명으로 인증됩니다.

Teleport에 웹 앱으로 추가된 HTTP API(주소가 https://로 시작)에 접근하려는 경우, 장치에 관리자 권한이 없는 경우, 또는 시스템에서 VNet을 아직 사용할 수 없는 경우에 이 방법을 사용하세요.

1. 탭 바 끝의 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T를 눌러도 동일한 결과를 얻을 수 있습니다.
2. 연결하려는 애플리케이션을 찾습니다.

• TCP 애플리케이션의 경우 연결 버튼을 클릭합니다.
  • macOS 및 Windows에서는 대신 세 점을 클릭하고 "로컬 포트에 연결"을 선택합니다.
• 웹 애플리케이션의 경우 실행 버튼 옆의 세 점을 클릭하고 "연결 설정"을 선택합니다.

또는 Linux에서 검색 바에서 TCP 애플리케이션을 찾아 Enter를 눌러 연결을 설정할 수 있습니다.

장치와 애플리케이션 사이에 새 연결이 설정된 새 탭이 열립니다.

Teleport Connect가 실행 중인 동안 연결이 활성 상태로 유지됩니다. 백그라운드 모드가 켜져 있으면 창을 닫은 후에도 활성 상태를 유지합니다. 연결을 종료하려면 연결 닫기를 클릭하거나 앱을 종료하세요.

포트 번호는 앱 재시작 사이에 유지되므로—갑자기 포트가 변경될 걱정 없이 클라이언트를 설정할 수 있습니다.

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

MCP 서버에 연결#

Teleport Connect는 streamable-HTTP 전송의 MCP 서버에 대한 임의 포트에 인증된 터널을 장치에 설정할 수 있습니다. 해당 터널에 연결되는 모든 연결은 사용자 자격 증명으로 인증됩니다.

1. 탭 바 끝의 더하기 기호를 클릭하여 클러스터 리소스가 있는 탭을 엽니다. Ctrl+Shift+T/Cmd+T를 눌러도 동일한 결과를 얻을 수 있습니다.
2. MCP 서버 리소스의 연결 버튼을 클릭합니다.

장치와 MCP 서버 사이에 새 연결이 설정된 새 탭이 열립니다.

Teleport Connect가 실행 중인 동안 연결이 활성 상태로 유지됩니다. 백그라운드 모드가 켜져 있으면 창을 닫은 후에도 활성 상태를 유지합니다. 연결을 종료하려면 연결 닫기를 클릭하거나 앱을 종료하세요.

포트 번호는 앱 재시작 사이에 유지되므로—갑자기 포트가 변경될 걱정 없이 클라이언트를 설정할 수 있습니다.

여러 클러스터에 연결#

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

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

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

재시작 및 재연결#

닫기 전에 Teleport Connect는 세션 종료 시 열려 있던 탭을 기억합니다. 다음에 앱을 열면 Connect는 해당 탭을 다시 열지 여부를 묻습니다. 동의하면 Connect는 앱을 닫기 전에 활성화되어 있던 모든 리소스에 대한 연결을 복원합니다.

터미널 탭 복원 시 Teleport Connect는 앱이 닫혔을 때 진행 중이던 명령을 재실행하지 않습니다. 해당 탭의 작업 디렉터리만 복원합니다.

내 컴퓨터 연결#

내 컴퓨터 연결(Connect My Computer)은 클릭 몇 번으로 Teleport 클러스터에 개인 머신을 추가할 수 있게 합니다.

Teleport를 탐색하거나 Teleport 기반 홈 랩에서 컴퓨터를 사용 가능하게 만들려는 경우, 클러스터에 컴퓨터를 추가하는 가장 쉬운 방법입니다.

내 컴퓨터 연결은 터미널을 사용하거나 에이전트 수명주기를 제어하기 위한 systemctl 같은 도구 없이도 Teleport Connect에서 완전히 관리되는 Teleport 에이전트를 설정합니다.

사전 요구 사항#

• 백엔드에서 사용자 객체를 읽고 업데이트할 수 있는 권한(user 리소스에 대한 read 및 update 동사).
• 백엔드에서 역할을 읽고, 업데이트하고, 생성할 수 있는 권한(role 리소스에 대한 read, update, create 동사).

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

설정 및 사용#

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

설정은 클러스터에 새 역할을 생성하여 현재 시스템 사용자로 장치에 대한 접근을 허용합니다. 그런 다음 해당 역할이 사용자 객체에 추가됩니다.

다음으로 설정은 플랫폼용 Teleport 에이전트를 다운로드하고 현재 클러스터를 가리키는 teleport node configure를 실행합니다. 완료되면 내 컴퓨터 연결이 에이전트를 시작하고 클러스터에서 SSH 노드로 나타날 때까지 기다립니다.

에이전트가 클러스터에 참가한 후, 탭이 에이전트의 상태를 표시하는 화면으로 전환됩니다. 여기서 에이전트가 사용 가능하게 만든 노드에 연결하고, 에이전트를 중지 및 시작하고, 완전히 제거할 수 있습니다. 클러스터에서 수동으로 로그아웃하면 에이전트도 제거됩니다.

Teleport Connect가 실행 중인 동안 컴퓨터가 공유됩니다. 백그라운드 모드가 켜져 있으면 창을 닫은 후에도 공유 상태가 유지됩니다. 공유를 중지하려면 앱을 종료하거나 내 컴퓨터 연결 탭을 통해 에이전트를 중지하세요.

종료하기 전에 에이전트를 중지하지 않으면 앱 재시작 시 공유가 재개됩니다. Teleport Connect가 예기치 않게 충돌하면 에이전트가 즉시 중지됩니다.

에이전트 유지 관리#

Teleport Connect에서 다운로드한 에이전트 버전은 항상 Teleport Connect 버전과 일치합니다. Teleport Connect를 업그레이드한 후 내 컴퓨터 연결은 에이전트를 실행하기 전에 일치하는 에이전트 버전 다운로드를 자동으로 시도합니다.

내 컴퓨터 연결은 항상 디스크에 단일 버전의 에이전트만 저장합니다.

내 컴퓨터 연결 문제 해결#

에이전트 로그 접근#

설정이 완료된 후 내 컴퓨터 연결 탭을 열고 탭 내의 세 점 메뉴에서 "에이전트 로그 디렉터리 열기"를 선택합니다.

내 컴퓨터 연결 아이콘이 상단 바에 표시되지 않음#

아이콘은 설정이 다음 요구 사항을 충족하는 경우에만 표시됩니다:

내 컴퓨터 연결 탭에 에이전트가 실행 중이라고 표시되지만 클러스터에 컴퓨터가 표시되지 않음#

내 컴퓨터 연결 탭에서 "연결"을 클릭합니다. 새 탭의 오류 메시지에 "액세스 거부"가 표시되면, 클러스터 사용자에게 내 컴퓨터 연결 노드에 대한 접근을 거부하는 역할이 할당되어 있을 가능성이 높습니다. 특정 로그인을 거부하거나 node_labels와 같은 필드를 통해 노드 자체에 대한 접근을 거부하는 경우가 있습니다. 이 문제를 해결하려면 웹 UI의 관리 섹션에서 역할 목록을 검사하세요. 먼저 사용자 객체에 할당된 역할을 확인한 다음 각 역할을 검사하세요. 광범위한 deny 규칙이 있는 역할을 찾아보세요.

오류 메시지에서 노드 또는 터널을 찾을 수 없다고 언급되면, 클러스터가 에이전트의 캐시된 뷰를 가지고 있지만 에이전트가 아직 클러스터에 참가하지 않았다는 것을 의미합니다. 몇 초 기다렸다가 노드에 다시 연결을 시도하세요. 문제가 지속되면 에이전트 로그를 확인하세요.

시스템 사용자 이름 변경 후 내 컴퓨터 연결이 작동하지 않음#

내 컴퓨터 연결 구성 시 사용 중이던 시스템 사용자 이름은 해당 클러스터 사용자에 대한 내 컴퓨터 연결 역할에 유지됩니다. 내 컴퓨터 연결 노드에 다시 접근하려면 역할의 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

설정 중에 내 컴퓨터 연결은 최대 5분 동안 유효한 참가 토큰을 생성합니다. 로그에 토큰이 만료되었다고 나오면, 클러스터 참가 초기 시도가 실패한 후 5분 이상이 지나서 다른 시도를 시작한 것일 가능성이 높습니다.

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

설정 다시 시작#

Teleport 노드는 완전히 상태가 없으므로, 에이전트 시작 또는 클러스터 참가 문제가 있는 경우 설정을 다시 실행할 수 있습니다. 설정이 실패한 경우 "재시도"를 클릭하거나, 에이전트가 성공적으로 구성된 후 내 컴퓨터 연결 탭 내의 세 점 메뉴에서 "에이전트 제거"를 선택하세요.

사용자의 내 컴퓨터 연결 접근 방지#

클러스터 사용자가 내 컴퓨터 연결을 사용하지 못하게 하려면 새 참가 토큰을 생성할 수 있는 권한을 부여하지 않도록 하세요. 이는 token 리소스에 대한 create 동사로 제어됩니다. 명시적으로 이 권한을 거부하거나 처음부터 부여하지 마세요. 자세한 내용은 액세스 제어 참조 문서를 참조하세요. 이 권한을 거부하면 상단 바의 아이콘이 숨겨집니다.

이미 에이전트를 설정한 사용자는 참가 토큰 생성 권한을 거부한 후에도 해당 에이전트를 계속 관리할 수 있습니다. 이는 악의적인 관리자가 사용자로 하여금 에이전트를 설정하게 한 다음 에이전트 제거를 방해하지 못하도록 보장합니다.

이미 클러스터에 참가한 에이전트에 대한 접근을 즉시 취소하려면, teleport.dev/connect-my-computer/owner 레이블이 지정된 노드를 찾아 해당 노드에 잠금을 설정하세요.

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

Teleport Connect 외부에서 tsh 사용#

Teleport Connect에는 자체 번들 tsh 버전이 포함되어 있습니다. Teleport Connect는 앱 내에서 수행되는 모든 작업에 항상 이 버전의 tsh를 사용합니다.

번들 tsh 도구는 터미널에서 직접 사용할 수도 있습니다. 기본적으로 Teleport Connect와 tsh는 동일한 홈 디렉터리를 공유하므로, 한 도구에서 생성하거나 업데이트한 프로필은 다른 도구에 즉시 반영됩니다. 다른 디렉터리를 원한다면 구성에서 tshHome 속성을 통해 구성할 수 있습니다.

Teleport Connect는 tsh 디렉터리를 적극적으로 모니터링하므로, tsh로 수행한 업데이트(로그인, 로그아웃, 또는 새 클러스터 추가 등)가 앱에 자동으로 표시됩니다.

하드웨어 키 지원#

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

하드웨어 키로 로그인하려면 역할 또는 클러스터 구성에서 이를 활성화해야 합니다. 적용되면 Teleport Connect는 하드웨어 키를 연결된 상태로 유지하도록 요구하며 탭 및/또는 PIV PIN을 입력하라는 메시지가 표시될 수 있습니다:

처음 로그인할 때 즉시 다시 로그인하라는 메시지가 표시됩니다.

키가 기본 PIV PIN으로 설정된 경우 이 단계에서 변경하라는 메시지가 표시될 수 있습니다. 기본 또는 빈 PIN을 입력하면 업데이트 대화상자가 열립니다.

구성#

Teleport Connect는 첫 실행 시 생성하는 app_config.json 파일을 편집하여 구성할 수 있습니다. 구성 파일을 열려면 추가 작업 메뉴에서 "구성 파일 열기"를 선택하세요. 파일이 기본 편집기에서 열립니다.

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

키보드 단축키 구성#

유효한 단축키는 최소 하나의 수정자와 단일 키 코드를 포함해야 합니다(예: 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

tsh ssh 환경 변수#

내부적으로 Teleport Connect는 tsh ssh를 사용하여 SSH 서버에 연결합니다. 결과적으로 Teleport Connect는 tsh ssh와 관련된 많은 tsh 환경 변수를 지원합니다. 이를 통해 tsh와 Teleport Connect 간에 공통 설정을 쉽게 공유할 수 있습니다.

다음은 SSH 연결에 대해 Teleport Connect에서 지원하는 환경 변수 목록입니다:

텔레메트리#

When you first start the app, Teleport Connect asks for permission to collect and send telemetry data. This includes tracking events such as:

• Logging in to a cluster
• Starting an SSH, database, application, desktop, or Kubernetes session
• File transfer during an SSH session
• Creating an Access Request
• Reviewing an Access Request
• Assuming an Access Request

On login, we also collect some device-related data:

• Operating system and its version
• App version
• Processor architecture

Additionally, we ask for a job role (the answer is optional).

The full list of events and collected data is defined as protocol buffer messages in the Teleport source. We do not track the details of those events but merely that the given event took place. Each event includes the cluster name and user name anonymized with HMAC using the cluster's internal random UUID as the key. It is infeasible to associate this back to a specific cluster or user without access to the cluster's internal datastore.

텔레메트리 비활성화#

처음에 텔레메트리 데이터 공유에 동의했지만 지금은 옵트아웃하려면, 구성에서 usageReporting.enabled를 false로 설정해야 합니다(구성 참조):

"usageReporting.enabled": false

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

문제 해결#

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

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

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

모든 앱 상태를 완전히 지우려면 Teleport Connect를 닫고 다음 명령을 실행하세요:

$ rm -rf ~/Library/Application\ Support/Teleport\ Connect/{tsh,app_state.json}
$ rm -rf ~/.tsh

$ rm -rf ~/.config/Teleport\ Connect/{tsh,app_state.json}
$ rm -rf ~/.tsh

$ del C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\app_state.json
$ rmdir /s /q C:\Users\%UserName%\AppData\Roaming\"Teleport Connect"\tsh
$ rmdir /s /q C:\Users\%UserName%\.tsh

이슈 제출#

이슈를 제출하려면 오른쪽 하단의 피드백 제출 버튼(말풍선 기호)을 클릭하고 버그 제출 링크를 따르세요.

$ teleport-connect --connect-debug

$ "%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --connect-debug

로컬 셸 환경 업데이트#

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

TLS 인증서 검증 건너뛰기#

Teleport Proxy 서비스와 통신할 때 TLS 인증서 검증을 건너뛰는 비보안 모드로 Teleport Connect를 열 수 있습니다. 이는 자체 서명된 인증서가 있는 테스트 환경이나 데모 목적에 유용합니다. 프로덕션 환경에서는 이 모드를 사용하지 않는 것을 권장합니다.

$ teleport-connect --insecure

$ "%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --insecure

Teleport Connect 제거#

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

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

$ rm -rf ~/.tsh

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

$ rmdir /s /q C:\Users\%UserName%\.tsh

$ sudo apt remove teleport-connect

$ sudo yum remove teleport-connect

$ rm -rf ~/.tsh