VNet 사용하기
Teleport v18.9이 가이드는 VNet을 사용하여 Teleport를 통해 사용 가능한 TCP 애플리케이션 및 SSH 서버에 연결하는 방법을 설명합니다. VNet은 컴퓨터에서 Teleport를 통해 사용 가능한 TCP 앱 및 SSH 서버로의 연결을 자동으로 프록시합니다.
이 가이드는 VNet을 사용하여 Teleport를 통해 사용 가능한 TCP 애플리케이션 및 SSH 서버에 연결하는 방법을 설명합니다.
작동 원리#
VNet은 컴퓨터에서 Teleport를 통해 사용 가능한 TCP 앱 및 SSH 서버로의 연결을 자동으로 프록시합니다. 기기의 프로그램은 Teleport 인증 세부 정보를 알 필요 없이 Teleport로 보호된 리소스에 안전하게 연결할 수 있습니다. 내부적으로 VNet은 Teleport 자격 증명으로 연결을 인증하고 연결을 안전하게 터널링합니다. 이 모든 작업은 클라이언트 측에서 이루어집니다 – VNet은 로컬 DNS 네임 서버를 설정하여 Teleport 리소스에 대한 DNS 요청을 가로챈 다음, VNet이 관리하고 연결을 처리할 가상 IP 주소로 응답합니다.
VNet의 SSH 지원 기능을 사용하면 서드파티 SSH 클라이언트가 최소한의 구성만으로 Teleport SSH 서버에 연결할 수 있으며, 동시에 세션당 MFA 및 하드웨어 키 지원과 같은 Teleport 접근 제어 및 기능도 계속 제공됩니다.
VNet은 이 로컬 가상 네트워크를 통해 VPN과 같은 경험을 제공하는 동시에, 기존 VPN이 제공할 수 없는 Teleport의 모든 아이덴티티 검증 및 제로 트러스트 기능을 유지합니다.
VNet은 macOS, Windows, Linux에서 Teleport Connect와 tsh를 통해 사용할 수 있습니다.
VNet의 앱 접근에 대한 VPN과 유사한 경험은 클라이언트 머신에서 실행되는 모든 소프트웨어가 로컬 DNS 또는 IP 주소로 Teleport 앱에 접근할 수 있음을 의미합니다.
공유 또는 다중 사용자 머신에서 VNet을 실행하지 마세요. 여러 OS 사용자가 동일한 머신을 공유하는 경우, 어떤 사용자든 자신의 로컬 VNet DNS 또는 IP 주소로 Teleport TCP 앱에 접근할 수 있습니다.
VNet 뒤에 있는 HTTP 서비스를 보호하세요. 신뢰할 수 없는 웹사이트는 DNS 리바인딩 공격을 사용하여 브라우저의 동일 출처 정책(Same-Origin Policy)을 우회하고 VNet IP 주소로 일반 HTTP 요청을 보낼 수 있습니다. Teleport 클러스터에 일반 HTTP API를 제공하는 TCP 앱이 포함되어 있다면, VNet 사용을 피하거나 다음 중 하나 이상의 DNS 리바인딩 공격 완화 방법을 구현하는 것을 강력히 권장합니다:
- 이러한 API를 HTTPS 또는 다른 프로토콜로 업그레이드
- HTTP 서버에서 Host 헤더 허용 목록 적용
- HTTP 웹사이트에 대한 브라우저 접근 차단
사전 요구사항#
- macOS Ventura(13.0) 이상을 실행하는 클라이언트 머신.
- Teleport Connect.
- Windows 10 이상을 실행하는 클라이언트 머신.
- 머신별 모드("이 컴퓨터를 사용하는 모든 사람")로 설치된 버전 17.3.0 이상의 Teleport Connect.
- systemd, systemd-resolved, polkit, D-Bus가 있는 Linux 배포판을 실행하는 클라이언트 머신.
- 버전 18.8.0 이상의 Teleport Connect.
1/3단계. VNet 시작하기#
Teleport Connect를 열고 클러스터에 로그인합니다. Teleport Connect 앱을 처음 사용해 본다면 Teleport Connect 사용하기를 참고하세요.
왼쪽 상단의 연결 목록을 열고 아이콘을 클릭하여 VNet을 시작합니다. 또는 이 단계를 건너뛰고 TCP 앱에서 "연결" 또는 SSH 서버에서 "VNet으로 연결"을 클릭하면 VNet이 자동으로 시작됩니다.
VNet이 한 번 시작되면, Teleport Connect를 닫기 전에 VNet을 중지하지 않는 한 Teleport Connect를 열 때마다 자동으로 시작됩니다.
macOS에서 처음 실행하기
처음 실행하는 동안 macOS는 tsh.app에 대한 백그라운드 항목을 활성화하라는 메시지를 표시합니다. VNet은 기기에서 DNS를 구성하기 위해 이 백그라운드 항목이 필요합니다. 백그라운드 항목을 활성화하려면 시스템 알림과 상호작용하거나 시스템 설정 > 일반 > 로그인 항목으로 이동하여 "백그라운드에서 허용"에서 tsh.app을 찾으세요.
2/3단계. TCP 앱에 연결하기#
연결하려는 TCP 앱을 찾습니다.
TCP 앱은 주소의 프로토콜로 tcp://를 사용합니다.
TCP 앱 옆의 "연결"을 클릭합니다. 이렇게 하면 VNet이 아직 실행 중이 아닌 경우 VNet을 시작한 다음, 앱의 주소를 클립보드에 복사합니다. 이제 평소에 연결할 때 사용하는 애플리케이션 클라이언트를 사용하여 애플리케이션에 연결할 수 있습니다.
$ psql postgres://postgres@tcp-app.teleport.example.com/postgres
VNet이 백그라운드에서 실행 중인 한, 각 앱 옆의 "연결"을 클릭할 필요가 없습니다. Teleport Connect에서 아무 작업도 하지 않고 모든 TCP 앱에 직접 연결할 수 있습니다.
애플리케이션이 여러
포트를
지정하지 않는 한, VNet은 애플리케이션 클라이언트가 사용하는 모든 포트를 통한 연결을 프록시합니다.
다중 포트 앱의 경우, 포트 번호는 앱의 타깃 포트 중 하나와 일치해야 합니다. 타깃 포트 목록을
확인하려면 Teleport Connect에서 애플리케이션 옆의 점 세 개 메뉴를 클릭하거나 tsh apps ls를
실행하세요.
세션당 MFA가 활성화되어 있으면, 각 포트를 통한 첫 번째 연결에서 MFA 확인이 트리거됩니다.
3/3단계. SSH 서버에 연결하기#
연결하려는 SSH 서버를 찾고, "연결" 드롭다운 옆의 메뉴를 열어 "VNet으로 연결"을 클릭합니다. 이렇게 하면 VNet이 아직 실행 중이 아닌 경우 VNet을 시작한 다음, 해당 서버의 VNet 주소를 클립보드에 복사합니다.
SSH 클라이언트가 VNet을 통해 Teleport SSH 서버에 연결할 수 있으려면 일회성 구성 단계가 필요합니다. SSH 서버에서 "VNet으로 연결"을 클릭하면, Teleport Connect가 이 구성이 존재하는지 자동으로 확인하고 필요한 경우 안내해 줍니다.
구성 단계가 완료되면, ~/.ssh/config에서 구성 옵션을 읽는 OpenSSH 호환 클라이언트라면
어떤 것이든 Teleport SSH 서버에 연결할 수 있어야 합니다.
표준 ssh 클라이언트나 Visual Studio Code, Zed와 같은 편집기의 원격 개발(Remote Development)
기능으로 연결해 보세요.
$ ssh <username>@<hostname>.<clustername>
VNet이 백그라운드에서 실행 중인 한, 각 SSH 서버 옆의 "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 프롬프트와 클러스터 로그인에 대해 더 나은 가시성을 제공하며, 문제
해결에 유용한 진단을 자동으로 실행합니다.
Teleport Connect 없이 Linux에서 tsh vnet 실행하기
Linux에서 VNet을 사용하려면 systemd 유닛, polkit 정책, D-Bus 서비스 파일이 시스템에
설치되어 있어야 합니다. 이 파일들은 Teleport Connect 패키지에
번들로 포함되어 있으며 설치 중에 배포됩니다.
Teleport Connect 없이 tsh vnet을 사용하는 경우, 이 파일들을 수동으로 설치해야 합니다.
Teleport 리포지터리의
examples/systemd/vnet을
참고하세요.
문제 해결#
IPv4 범위 충돌#
클라이언트 컴퓨터에서 VNet은 기본적으로 CGNAT IP 범위인 100.64.0.0/10의 IPv4 주소를 사용하며,
이 범위에 대한 주소와 경로를 구성해야 합니다.
이는 다른 VPN과 유사한 애플리케이션과 충돌할 수 있으며, 특히 Tailscale도 이 범위를 사용합니다.
VNet에서 연결 문제가 발생하는 경우, Tailscale이나 다른 VPN 클라이언트를 실행 중인지 확인하고 비활성화해도 문제가 지속되는지 시도해 보세요. 충돌을 피하고 VNet을 Tailscale이나 다른 VPN 클라이언트와 함께 실행하려면 VNet이 다른 IPv4 범위를 사용하도록 구성할 수 있습니다. 자세한 내용은 VNet 구성 가이드를 참고하세요.
VNet 없이 앱에 연결하기#
때로는 연결 문제가 VNet과 관련이 없을 수 있으며, VNet 없이 앱에 연결을 시도하여 문제를
좁혀 나갈 수 있습니다. 앱이 Connect 리소스 뷰나 tsh apps ls의 출력에 나타나는지 확인하세요.
VNet을 끄고 tsh proxy app -d <app-name>으로(디버그 로깅을 활성화한 상태로) 앱에 대한 로컬
프록시를 생성해 보세요.
macOS에서 Teleport 클러스터에 도달하려 할 때 발생하는 타임아웃#
갑작스러운 기기 종료와 같은 상황에서 VNet이 중지되기 전에 정리할 기회를 갖지 못하면,
/etc/resolver에 DNS 구성 파일이 남아 있을 수 있습니다. 이 파일들은 클러스터에 연결할 때
컴퓨터가 VNet이 운영하는 DNS 서버와 통신하도록 지시합니다. 하지만 VNet이 더 이상 실행되고
있지 않으므로, 이러한 호출에 응답할 DNS 서버가 없습니다.
이 파일들을 정리하려면 VNet을 다시 시작하기만 하면 됩니다. 또는 남아 있는 파일을 수동으로 제거할 수도 있습니다.
VNet이 DNS 쿼리를 수신하는지 확인하기#
Teleport Connect를 엽니다. 왼쪽 상단의 연결 패널에서 VNet을 선택합니다. VNet이 실행 중인지 확인한 다음 "진단 보고서 열기"를 선택합니다. VNet이 사용하는 IPv6 프리픽스와 IPv4 CIDR 범위를 기록해 두세요.
클러스터에서 사용 가능한 TCP 앱에 대한 쿼리를 전송합니다. tcp-app.teleport.example.com을 앱의 이름으로 바꾸세요:
$ dscacheutil -q host -a name tcp-app.teleport.example.com
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
# PowerShell에서.
$ Resolve-DnsName tcp-app.teleport.example.com
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
$ resolvectl query tcp-app.teleport.example.com
tcp-app.teleport.example.com: 100.68.51.151 -- link: TeleportVNet
fd60:67ec:4325::647a:547d -- link: TeleportVNet
-- Information acquired via protocol DNS in 3.9ms.
-- Data is authenticated: no; Data was acquired via local or encrypted transport: no
-- Data from: network
반환된 주소는 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을 선택한 다음 "진단 보고서 열기"를 선택합니다. 열린 보고서가 있는 새 탭에서 "보고서를 파일로 저장" 아이콘을 클릭합니다.
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
다음으로, 이슈를 재현해 보세요.
Teleport Connect에서 로그를 수집하려면, 앱 메뉴에서 Help → Open Logs Directory를 선택하여
~/Library/Application Support/Teleport Connect/logs를 Finder에서 엽니다. 이전 단계에서
생성된 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의 디버그 로그를 비활성화합니다:
$ 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에
저장되었습니다.
VNet에서 디버그 로그를 활성화하려면, 먼저 Teleport Connect를 중지합니다. 그런 다음 VNet systemd 서비스를 편집하여 디버그 환경 변수를 추가합니다:
$ sudo systemctl edit teleport-vnet.service
편집기에서 다음을 추가한 다음 저장하고 종료합니다:
[Service]
Environment=TELEPORT_DEBUG=1
새 설정을 적용하려면 서비스를 재시작합니다:
$ sudo systemctl restart teleport-vnet.service
다음으로, VNet 로그를 파일로 캡처하기 시작합니다:
$ journalctl -fu teleport-vnet.service > vnet.log
별도의 터미널에서, 디버그 로그가 활성화된 상태로 Teleport Connect를 시작합니다:
$ teleport-connect --connect-debug
다음으로, 이슈를 재현해 보세요.
완료되면, journalctl 출력 캡처를 중지한 다음 다음으로 VNet의 디버그 로그를 비활성화합니다:
$ sudo systemctl revert teleport-vnet.service
Teleport Connect에서 로그를 수집하려면, 이전 단계에서 생성된 vnet.log와 함께
~/.config/Teleport Connect/logs/의 모든 파일을 첨부하세요.