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

이 페이지에서는 Teleport Connect의 설치 방법과 기능을 설명하며, Teleport로 보호되는 리소스에 연결하는 방법과 자신의 컴퓨터를 Teleport로 보호되는 서버로 등록하는 방법도 다룹니다.

설치 및 업그레이드#

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

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

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

관리형 업데이트#

Teleport Connect는 Teleport Client Tool Managed Updates를 지원합니다. 클러스터에서 이 기능이 활성화되어 있으면, 앱은 로그인 시 사용 가능한 업데이트를 확인하고 자동으로 다운로드한 후 재시작을 요청합니다. tsh의 관리형 업데이트와 달리, Teleport Connect는 업그레이드만 설치합니다. 다운그레이드는 수동으로 설치해야 합니다.

Windows에서는 컴퓨터별 설치의 경우, 권한이 있는 업데이터 서비스(TeleportConnectUpdater)를 사용하여 UAC 프롬프트 없이 백그라운드에서 업데이트를 설치합니다.

Linux에서는 설치를 완료하기 위해 관리자 자격 증명을 입력하라는 요청을 받을 수 있습니다.

추가 작업 메뉴에서 "Check for Updates…"를 통해 수동으로 업데이트를 확인할 수도 있습니다.

다중 클러스터#

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

관리형 업데이트 설정#

관리형 업데이트는 macOS와 Linux에서는 환경 변수로, Windows에서는 레지스트리 정책 키로 설정합니다.

$ launchctl set env TELEPORT_TOOLS_VERSION X.Y.Z

$ reg add "HKLM\SOFTWARE\Policies\Teleport\TeleportConnect" /v ToolsVersion /t REG_SZ /d X.Y.Z /f

$ reg add "HKLM\SOFTWARE\Policies\Teleport\TeleportConnect" /v ToolsVersion /t REG_SZ /d off /f

$ reg add "HKLM\SOFTWARE\Policies\Teleport\TeleportConnect" /v CdnBaseUrl /t REG_SZ /d https://example.com /f

$ reg delete "HKLM\SOFTWARE\Policies\Teleport\TeleportConnect" /v ToolsVersion /f

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

사용자 인터페이스#

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

• 프로필 선택기(오른쪽 상단): 서로 다른 Teleport 클러스터의 프로필 간을 전환하거나 클러스터에 로그인/로그아웃할 수 있습니다.
• 연결 목록(왼쪽 상단): 최근 연결을 표시하여 연결 간을 원활하게 전환할 수 있습니다.
• 검색 바(가운데): 클러스터 전체에서 리소스를 검색할 수 있습니다.
• 클러스터 선택기(검색 바 왼쪽): 트러스티드 클러스터를 설정했고 루트 클러스터에 연결된 리프 클러스터가 있는 경우에만 표시됩니다. 리프 클러스터 리소스를 탐색할 수 있게 해줍니다. 또한 "Open new terminal" 작업은 새 터미널 탭을 선택한 클러스터에 바인딩합니다.
• 추가 작업 메뉴(프로필 선택기 왼쪽): 설정 파일 열기 또는 Enterprise 클러스터에서 접근 요청 생성과 같은 옵션을 포함합니다.

하단의 상태 바는 왼쪽 하단에 클러스터 브레드크럼을 표시하여 현재 탭이 어느 클러스터에 바인딩되어 있는지 나타내며, 오른쪽 하단에는 Share Feedback 버튼이 있습니다.

백그라운드 모드#

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

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

SSH 서버에 연결하기#

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

선택한 서버에서 셸 세션과 함께 새 탭이 열립니다.

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

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

로컬 터미널 열기#

로컬 셸 세션과 함께 터미널을 열려면, 추가 작업 메뉴에서 "Open new terminal"을 선택하거나 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 설정 속성 아래에 저장됩니다. 자세한 내용은 Configuration 섹션을 참조하세요.

Kubernetes 클러스터에 연결하기#

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

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

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

KUBECONFIG 환경 변수의 값은 앱 재시작 시에도 유지되지만, 이 설정 파일은 왼쪽 상단의 연결 목록에서 Kubernetes 클러스터가 제거되거나 Teleport Connect가 닫히면 사용할 수 없게 됩니다.

데이터베이스에 연결하기#

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

사용자의 장치와 데이터베이스 서버 간에 새 연결이 설정된 새 탭이 열립니다.

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

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

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

GUI 클라이언트 사용#

GUI 클라이언트로 연결하려면, 데이터베이스 연결 탭의 Connect with GUI 섹션에 있는 지침을 따르세요.

CLI 클라이언트 사용#

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

Windows 데스크톱에 연결하기#

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

원격 데스크톱 세션과 함께 새 탭이 열립니다.

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

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

애플리케이션에 연결하기#

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

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

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

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

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

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

VNet으로 TCP 앱에 연결하기#

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

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

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

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

인증된 터널 생성하기#

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

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

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

• TCP 애플리케이션의 경우, Connect 버튼 옆의 점 세 개를 클릭하고 "Connect without VNet"을 선택합니다.
• 웹 애플리케이션의 경우, Launch 버튼 옆의 점 세 개를 클릭하고 "Set up connection"을 선택합니다.

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

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

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

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

MCP 서버에 연결하기#

Teleport Connect는 스트리머블 HTTP 전송 방식의 MCP 서버에 대해 사용자 장치의 무작위 포트에 인증된 터널을 설정할 수 있습니다. 해당 터널에 대한 모든 연결은 사용자의 자격 증명으로 인증됩니다.

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

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

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

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

다중 클러스터에 연결하기#

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

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

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

재시작 및 재연결#

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

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

Connect My Computer#

Connect My Computer를 사용하면 몇 번의 클릭만으로 개인 컴퓨터를 Teleport 클러스터에 추가할 수 있습니다.

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

Connect My Computer는 작업을 완료하기 위해 터미널을 사용할 필요 없이, 그리고 에이전트의 수명 주기를 제어하기 위한 systemctl 같은 도구가 필요 없이, Teleport Connect가 완전히 관리하는 Teleport 에이전트를 설정합니다.

사전 요구 사항#

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

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

설정 및 사용#

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

설정 과정에서 현재 시스템 사용자로 사용자의 장치에 대한 접근 권한을 부여하는 새 역할이 클러스터에 생성됩니다. 이 역할은 이후 사용자 객체에 추가됩니다.

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

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

Teleport Connect가 실행되는 동안 사용자의 컴퓨터가 공유됩니다. 백그라운드 모드가 켜져 있으면 창을 닫은 후에도 계속 공유됩니다. 공유를 중지하려면 앱을 종료하거나 Connect My Computer 탭에서 에이전트를 중지하세요.

앱 재시작 시 공유가 재개되며, 종료 전에 에이전트를 중지한 경우에는 그렇지 않습니다. Teleport Connect가 예기치 않게 충돌하면 에이전트는 즉시 중지됩니다.

에이전트 유지 관리#

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

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

Connect My Computer 문제 해결#

에이전트 로그 접근하기#

설정이 완료된 후, Connect My Computer 탭을 열고 탭 내의 점 세 개 메뉴에서 "Open agent logs directory"를 선택하세요.

상단 바에 Connect My Computer 아이콘이 보이지 않는 경우#

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

Connect My Computer 탭에서 에이전트가 실행 중이라고 표시되지만 클러스터에서 컴퓨터가 보이지 않는 경우#

Connect My Computer 탭에서 "Connect"를 클릭하세요. 새 탭에 표시되는 오류 메시지가 "access denied"라면, 클러스터 사용자에게 할당된 역할이 특정 로그인 계정이나 node_labels 같은 필드를 통해 노드 자체에 대한 접근을 거부하여 Connect My Computer 노드에 대한 접근을 거부하고 있을 가능성이 있습니다. 이 문제를 해결하려면 Web UI의 Management 섹션에서 역할 목록을 확인하세요. 먼저 사용자 객체에 할당된 역할을 확인한 다음 각 역할을 검사하세요. 광범위한 deny 규칙이 있는 역할을 찾아보세요.

오류 메시지에 노드나 터널을 찾을 수 없다는 내용이 있다면, 클러스터에 에이전트에 대한 캐시된 뷰는 있지만 에이전트가 아직 클러스터에 합류하지 않았음을 의미합니다. 몇 초 기다린 후 다시 노드에 연결을 시도하세요. 문제가 지속되면 에이전트 로그를 확인하세요.

시스템 사용자 이름을 변경한 후 Connect My Computer가 작동하지 않는 경우#

Connect My Computer를 설정할 당시 사용 중이던 시스템 사용자 이름은 해당 클러스터 사용자에 대한 Connect My Computer 역할에 유지됩니다. Connect My Computer 노드에 대한 접근 권한을 다시 얻으려면, 역할의 logins 섹션에 새 시스템 사용자 이름을 추가하세요. 이 역할은 connect-my-computer-<name of cluster user> 형식의 이름으로 식별할 수 있습니다.

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

에이전트가 클러스터에 합류할 수 없고 로그에 토큰이 만료되었거나 찾을 수 없다고 표시되는 경우#

이 시나리오에서는 에이전트가 시작될 때 다음과 같은 로그를 출력합니다.

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 노드는 완전히 상태 비저장(stateless)이므로, 에이전트 시작이나 클러스터 합류에 문제가 있는 경우 설정을 다시 실행해볼 수 있습니다. 설정이 실패한 경우 "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=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을 변경하라는 메시지가 표시될 수 있습니다. 기본 또는 빈 PIN을 입력하면 이를 업데이트하는 대화 상자가 열립니다.

설정#

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

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

키보드 단축키 설정하기#

유효한 단축키는 하나 이상의 수정자와 하나의 키 코드를 포함해야 합니다(예: 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 간에 공통 설정을 더 쉽게 공유할 수 있습니다.

아래는 Teleport Connect가 SSH 연결에 대해 지원하는 환경 변수 목록입니다.

텔레메트리#

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

• 클러스터에 로그인
• SSH, 데이터베이스, 애플리케이션, 데스크톱 또는 Kubernetes 세션 시작
• SSH 세션 중 파일 전송
• Access Request 생성
• Access Request 검토
• Access Request 승격(assume)

로그인 시 일부 디바이스 관련 데이터도 수집합니다:

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

추가로, 직무 역할을 질문합니다(답변은 선택 사항입니다).

이벤트 및 수집 데이터의 전체 목록은 Teleport 소스의 protocol buffer 메시지로 정의되어 있습니다. 우리는 해당 이벤트의 세부 내용을 추적하지 않으며 단지 주어진 이벤트가 발생했다는 사실만을 추적합니다. 각 이벤트에는 클러스터의 내부 랜덤 UUID를 키로 사용하는 HMAC로 익명화된 클러스터 이름과 사용자 이름이 포함됩니다. 클러스터의 내부 데이터스토어에 접근하지 않고서는 이를 특정 클러스터나 사용자와 다시 연결하는 것은 실질적으로 불가능합니다.

텔레메트리 비활성화하기#

처음에는 텔레메트리 데이터 공유에 동의했지만 이제는 옵트아웃하고 싶다면, 설정에서 usageReporting.enabled를 false로 설정해야 합니다(Configuration 참조).

"usageReporting.enabled": false

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

문제 해결#

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

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

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

이슈 제출하기#

이슈를 제출하려면 오른쪽 하단의 Submit Feedback 버튼(말풍선 아이콘)을 클릭하고 Submit a Bug 링크를 따라가세요.

$ teleport-connect --connect-debug

# 컴퓨터별 설치(기본값):
$ "%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --connect-debug

# 사용자별 설치:
$ "%LOCALAPPDATA%\Programs\Teleport Connect\Teleport Connect.exe" --connect-debug

로컬 셸 환경 업데이트하기#

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

TLS 인증서 확인 건너뛰기#

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

$ teleport-connect --insecure

# 컴퓨터별 설치(기본값):
$ "%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --insecure

# 사용자별 설치:
$ "%LOCALAPPDATA%\Programs\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