VNet 사용하기
이 가이드는 VNet을 사용하여 Teleport를 통해 사용 가능한 TCP 애플리케이션 및 SSH 서버에 연결하는 방법을 설명합니다. VNet은 컴퓨터에서 Teleport를 통해 사용 가능한 TCP 앱 및 SSH 서버로의 연결을 자동으로 프록시합니다.
이 가이드는 VNet을 사용하여 Teleport를 통해 사용 가능한 TCP 애플리케이션 및 SSH 서버에 연결하는 방법을 설명합니다.
작동 원리#
VNet은 컴퓨터에서 Teleport를 통해 사용 가능한 TCP 앱 및 SSH 서버로의 연결을 자동으로 프록시합니다. 기기의 프로그램은 Teleport 인증 세부 정보를 알 필요 없이 Teleport로 보호된 리소스에 안전하게 연결할 수 있습니다. 내부적으로 VNet은 Teleport 자격 증명으로 연결을 인증하고 연결을 안전하게 터널링합니다. 이 모든 것은 클라이언트 측에서 수행됩니다 – VNet은 Teleport 리소스에 대한 DNS 요청을 가로채고 연결을 처리할 VNet이 관리하는 가상 IP 주소로 응답하는 로컬 DNS 네임 서버를 설정합니다.
VNet의 SSH 지원을 통해 서드파티 SSH 클라이언트는 최소한의 구성으로 Teleport SSH 서버에 연결할 수 있으며, 여전히 세션별 MFA 및 하드웨어 키 지원과 같은 Teleport 액세스 제어 및 기능을 제공합니다.
VNet은 이 로컬 가상 네트워크를 통해 VPN과 같은 경험을 제공하면서, 기존 VPN이 제공할 수 없는 Teleport의 모든 신원 확인 및 제로 트러스트 기능을 유지합니다.
VNet은 Teleport Connect 및 tsh의 macOS와 Windows에서 사용할 수 있으며, 향후 버전에서 Linux 지원이 계획되어 있습니다.
앱 액세스를 위한 VNet의 VPN과 유사한 경험은 클라이언트 머신에서 실행 중인 모든 소프트웨어가 로컬 DNS 또는 IP 주소에서 Teleport 앱에 액세스할 수 있음을 의미합니다.
공유 또는 다중 사용자 머신에서 VNet을 실행하지 마세요. 여러 OS 사용자가 동일한 머신을 공유하는 경우, 모든 사용자가 로컬 VNet DNS 또는 IP 주소에서 Teleport TCP 앱에 액세스할 수 있습니다.
VNet 뒤에 HTTP 서비스를 보호하세요. 신뢰할 수 없는 웹사이트는 DNS 리바인딩 공격을 사용하여 브라우저의 Same-Origin 정책을 우회하고 VNet IP 주소에 일반 HTTP 요청을 발행할 수 있습니다. Teleport 클러스터에 일반 HTTP API를 제공하는 TCP 앱이 포함된 경우, VNet을 피하거나 DNS 리바인딩 공격에 대한 다음 완화 방법 중 하나 이상을 구현하는 것이 강력히 권장됩니다:
- 이러한 API를 HTTPS 또는 다른 프로토콜로 업그레이드
- HTTP 서버에서 Host 헤더 허용 목록 적용
- HTTP 웹사이트에 대한 브라우저 액세스 차단
사전 요구사항#
- macOS Ventura (13.0) 이상을 실행하는 클라이언트 머신.
- Teleport Connect.
- Windows 10 이상을 실행하는 클라이언트 머신.
- Teleport Connect, 버전 17.3.0 이상.
1/3단계. VNet 시작#
Teleport Connect를 열고 클러스터에 로그인합니다. Teleport Connect 앱을 이전에 사용한 적이 없다면 Teleport Connect 사용하기를 참조하세요.
왼쪽 상단의 연결 목록을 열고 아이콘을 클릭하여 VNet을 시작합니다. 또는 이 단계를 건너뛰면 TCP 앱에서 "Connect"를 클릭하거나 SSH 서버에서 "Connect with VNet"을 클릭할 때 VNet이 자동으로 시작됩니다.
VNet이 한 번 시작된 후에는 VNet을 중지하고 Teleport Connect를 닫지 않는 한 Teleport Connect를 열 때마다 자동으로 시작됩니다.
macOS에서의 첫 번째 실행
첫 번째 실행 시 macOS는 tsh.app에 대한 백그라운드 항목을 활성화하라는 메시지를 표시합니다. VNet은 기기에서 DNS를 구성하기 위해 이 백그라운드 항목이 필요합니다. 백그라운드 항목을 활성화하려면 시스템 알림과 상호작용하거나 시스템 설정 > 일반 > 로그인 항목으로 이동하여 "백그라운드에서 허용"에서 tsh.app을 찾으세요.
2/3단계. TCP 앱에 연결#
연결하려는 TCP 앱을 찾습니다.
TCP 앱은 주소에 tcp://를 프로토콜로 사용합니다.
TCP 앱 옆의 "Connect"를 클릭합니다. 이렇게 하면 VNet이 아직 실행 중이지 않은 경우 시작되고 앱의 주소가 클립보드에 복사됩니다. 이제 일반적으로 연결하는 데 사용하는 애플리케이션 클라이언트를 사용하여 애플리케이션에 연결할 수 있습니다.
$ psql postgres://postgres@tcp-app.teleport.example.com/postgres
VNet이 백그라운드에서 실행 중인 동안에는 각 앱 옆의 "Connect"를 클릭할 필요가 없습니다. Teleport Connect에서 아무런 작업 없이 모든 TCP 앱에 직접 연결할 수 있습니다.
애플리케이션이 다중
포트를 지정하지 않는 한,
VNet은 애플리케이션 클라이언트가 사용하는 모든 포트에서 연결을 프록시합니다. 다중 포트 앱의 경우, 포트 번호는 앱의 대상 포트 중 하나와 일치해야 합니다. 대상 포트 목록을 보려면 Teleport Connect의 애플리케이션 옆에 있는 점 세 개 메뉴를 클릭하거나 tsh apps ls를 실행하세요.
세션별 MFA가 활성화된 경우, 각 포트에 대한 첫 번째 연결이 MFA 확인을 트리거합니다.
3/3단계. SSH 서버에 연결#
연결하려는 SSH 서버를 찾고, "Connect" 드롭다운 옆의 메뉴를 열고, "Connect with VNet"을 클릭합니다. 이렇게 하면 VNet이 아직 실행 중이지 않은 경우 시작되고 서버의 VNet 주소가 클립보드에 복사됩니다.
SSH 클라이언트가 VNet을 통해 Teleport SSH 서버에 연결할 수 있기 전에 일회성 구성 단계가 필요합니다. SSH 서버에서 "Connect with VNet"을 클릭하면 Teleport Connect가 이 구성이 있는지 자동으로 확인하고 필요한 경우 안내를 제공합니다.
구성 단계가 완료되면 ~/.ssh/config에서 구성 옵션을 읽는 모든 OpenSSH 호환 클라이언트가 Teleport SSH 서버에 연결할 수 있어야 합니다.
표준 ssh 클라이언트 또는 Visual Studio Code나 Zed와 같은 편집기의 원격 개발 기능으로 연결해 보세요.
$ ssh <username>@<hostname>.<clustername>
VNet이 백그라운드에서 실행 중인 동안에는 각 SSH 서버 옆의 "Connect with VNet"을 클릭할 필요가 없으며, Teleport Connect에서 아무런 작업 없이 모든 Teleport SSH 서버에 직접 연결할 수 있습니다.
tsh 지원#
VNet은 Teleport Connect를 실행하지 않고도 tsh에서 사용할 수 있습니다.
사용하려면 로그인한 다음 tsh vnet을 실행하세요.
$ tsh login --proxy=teleport.example.com
$ tsh vnet
tsh 지원이 가능하지만 VNet 실행을 위한 기본 애플리케이션은 Teleport Connect입니다.
Teleport Connect는 MFA 프롬프트 및 클러스터 로그인에 대한 더 나은 가시성을 제공하며, 문제 해결에 유용한 진단을 자동으로 실행합니다.
문제 해결#
충돌하는 IPv4 범위#
클라이언트 컴퓨터에서 VNet은 기본적으로 CGNAT IP 범위 100.64.0.0/10의 IPv4 주소를 사용하며, 이 범위에 대한 주소와 경로를 구성해야 합니다.
이는 다른 VPN과 유사한 애플리케이션과 충돌할 수 있으며, 특히 Tailscale도 이 범위를 사용합니다.
VNet에서 연결 문제가 발생하는 경우, Tailscale이나 다른 VPN 클라이언트를 실행 중인지 확인하고 비활성화하여 문제가 지속되는지 확인해 보세요. 충돌을 피하고 Tailscale이나 다른 VPN 클라이언트와 함께 VNet을 실행하려면 VNet이 다른 IPv4 범위를 사용하도록 구성할 수 있습니다. VNet 구성 가이드를 참조하세요.
VNet 없이 앱에 연결하기#
때로는 연결 문제가 VNet과 관련이 없을 수 있으며, VNet 없이 앱에 연결해 보면 이를 확인할 수 있습니다. Connect 리소스 보기나 tsh apps ls의
출력에 앱이 표시되는지 확인하세요. VNet을 끄고 tsh proxy app -d <app-name>으로 앱에 대한 로컬 프록시를 생성해 보세요(디버그 로깅 활성화).
Teleport 클러스터에 도달하려고 할 때 타임아웃#
갑작스러운 기기 종료와 같이 VNet이 중지하기 전에 정리할 기회가 없는 경우, /etc/resolver에 남은 DNS 구성 파일이 남아 있을 수 있습니다. 이 파일들은 클러스터에 연결할 때 VNet이 운영하는 DNS 서버와 통신하도록 컴퓨터에 지시합니다. 하지만 VNet이 더 이상 실행되지 않으므로 해당 요청에 응답할 DNS 서버가 없습니다.
이 파일을 정리하려면 VNet을 다시 시작하기만 하면 됩니다. 또는 남은 파일을 수동으로 제거할 수 있습니다.
VNet이 DNS 쿼리를 수신하는지 확인#
Teleport Connect를 엽니다. 왼쪽 상단의 연결 패널에서 VNet을 선택합니다. VNet이 실행 중인지 확인한 다음 "Open Diag Report"를 선택합니다. VNet이 사용하는 IPv6 접두사와 IPv4 CIDR 범위를 확인합니다.
클러스터에서 사용 가능한 TCP 앱에 대한 쿼리를 전송하고, 을 앱의 이름으로 교체하세요:
$ dscacheutil -q host -a name
name: tcp-app.teleport.example.com
ipv6_address: fd60:67ec:4325::647a:547d
name: tcp-app.teleport.example.com
ip_address: 100.68.51.151
# In PowerShell.
$ Resolve-DnsName
Name Type TTL Section IPAddress
---- ---- --- ------- ---------
tcp-app.teleport.example.com AAAA 10 Answer fd60:67ec:4325::647a:547d
tcp-app.teleport.example.com A 10 Answer 100.68.51.151
반환된 주소는 VNet 진단 보고서에 나열된 범위에 속해야 합니다.
TCP 앱의 주소 이외의 것을 쿼리하면 프록시 서비스에 속하는 주소가 반환되어야 합니다. macOS를 예로 들면:
$ dscacheutil -q host -a name dashboard.teleport.example.com
name: dashboard.teleport.example.com
ipv6_address: 2606:2800:21f:cb07:6820:80da:af6b:8b2c
name: dashboard.teleport.example.com
ip_address: 93.184.215.14
이러한 호스트 이름 중 하나를 쿼리하면 VNet의 디버그 로그에 일부 출력이 발생해야 합니다(디버그 로그를 활성화하는 방법은 이슈 제출을 참조하세요).
이슈 제출#
이슈를 제출할 때, VNet 진단 보고서와 VNet 및 Teleport Connect의 디버그 로그를 포함해야 합니다.
진단 보고서를 파일로 저장하려면 Teleport Connect를 엽니다. 왼쪽 상단의 연결 패널에서 VNet을 선택한 다음 "Open Diag Report"를 선택합니다. 열린 보고서가 있는 새 탭에서 "Save Report to File" 아이콘을 클릭합니다.
VNet 및 Teleport Connect 로그를 수집하려면 아래 지침을 사용하세요:
VNet에서 디버그 로그를 활성화하려면 먼저 Teleport Connect를 중지한 다음 다음 명령을 실행합니다. 이렇게 하면 다음 VNet 호출에 대해서만 디버그 로그가 활성화됩니다:
$ sudo launchctl debug system/com.gravitational.teleport.tsh.vnetd --environment TELEPORT_DEBUG=1
다음으로 VNet에서 로그를 파일로 캡처하기 시작합니다:
$ log stream --predicate 'subsystem ENDSWITH ".vnetd"' --style syslog --level debug > vnet.log
그런 다음 Teleport Connect의 디버그 로그를 활성화하려면 다음 명령을 사용하여 Teleport Connect를 시작합니다:
$ open -a "Teleport Connect" --args --connect-debug
다음으로 VNet에서 문제를 재현해 보세요.
Teleport Connect에서 로그를 수집하려면 앱 메뉴에서 Help → Open Logs Directory를 선택하면 Finder에서 ~/Library/Application Support/Teleport Connect/logs가 열립니다. 이전 단계에서 생성된 vnet.log와 함께 모든 파일을 첨부하세요.
버전 18.0.0 이전에는 VNet 로그가 /var/log/vnet.log에 저장되었습니다.
오류가 Teleport Connect가 VNet을 시작할 수 없거나 코드 서명 문제와 관련된 경우, VNet 시작을 시도한 직후 /var/log/com.apple.xpc.launchd/launchd.log에서 tsh를 검색하면 관련 정보를 찾을 수 있습니다:
$ grep tsh /var/log/com.apple.xpc.launchd/launchd.log
VNet에서 디버그 로그를 활성화하려면 먼저 Teleport Connect를 중지합니다. 그런 다음 시작 메뉴에서 명령 프롬프트를 찾고 오른쪽 클릭 메뉴에서 관리자 권한으로 실행을 선택합니다. 다음 명령은 VNet에서 디버그 로그를 활성화하고 실수로 관리자로 Teleport Connect를 시작하지 않도록 즉시 관리자 명령 프롬프트를 닫습니다.
$ reg.exe ADD HKLM\SYSTEM\CurrentControlSet\Services\TeleportVNet /v Environment /t REG_MULTI_SZ /d TELEPORT_DEBUG=1 /f && exit
다음으로 시작 메뉴에서 실행 앱을 엽니다. 디버그 로그가 활성화된 상태로 Teleport Connect를 시작하려면 다음을 실행합니다:
$ "%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --connect-debug
다음으로 VNet에서 문제를 재현해 보세요.
완료되면 관리자 명령 프롬프트에서 다음 명령을 실행하여 VNet에서 디버그 로그를 비활성화합니다:
$ reg.exe DELETE HKLM\SYSTEM\CurrentControlSet\Services\TeleportVNet /v Environment /f
마지막 단계는 로그를 수집하는 것입니다. VNet 로그부터 시작하겠습니다. 시작 메뉴에서 이벤트 뷰어를 엽니다. 왼쪽 사이드바에서 이벤트 뷰어(로컬) → 응용 프로그램 및 서비스 로그 → Teleport를 선택합니다. 오른쪽 사이드바에서 "모든 이벤트를 다른 이름으로 저장..."을 선택합니다. 로그를 .evtx 파일로 저장합니다. 이벤트 뷰어에서 표시 정보에 대해 묻는 경우 "표시 정보 없음"을 선택합니다.
Teleport Connect에서 로그를 수집하려면 앱에서 Alt 키를 누른 다음 Help → Open Logs
Directory를 선택합니다. 그러면 C:\Users\%UserName%\AppData\Roaming\Teleport Connect\logs가 열립니다. 이전 단계의 .evtx 파일과 함께 모든 파일을 첨부하세요.
이슈 제출 외에도 VNet 로그는 다음 PowerShell 명령으로 파일에 빠르게 저장할 수 있습니다. 단, 이슈를 제출할 때는 .evtx 파일을 첨부해 주세요.
$ Get-WinEvent -LogName Teleport -FilterXPath "*[System[Provider[@Name='vnet']]]" -Oldest | Format-Table -Property TimeCreated,LevelDisplayName,Message -Wrap | Out-File vnet.log
버전 18.0.0 이전에는 VNet 로그가 C:\Program Files\Teleport Connect\resources\bin\logs.txt에 저장되었습니다.