인포레터에서 최신 DevOps 트렌드를 격주로 만나보세요!
Teleport와 함께 PuTTY 및 WinSCP 사용하기
이 가이드는 Teleport 클라이언트 도구 tsh
를 사용하여 저장된 세션을 추가하는 방법과
PuTTY를 클라이언트로 사용하여 SSH 노드에 연결하는 방법을 보여줍니다.
그리고 이러한 저장된 세션을 선택적으로 WinSCP를 사용하여 SSH 노드에서 SFTP를 통해 파일을 전송하는 방법도 보여줍니다.
당신은 다음을 배울 것입니다:
- Teleport 클러스터에 연결된 SSH 노드를 위한 저장된 PuTTY 세션 생성.
- 이러한 저장된 PuTTY 세션을 사용하여 대화형 쉘에 로그인.
- (선택 사항) 저장된 PuTTY 세션을 WinSCP로 가져온 후 SSH 노드에서 파일을 전송하기 위한 SFTP 세션 시작.
필수 조건
-
Windows 10 이상이 실행되는 클라이언트 머신.
tsh
를 사용하여 PuTTY 세션을 저장할 수 있습니다. -
Teleport
tsh.exe
클라이언트, 버전 14.0.3 이상.tsh.exe
클라이언트를 다운로드하려면 다음 명령을 실행하세요:curl.exe -O https://cdn.teleport.dev/teleport-v17.0.0-dev-windows-amd64-bin.zip그런 다음 압축을 풀고
tsh.exe
를%PATH%
로 이동하세요.NoteWinSCP를 사용할 때 문제가 발생할 수 있으므로
System32
디렉토리에tsh.exe
를 두지 마세요. 대신 이미%PATH%
에 포함된%SystemRoot%
(예:C:\Windows
)를 사용해야 합니다.사용 중인 Windows 시스템에서 관리자 권한이 없으면
%USERPROFILE%
(예:C:\Users\<username>
)를 대신 사용할 수 있지만,tsh
명령을 전역적으로 커맨드 라인에서 실행할 수 없다는 점에 유의하세요.tsh.exe
와 동일한 디렉토리에 있어야 합니다. -
PuTTY for Windows 0.78 버전 이상. 최신 버전의 PuTTY는 PuTTY 다운로드 페이지에서 다운로드할 수 있습니다.
-
(선택 사항) WinSCP for Windows 6.2 버전 이상. 최신 버전의 WinSCP는 WinSCP 다운로드 페이지에서 다운로드할 수 있습니다.
요약
PuTTY에 저장된 세션을 추가하려면:
tsh login
명령을 사용하여 Teleport 클러스터에 로그인합니다:
tsh login --proxy=teleport.example.com
이 명령은 사용자 인증서를 검색하여 %USERPROFILE%/.tsh
디렉토리에 로컬 파일로 저장합니다.
- 클러스터 내에서 사용자가 연결할 수 있는 SSH 노드를 나열합니다:
tsh lsNode Name Address Labels----------------------------------- -------------- ----------------------------ip-172-31-30-140 127.0.0.1:3022 company=acmecorp,env=aws,...ip-172-31-34-128.us-east-2.compu... ⟵ Tunnel access=open,enhanced_reco...ip-172-31-8-63 172.31.8.63:22 type=openssh
- 특정 노드에서 특정 로그인에 대한 저장된 세션을 Windows 레지스트리에 추가합니다.
예를 들어, ip-172-31-30-140
노드에서 로그인 ubuntu
에 대한 저장된 세션을 Windows 레지스트리에 추가하려면 다음 명령을 실행합니다:
tsh puttyconfig ubuntu@ip-172-31-30-140Added PuTTY session for ubuntu@ip-172-31-30-140 [proxy:teleport.example.com]
이 명령에 로그인을 제공하지 않으면 로컬 Windows 사용자 이름이 대신 사용됩니다.
클러스터 내에서 등록된 OpenSSH 노드에 대한 세션을 추가하는 경우 (teleport join openssh
로 추가됨),
tsh puttyconfig
로 세션을 추가할 때 sshd
포트(보통 22)를 지정해야 합니다:
tsh puttyconfig --port 22 ubuntu@ip-172-31-8-63Added PuTTY session for ubuntu@ip-172-31-8-63 [proxy:teleport.example.com]
선택적으로 tsh puttyconfig user@host:22
를 사용할 수도 있습니다.
tsh login
명령을 사용하여 Teleport 클러스터에 로그인합니다:
tsh login --proxy=mytenant.teleport.sh
이 명령은 사용자 인증서를 검색하여 %USERPROFILE%/.tsh
디렉토리에 로컬 파일로 저장합니다.
- 클러스터 내에서 사용자가 연결할 수 있는 SSH 노드를 나열합니다:
$ tsh ls
Node Name Address Labels
----------------------------------- -------------- ----------------------------
ip-172-31-30-140 ⟵ Tunnel company=acmecorp,env=aws,...
ip-172-31-34-128.us-east-2.compu... ⟵ Tunnel access=open,enhanced_reco...
- 특정 노드에서 특정 로그인에 대한 저장된 세션을 Windows 레지스트리에 추가합니다.
예를 들어, ip-172-31-30-140
노드에서 로그인 ubuntu
에 대한 저장된 세션을 Windows 레지스트리에 추가하려면 다음 명령을 실행합니다:
tsh puttyconfig ubuntu@ip-172-31-30-140Added PuTTY session for ubuntu@ip-172-31-30-140 [proxy:mytenant.teleport.sh]
이 명령에 로그인을 제공하지 않으면 로컬 Windows 사용자 이름이 대신 사용됩니다.
PuTTY를 사용하여 저장된 세션으로 연결하기
- PuTTY를 시작하여 클러스터에 대한 저장된 세션을 확인합니다.

- 세션을 두 번 클릭하여 Teleport를 통해 호스트에 연결합니다.

호스트에 연결되면, Teleport는 세션 시작에 대한 감사 로그 항목을 생성하며, Teleport 내 "활성 세션" 목록에 나타납니다.
세션 안에서 teleport status
를 실행하여 Teleport 프록스를 통해 연결되었는지 확인하고,
세션 UUID를 출력하여 추적 목적으로 활용할 수 있습니다.
클러스터에 대한 세션 기록이 활성화된 경우, 세션을 종료하고 호스트에서 연결을 끊은 후
세션의 기록을 볼 수도 있습니다.
리프 클러스터
사용 가능한 리프 클러스터를 나열하려면, 다음 명령어를 실행합니다:
tsh clustersCluster Name Status Cluster Type Labels Selected----------------- ------ ------------ ------ --------teleport.example.com online root *example.teleport.sh online leaf
PuTTY 세션에서 리프 클러스터에 접근하려면 tsh puttyconfig
명령에 --leaf <leaf cluster name>
매개변수를 추가합니다.
예를 들어, 리프 클러스터의 이름이 example.teleport.sh
이고 노드가 ip-172-31-34-128.us-east-2.compute.internal
이라면,
아래의 명령어를 사용하여 로그인 ec2-user
를 위한 PuTTY 세션을 추가할 수 있습니다:
tsh puttyconfig --leaf example.teleport.sh ec2-user@ip-172-31-34-128.us-east-2.compute.internalAdded PuTTY session for ec2-user@ip-172-31-34-128.us-east-2.compute.internal [leaf:example.teleport.sh,proxy:teleport.example.com]
세션 명명
세션은 다음의 스키마를 사용하여 이름이 지정됩니다:
루트 클러스터: <login>@<hostname> [proxy:<proxy address>]
리프 클러스터: <login>@<hostname> [leaf:<leaf cluster name>,proxy:<proxy address>]
SFTP를 이용한 파일 전송을 위한 WinSCP 사용
PuTTY에서 저장된 세션을 WinSCP로 가져오면 SSH 노드에 연결하여 파일을 전송할 수 있습니다.
- WinSCP를 시작합니다.
WinSCP가 시작될 때 사이트 관리자 "로그인" 대화 상자가 세션 목록과 함께 표시되지 않으면, Tabs 메뉴를 클릭하고 Sites를 선택한 후 **Site Manager...**를 클릭하여 표시합니다.

- 좌측 하단에서 Tools 버튼을 클릭한 후 Import Sites를 선택합니다.

- WinSCP에서 사용하려는 저장된 PuTTY 세션 옆의 체크박스를 선택한 후 "OK" 버튼을 클릭합니다.
연결하려는 호스트와 일치하는 세션이 보이지 않으면 이 상자를 닫고
터미널에서 tsh puttyconfig <user>@<host>
를 실행하여 세션을 추가한 후
이 단계를 반복합니다. 위에서 설명한대로 실행합니다.

- WinSCP가 PuTTY에서 저장된 호스트 CA를 신뢰하고 로드하도록 하려면 좌측 하단에서 Tools를 다시 클릭하고 **Preferences...**를 선택합니다.
이전에 이 과정을 완료한 경우 나머지 단계를 건너뛰십시오
이전에 이 PC에서 이 사용자로 과정을 완료한 경우 4단계와 5단계를 건너뛸 수 있습니다.

- 왼쪽에서 Security 섹션을 클릭한 후 신뢰할 수 있는 호스트 인증 기관 섹션에서 Load authorities from PuTTY 체크박스를 선택하고 OK를 클릭하여 종료합니다.

- 왼쪽 목록에서 연결할 호스트를 선택하고 Login을 클릭합니다. 원하는 경우 이름을 두 번 클릭하여 세션을 시작할 수도 있습니다.

Teleport를 통해 WinSCP를 사용하여 파일을 업로드하거나 다운로드하는 것은 감사 이벤트를 생성합니다.
자주 묻는 질문
tsh puttyconfig
를 실행하기 위해 내 컴퓨터에서 관리자 권한이 필요합니까?
아니요, tsh
는 HKEY_CURRENT_USER
레지스트리 키만 변경합니다.
모든 사용자의 저장된 PuTTY 세션을 추가할 수 있습니까?
아니요, 세션은 현재 사용자에게만 추가됩니다. 다른 사용자가 사용할 수 있도록 세션을 내보내려면 아래에서 설명하는 레지스트리 내보내기 방법을 사용할 수 있습니다.
저장된 PuTTY 세션을 다른 컴퓨터로 내보낼 수 있습니까?
예, 레지스트리 편집기를 사용하여 HKEY_CURRENT_USER\Software\SimonTatham\PuTTY
레지스트리 키를 파일로 내보내고 이 파일을 다른 컴퓨터에서 가져올 수 있습니다. 레지스트리 편집기를 실행하려면 관리자 권한이 필요합니다.
저장된 PuTTY 세션의 글꼴 크기, 창 크기 또는 기타 기본 설정을 변경할 수 있습니까?
세션이 추가된 후, PuTTY UI에서 "저장된 세션" 목록에서 세션 이름을 클릭한 다음 로드를 클릭하여 변경할 수 있습니다. 필요한 모든 변경을 한 다음, 세션을 다시 선택하고 저장을 클릭합니다.
특정 호스트에 대해 tsh puttyconfig
를 다시 실행하면 저장된 세션에 대한 사용자 정의 변경 사항이 덮어쓰여집니까?
Teleport는 프록시 이름, 프록시 명령, 호스트 이름, 사용자 이름, 포트 등과 같이 의존하는 구성 매개변수만 수정합니다. 글꼴 크기, 창 크기 및 기타 매개변수에 대한 변경 사항은 그대로 유지됩니다.
MobaXterm 또는 SecureCRT와 같은 다른 그래픽 클라이언트를 사용할 수 있습니까?
현재 PuTTY만 지원됩니다. 대부분의 다른 그래픽 클라이언트는 인증을 위한 SSH 사용자 인증서와 SSH 호스트 인증서를 모두 완전히 지원하지 않으며, 이는 Teleport를 사용하기 위한 요구 사항입니다.
Teleport 세션 추가 지원을 원하시면 해당 클라이언트의 개발자에게 문의하시기 바랍니다.
KiTTY 또는 Solar PuTTY와 같은 PuTTY의 포크를 사용할 수 있습니까?
포크가 PuTTY 0.78 이상의 버전을 기반으로 한다면 작동할 수 있습니다. 그러나 Teleport 팀은 기본 버전의 PuTTY만 테스트하며 포크된 버전에 대한 지원을 제공할 수 없습니다.
저장된 Teleport PuTTY 세션을 WinSCP와 함께 사용할 수 있습니까?
예, WinSCP 버전 6.2 이상은 Teleport를 사용하여 연결하는 데 필요한 SSH 호스트 인증서를 사용한 유효성 검사를 지원합니다.
저장된 세션과 함께 다른 Teleport 인증 방법(tsh login --auth
)을 사용할 수 있습니까?
아니요, PuTTY는 tsh proxy ssh
를 호출하며, 이는 Teleport 클러스터에 대해 구성된 기본 인증 방법을 사용합니다.
Teleport 인증에 대한 자세한 내용은 인증 옵션을 참조하십시오.
가급적 고급 사용자들은 레지스트리 편집기를 사용하여 ProxyTelnetCommand
키 아래에서 PuTTY 프록시 명령을 직접 수정할 수 있습니다. 주의할 점은 특정 호스트 이름에 대해 tsh puttyconfig
를 다시 실행하면 이 명령이 덮어쓰여진다는 것입니다.
문제 해결
WinSCP에서 서버가 네트워크 연결을 예상하지 못하게 종료했습니다
또는 오류 232: 파이프가 닫히고 있습니$1
가 표시될 때 연결 문제
이 오류는 일반적으로 tsh.exe
애플리케이션이 C:\Windows\System32
디렉토리에 잘못 배치되었을 때 발생합니다. 이로 인해 WinSCP에 버그가 발생하여 런타임 중에 tsh.exe
의 경로가 잘못 교체되어 연결 실패를 초래합니다. 이 버그는 PuTTY 세션에는 영향을 미치지 않는 것 같습니다.
다음은 이 버그의 영향을 받지 않는 tsh.exe
를 저장할 수 있는 두 가지 위치입니다:
%SystemRoot%
(예:C:\Windows
- 관리자 권한이 필요하며 기본적으로%PATH%
에 포함됨)%USERPROFILE
(예:C:\Users\<username>
- 관리자 권한이 필요하지 않음)
이 문제를 해결하려면 다음 단계를 따르십시오:
- 위에 설명한 대로
tsh.exe
애플리케이션을 다른 디렉토리에 배치하십시오. - 각 PuTTY 세션에 대해
tsh puttyconfig
를 다시 실행하여 세션 내의tsh.exe
에 대한 구성된 경로를 교체하십시오. - WinSCP에 있는 각 저장된 세션을 삭제하십시오.
- 단계 2-3에서 설명한 절차에 따라 WinSCP에 저장된 PuTTY 세션을 다시 가져오십시오.
proxy: 오류: <user>가 <proxy>에 연결을 거부당했습니$1
tsh puttyconfig
명령에 잘못된 로그인 사용자 이름을 제공했습니다. Teleport 사용자/역할이 사용할 수 있는 로그인 사용자 이름으로 명령을 다시 실행하십시오. logins
역할 사양 또는 사용자 특성에 나열된 로그인을 확인하십시오.
tsh ssh
로 성공적으로 로그인할 수 있다면, tsh puttyconfig
를 사용하여 이름 로그인/호스트 이름을 사용할 수 있어야 합니다.
연결 실패 [ssh: 핸드셰이크 실패: ssh: 인증할 수 없음, 시도한 방법 [none publickey], 지원되는 방법 없음]
OpenSSH 서버에 연결하려고 할 때 tsh puttyconfig
명령에 잘못된 로그인 사용자 이름을 제공했습니다. Teleport 사용자/역할이 사용할 수 있는 로그인 사용자 이름으로 명령을 다시 실행하십시오. logins
역할 사양 또는 사용자 특성에 나열된 로그인을 확인하십시오.
tsh ssh
로 성공적으로 로그인할 수 있다면, tsh puttyconfig
를 사용하여 이름 로그인/호스트 이름을 사용할 수 있어야 합니다.
proxy: 오류: ssh: 서브시스템 요청 실$1
Teleport 프록시는 저장된 세션에 제공된 호스트/포트에 연결할 수 없습니다. 이는 노드가 오프라인임을 의미할 수 있습니다. tsh ls
에서 노드가 표시되는지 확인하고, tsh ssh login@hostname
으로 연결할 수 있는지 확인하십시오. 성공적이라면 Teleport 프록시 로그에서 더 상세한 오류를 확인하십시오.
노드가 Teleport가 아닌 OpenSSH를 실행 중이라면, 세션을 추가할 때 sshd
포트를 지정해야 합니다. 예를 들어 tsh puttyconfig --port 22 user@host
또는 tsh puttyconfig user@host:22
를 사용하십시오.
proxy: 인벤토리에 없는 노드에 대한 직접 다이얼링은 지원되지 않습니$1
이 오류는 일반적으로 에이전트 없는 OpenSSH 호스트(즉, sshd를 실행하는 호스트)를 등록하면서 포트를 제공하지 않아 발생합니다. tsh puttyconfig
를 사용할 때 올바른 포트(예: 22)를 사용하여 호스트를 다시 추가해 보십시오.
포트를 수정한 후에도 여전히 이 오류가 발생하면, 연결하려는 호스트가 tsh ls
의 출력에 나타나는지 확인하십시오. tsh ls
의 출력에 나타나지 않는 호스트 이름은 연결 불가능합니다.
인증서 파일 "C:\Users\<username>\.tsh\keys\<proxy>\<user>-ssh\<cluster>-cert.pub"를 사용할 수 없습니다 (파일을 열 수 없음)
Teleport에 올바르게 로그인하지 않았습니다. 유효한 인증서를 얻으려면 tsh login --proxy=<proxy hostname>
을 실행하여 PuTTY 저장된 세션을 시작하세요.
리프 클러스터의 저장된 세션을 루트 클러스터의 프록시를 사용하여 사용하는 경우, 리프 클러스터에 대한 세션을 시작할 수 있도록 루트 클러스터에 로그인해야 합니다.
오류: 프록시 주소가 지정되지 않았습니다. --proxy 플래그를 놓쳤습니까?
로컬에 유효한 tsh
자격 증명이 없습니다. 먼저 로그인하려면 tsh login --proxy=<proxy hostname>
을 실행하거나 tsh puttyconfig
를 실행할 때 --proxy
매개변수를 제공하십시오.
오류: TeleportHostCA-<cluster_name>의 유효성 문자열...
유효성 문자열과 관련된 모든 오류는 특정 호스트 CA에 대해 신뢰해야 하는 호스트 이름 목록을 보관하는 PuTTY 레지스트리 키의 잘못된 형식으로 인해 발생합니다. 잘못된 형식은 일반적으로 PuTTY GUI나 레지스트리 편집기에서 호스트 CA 레코드를 수동으로 편집함으로써 발생하며, 이는 결코 필요하지 않으며 강력히 권장되지 않습니다.
이 오류를 수정하려면, PuTTY를 열고 왼쪽에서 SSH -> Host Keys -> Configure Host CAs로 이동합니다. 오류에서 일치하는 TeleportHostCA-<cluster_name>
호스트 CA 레코드를 선택하고 로드 버튼을 클릭합니다. "유효 호스트 이 키가 인증한다고 신뢰하는" 아래의 항목을 수동으로 수정할 수 있습니다 - 형식은 <hostname> || <hostname> || ...
를 따라야 하며, 또는 삭제 버튼을 클릭할 수 있습니다.
호스트 CA 레코드를 삭제하면 PuTTY를 통해 접근할 수 있는 모든 Teleport SSH 서비스에 대해 tsh puttyconfig
를 다시 실행해야 합니다. 저장된 세션이 여전히 존재해도 마찬가지입니다.
일상적인 작업 중에 이 오류가 발생하면 이는 버그이며 GitHub를 통해 보고해야 합니다.
tsh 제거하기
tsh
및 관련 사용자 데이터를 제거하려면
Teleport 제거하기를 참조하세요.