이 가이드는 Teleport 클라이언트 도구인 tsh 를 사용하는 방법을 보여줍니다.

다음과 같은 내용을 배우게 됩니다:

• 원격 클러스터 노드에서 대화형 셸에 로그인합니다.
• 클러스터 노드로 파일을 복사하고 클러스터 노드에서 파일을 복사합니다.
• 열린 포트 없이 방화벽 뒤의 SSH 클러스터에 SSH 역 터널을 사용하여 연결합니다.
• 클러스터를 탐색하고 클러스터 내 특정 노드에서 명령을 실행합니다.
• 동료와 대화형 셸 세션을 공유하거나 다른 사람의 세션에 참여합니다.
• 기록된 대화형 세션을 나열하고 재생합니다.

이 문서 외에도 언제든지 터미널에 tsh 를 입력하여 CLI 참조를 얻을 수 있습니다.

소개

조급한 분들을 위해 사용자가 일반적으로 tsh 를 사용하는 예시입니다:

Teleport 클러스터에 로그인합니다. 이 명령은 사용자의 인증서를 검색하여
~/.tsh/teleport.example.com 에 저장합니다.
tsh login --proxy=teleport.example.com

노드에 SSH로 접속합니다.
tsh ssh user@node

`tsh ssh` 는 OpenSSH 클라이언트와 동일한 인수를 사용합니다:
tsh ssh -o ForwardAgent=yes user@node
tsh ssh -o AddKeysToAgent=yes user@node

편리한 심볼릭 링크를 생성할 수도 있습니다:
ln -s /path/to/tsh /path/to/ssh

... 이제 'ssh' 명령이 Teleport의 `tsh ssh` 를 호출합니다.
ssh user@host

이 명령은 사용자의 머신에서 SSH 인증서를 제거합니다:
tsh logout

Teleport 클러스터에 로그인합니다. 이 명령은 사용자의 인증서를 검색하여
~/.tsh/mytenant.teleport.sh 에 저장합니다.
tsh login --proxy=mytenant.teleport.sh

노드에 SSH로 접속합니다.
tsh ssh user@node

`tsh ssh` 는 OpenSSH 클라이언트와 동일한 인수를 사용합니다:
tsh ssh -o ForwardAgent=yes user@node
tsh ssh -o AddKeysToAgent=yes user@node

편리한 심볼릭 링크를 생성할 수도 있습니다:
ln -s /path/to/tsh /path/to/ssh

... 이제 'ssh' 명령이 Teleport의 `tsh ssh` 를 호출합니다.
ssh user@host

이 명령은 사용자의 머신에서 SSH 인증서를 제거합니다:
tsh logout

다시 말해, Teleport는 기존 SSH 기반 워크플로와 완벽하게 호환되도록 설계되었으며, 사용자가 새로운 것을 배우지 않고도 tsh login 을 처음에 호출하기만 하면 됩니다.

tsh 설치

tsh 바이너리를 설치하려면 아래의 지침을 따르십시오.

Teleport 클러스터에서 사용된 것과 동일한 주요 버전의 tsh 설치를 권장합니다.

버전 번호를 찾으려면 다음 방법 중 하나를 사용하세요:

• 웹 UI에서 오른쪽 위에 있는 사용자 이름을 선택한 후 도움말 및 지원을 클릭합니다. 그러면 클러스터 정보 아래에서 Teleport 클러스터의 버전을 확인할 수 있습니다.

• curl 과 jq 를 사용합니다. teleport.example.com 을 Proxy Service 주소(예: Teleport Enterprise Cloud의 경우 mytenant.teleport.sh )로 교체하세요:

  curl https://teleport.example.com/webapi/find | jq '.server_version'
  "17.0.0-dev"

curl -O https://cdn.teleport.dev/tsh-17.0.0-dev.pkg

curl.exe -O https://cdn.teleport.dev/teleport-v17.0.0-dev-windows-amd64-bin.zip
아카이브를 풀고 `tsh.exe` 를 %PATH%에 이동합니다.
NOTE: WinSCP를 사용할 때 문제를 일으킬 수 있으므로 tsh.exe를 System32 디렉터리에 두지 마십시오.
대신 %SystemRoot% (C:\Windows) 또는 %USERPROFILE% (C:\Users\<username>)를 사용하십시오.

curl -O https://cdn.teleport.dev/teleport-v17.0.0-dev-linux-amd64-bin.tar.gz
tar -xzf teleport-v17.0.0-dev-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
Teleport 바이너리가 /usr/local/bin에 복사되었습니다.

사용자 ID

Teleport에서 사용자 ID는 클러스터의 범위 내에 존재합니다. 클러스터의 구성원 노드에는 여러 개의 OS 사용자가 있을 수 있습니다. Teleport 관리자는 모든 Teleport 사용자 계정에 허용된 로그인 정보를 할당합니다.

원격 노드에 로그인할 때는 Teleport 로그인과 OS 로그인을 모두 지정해야 합니다. Teleport ID는 --user 플래그를 통해 전달되어야 하며, OS 로그인은 전통적인 ssh 명령과 호환되는 구문을 사용하여 login@host 형식으로 전달됩니다.

'work' 클러스터에 joe로 인증한 후
노드에 root로 로그인합니다:
tsh ssh --proxy=work.example.com --user=joe root@node

'work' 클러스터에 joe로 인증한 후
노드에 root로 로그인합니다:
tsh ssh --proxy=mytenant.teleport.sh --user=joe root@node

CLI 문서 - tsh ssh

로그인하기

사용자의 인증서를 가져오려면 다음을 실행하십시오:

전체 형식:
tsh login --proxy=proxy_host:<https_proxy_port>

기본 포트 사용:
tsh login --proxy=work.example.com

사용자 지정 HTTPS 포트 사용:
tsh login --proxy=work.example.com:5000

전체 형식:
tsh login --proxy=proxy_host:<https_proxy_port>

tsh login --proxy=mytenant.teleport.sh

CLI 문서 - tsh login

로그인 명령은 사용자의 인증서를 가져와 ~/.tsh 디렉토리와 ssh agent에 저장합니다(실행 중인 경우).

이것은 당신이 하루의 시작 시 한 번만 인증하면 되게 합니다. 이후의 tsh ssh 명령은 임시 인증서가 만료될 때까지 자격 증명을 묻지 않고 실행됩니다. 기본적으로 Teleport는 사용자 인증서를 12시간의 유효 기간(TTL)을 가지고 발급합니다.

Teleport 클러스터는 여러 사용자 ID 소스를 구성할 수 있습니다. 예를 들어, 클러스터에는 admin 이라는 로컬 사용자가 있을 수 있으며, 일반 사용자는 GitHub를 통해 인증해야 합니다. 이 경우 tsh login 에 --auth 플래그를 전달하여 사용할 ID 저장소를 지정해야 합니다:

로컬 Teleport 'admin' 사용자로 로그인:
tsh --proxy=proxy.example.com --auth=local --user=admin login

GitHub를 SSO 제공자로 사용하여 로그인, GitHub 커넥터의 이름이 "github"라고 가정
tsh --proxy=proxy.example.com --auth=github login

로컬 Teleport 'admin' 사용자로 로그인:
tsh --proxy=mytenant.teleport.sh --auth=local --user=admin login

GitHub를 SSO 제공자로 사용하여 로그인, GitHub 커넥터의 이름이 "github"라고 가정
tsh --proxy=mytenant.teleport.sh --auth=github login

외부 ID 공급자를 사용하여 로그인할 때 tsh 는 인증 흐름을 완료하기 위해 웹 브라우저를 열어야 합니다. 기본적으로 tsh 는 시스템의 기본 브라우저를 사용합니다. 이 동작을 억제하려면 --browser=none 플래그를 사용할 수 있습니다:

로그인할 때 시스템 기본 브라우저를 열지 않음
tsh login --proxy=work.example.com --browser=none

로그인할 때 시스템 기본 브라우저를 열지 않음
tsh login --proxy=mytenant.teleport.sh --browser=none

이 경우, 화면에 링크가 인쇄됩니다. 이 링크를 복사하여 원하는 브라우저에 붙여넣어 로그인 흐름을 계속할 수 있습니다.

CLI 문서 - tsh login

SSH 인증서 검사

~/.tsh 에 있는 SSH 인증서를 검사하려면 사용자가 다음 명령어를 실행할 수 있습니다:

tsh status

> 프로파일 URL:  https://proxy.example.com:3080
로그인 사용자: johndoe
클러스터:      proxy.example.com
역할:        access, auditor, editor
로그인:       root, admin, guest
Kubernetes:   활성화됨
유효 기간:  2017-04-25 15:02:30 -0700 PDT [유효 기간 1h0m0s]
확장 기능:   permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh status

> 프로파일 URL:  https://mytenant.teleport.sh:443
로그인 사용자: johndoe
클러스터:      mytenant.teleport.sh
역할:        access, editor, auditor
로그인:       root, admin, guest
Kubernetes:   활성화됨
유효 기간:  2017-04-25 15:02:30 -0700 PDT [유효 기간 1h0m0s]
확장 기능:   permit-agent-forwarding, permit-port-forwarding, permit-pty

CLI Docs - tsh status

SSH 에이전트 지원

만약 ssh agent 가 실행 중이라면, tsh login 은 사용자 인증서를 에이전트에 저장합니다. 이는 다음을 통해 확인할 수 있습니다:

ssh-add -L

SSH 에이전트는 인증서를 다른 SSH 클라이언트에 공급하는 데 사용할 수 있습니다. 예를 들어, OpenSSH(ssh )에 사용할 수 있습니다.

SSH 에이전트 통합을 비활성화하려면 --no-use-local-ssh-agent 를 tsh 에 전달하면 됩니다. 또한, 이 설정을 영구적으로 유지하려면, 셸 프로파일에서 TELEPORT_USE_LOCAL_SSH_AGENT 환경 변수를 false 로 설정할 수 있습니다.

인증서 파일

tsh login 은 사용자 인증서를 파일에 저장할 수도 있습니다:

proxy.example.com에서 사용자 인증을 수행하고, 사용자
인증서를 joe.pem에 저장합니다.
tsh login --proxy=proxy.example.com --out=joe

joe.pem을 사용하여 'db' 서버에 로그인합니다.
tsh ssh --proxy=proxy.example.com -i joe joe@db

mytenant.teleport.sh에서 사용자 인증을 수행하고, 사용자
인증서를 joe.pem에 저장합니다.
tsh login --proxy=mytenant.teleport.sh --out=joe

joe.pem을 사용하여 'db' 서버에 로그인합니다.
tsh ssh --proxy=mytenant.teleport.sh -i joe joe@db

기본적으로 --out 플래그는 tsh -i 에 적합한 인증서 파일을 생성합니다. OpenSSH와의 호환성이 필요하다면 --format=openssh 를 지정해야 합니다. 이 경우, 인증서는 두 개의 파일 joe 와 joe-cert.pub 에 저장됩니다:

tsh login --proxy=proxy.example.com --out=joe --format=openssh
ls -lh

총 8.0K
-rw------- 1 joe staff 1.7K Aug 10 16:16 joe
-rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub

tsh login --proxy=mytenant.teleport.sh --out=joe --format=openssh
ls -lh

총 8.0K
-rw------- 1 joe staff 1.7K Aug 10 16:16 joe
-rw------- 1 joe staff 1.5K Aug 10 16:16 joe-cert.pub

자동화를 위한 SSH 인증서

Teleport의 정기 사용자들은 일반적으로 매일 자동 만료되는 SSH 인증서를 요청해야 합니다. 이는 cron 작업이나 CI/CD 파이프라인과 같은 비대화형 스크립트에서는 작동하지 않습니다.

자동화 목적으로 인증서를 생성하는 가장 안전한 방법은 Machine ID를 사용하는 것입니다. 이것은 귀하의 자동화가 단기 자격 증명의 보안 속성을 활용할 수 있도록 보장합니다.

Machine ID가 선호하는 CI/CD 플랫폼을 지원하지 않는 경우, 자동화를 위해 사용할 로컬 사용자를 생성하고 해당 사용자에 대해 장기 인증서를 요청할 수 있습니다.

이 예제에서는 jenkins 사용자에 대해 TTL이 1시간인 인증서를 생성하고 이를 jenkins.pem 파일에 저장하며, 이는 나중에 tsh 의 -i (identity) 플래그와 함께 사용될 수 있습니다.

로컬 머신에서 tctl을 사용할 수 있도록 tsh를 통해 클러스터에 로그인합니다.
"tsh login"을 먼저 실행하지 않고도 Auth Service 호스트에서 tctl을 실행할 수 있습니다.
tsh login --proxy=teleport.example.com --user=myuser
tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem

로컬에서 tctl을 사용하려면 Teleport Cloud 클러스터에 로그인합니다.
tsh login --proxy=myinstance.teleport.sh --user=email@example.com
tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem

CLI Docs - tctl auth sign

이제 jenkins.pem 파일을 Jenkins 서버로 복사하여 tsh 의 -i (identity file) 플래그에 전달할 수 있습니다.

tctl auth sign 은 관리자의 tsh login --out 과 동등하며 제한 없는 인증서 TTL 값을 허용합니다.

클러스터 탐색

Teleport 클러스터에서 모든 노드는 주기적으로 클러스터의 Auth Service에 ping을 보내고 상태를 업데이트합니다. 이를 통해 Teleport 사용자는 tsh ls 명령어를 사용하여 온라인인 노드를 확인할 수 있습니다:

이 명령어는 "tsh login"을 통해 로그인한 클러스터의 모든 노드를 나열합니다:
tsh ls

Node Name     Address            Labels
---------     -------            ------
turing        ⟵ Tunnel          os=linux
graviton      10.1.0.7:3022      os=osx

CLI Docs - tsh ls

tsh ls 는 노드 레이블을 기반으로 필터를 적용할 수 있습니다.

os 레이블이 'osx'인 노드만 표시합니다:
tsh ls os=osx

Nodename      Address            Labels
---------     -------            ------
graviton      10.1.0.7:3022      os=osx

CLI Docs -tsh ls

대화형 셸

원격 노드에서 대화형 셸을 시작하거나 명령을 실행하려면 tsh ssh 를 사용합니다.

tsh 는 가능한 한 ssh 경험을 모방하려고 하므로 -p , -l 또는 -L 과 같은 가장 인기 있는 ssh 플래그를 지원합니다. 예를 들어, ~/.bashrc 에 다음과 같은 별칭이 정의되어 있다면: alias ssh="tsh ssh" 계속해서 익숙한 SSH 구문을 사용할 수 있습니다:

이 별칭이 ~/.bashrc를 통해 구성되어 있다고 가정합니다.
alias ssh="/usr/local/bin/tsh ssh"

클러스터에 로그인하고 SSH 인증서를 가져옵니다:
tsh --proxy=proxy.example.com login

이 명령들은 내부적으로 `tsh ssh` 를 실행합니다:
ssh user@node
ssh -p 6122 user@node ls
ssh -o ForwardAgent=yes user@node
ssh -o AddKeysToAgent=yes user@node

이 별칭이 ~/.bashrc를 통해 구성되어 있다고 가정합니다.
alias ssh="/usr/local/bin/tsh ssh"

클러스터에 로그인하고 SSH 인증서를 가져옵니다:
tsh --proxy=mytenant.teleport.sh login

이 명령들은 내부적으로 `tsh ssh` 를 실행합니다:
ssh user@node
ssh -p 6122 user@node ls
ssh -o ForwardAgent=yes user@node
ssh -o AddKeysToAgent=yes user@node

tsh --proxy=proxy.example.com:5000 <subcommand>

포트 포워딩

tsh ssh 는 로컬호스트에서 지정된 원격 호스트:포트로의 수신 연결을 포워딩하는 OpenSSH -L 플래그를 지원합니다. -L 플래그의 구문은 다음과 같으며, "bind_ip"는 기본적으로 127.0.0.1 로 설정됩니다:

-L [bind_ip]:listen_port:remote_host:remote_port

예:

tsh ssh -L 5000:web.remote:80 node

이것은 프록시 서비스를 통해 원격 서버 node 에 연결한 다음, localhost:5000 에서 수신 소켓을 엽니다. 마지막으로 모든 수신 연결을 이 SSH 터널을 통해 web.remote:80 으로 포워딩합니다.

포트 포워딩을 설정하고 연결을 사용하는 로컬 명령어를 실행한 다음, 연결을 끊는 것이 종종 편리합니다. --local 플래그를 사용하여 이를 수행할 수 있습니다.

예:

tsh ssh -L 5000:google.com:80 --local node curl http://localhost:5000

이 명령어는:

• node 에 연결합니다.
• 로컬 포트 5000 을 google.com 의 포트 80 에 바인딩합니다.
• 로컬에서 curl 명령어를 실행하여, curl 이 node 를 통해 google.com:80 에 도달하게 합니다.

SSH 점프 호스트

Teleport를 위한 ProxyJump 를 구현할 때, 우리는 이 기능을 tsh 로 확장했습니다.

tsh ssh -J proxy.example.com telenode

tsh ssh -J mytenant.teleport.sh telenode

알려진 제한 사항:

• 점프 호스트는 하나만 지원됩니다 (-J 는 Teleport에서 사용하지 않는 체인을 지원하지만), 두 개의 점프 호스트의 경우 tsh 가 오류와 함께 반환됩니다. 예: -J proxy-1.example.com,proxy-2.example.com 은 작동하지 않습니다.
• tsh ssh -J user@proxy 를 사용하면, tsh 프로필에 정의된 SSH 프록시를 덮어쓰고, 기존 Teleport 프록시 서브시스템 대신 포트 포워딩이 사용됩니다.

노드 이름 확인

tsh 는 원격 노드 이름을 확인하는 여러 방법을 지원합니다.

• 전통적인 방법: IP 주소 또는 DNS를 통해.
• 노드 이름 설정: teleport 데몬은 nodename 플래그를 지원하여 Teleport 관리자가 대체 노드 이름을 할당할 수 있습니다.
• 레이블: name=value 쌍으로 노드를 주소 지정할 수 있습니다.

os:linux 레이블을 가진 노드와 os:osx 노드가 있는 경우, 다음과 같이 OSX 노드에 로그인할 수 있습니다:

tsh ssh os=osx

이는 os:osx 레이블을 가진 원격 노드가 하나만 있을 때만 작동하지만, 레이블을 선택기로 사용하여 여러 노드에서 SSH를 통해 명령어를 실행할 수 있습니다. 이 명령어는 리눅스 머신에서 모든 시스템 패키지를 업데이트합니다:

tsh ssh os=ubuntu apt-get update -y

단기 세션

Teleport 사용자 인증서의 기본 TTL은 12시간입니다. 이는 --ttl 플래그를 사용하여 로그인 시 수정할 수 있습니다. 이 명령은 매우 짧은 시간(1분) 동안의 임시 인증서로 클러스터에 로그인합니다:

tsh --ttl=1 login

1분 후에 로그아웃되지만, 즉시 로그아웃하려면 언제든지 다음 명령을 실행할 수 있습니다:

tsh logout

파일 복사

클러스터 노드 간에 파일을 안전하게 복사하려면 tsh scp 명령을 사용합니다. 이 명령은 가능하면 OpenSSH의 scp 명령을 모방하도록 설계되었습니다:

tsh scp example.txt root@node:/path/to/dest

마찬가지로, alias scp="tsh --proxy=work scp" 와 같은 bash 별칭을 만들고 익숙한 구문을 사용할 수 있습니다:

scp -P 61122 -r files root@node:/path/to/dest

Teleport는 SCP 및 SFTP 프로토콜 모두를 지원합니다. 원한다면 OpenSSH scp 또는 sftp 명령을 tsh scp 대신 사용할 수 있습니다.

세션 공유

원격 서버에서 문제가 발생하고 있다고 가정해 봅시다. 때때로 다른 팀원에게 도움을 요청하는 것이 합리적입니다. 전통적으로는 자신이 있는 호스트를 알리고, 그들이 SSH로 로그인하여 screen 과 같은 터미널 멀티플렉서를 시작하고 거기에서 세션에 참여하도록 할 수 있었습니다.

Teleport는 이를 더 편리하게 만들어줍니다. 'luna'라는 서버에 로그인하고 현재 세션 상태를 확인하기 위해 Teleport에 요청해 보겠습니다:

tsh ssh luna
on host luna
teleport status

사용자 ID    : joe, joe로 로그인됨 (10.0.10.1 43026 3022에서)
세션 ID : 7645d523-60cb-436d-b732-99c5df14b7c4
세션 URL: https://work:3080/web/sessions/7645d523-60cb-436d-b732-99c5df14b7c4

이제 다른 사용자 계정을 work 클러스터에 초대할 수 있습니다. 웹 브라우저를 통해 접근할 수 있는 URL을 공유하거나 세션 ID를 공유하여 다른 사용자가 다음 명령어를 통해 자신의 터미널에서 참여할 수 있습니다:

tsh join <session_ID>

방화벽 뒤에 있는 SSH 클러스터에 연결

Teleport는 열려 있는 수신 TCP 포트 없이 방화벽 뒤에 있는 서버 클러스터를 생성하는 것을 지원합니다. 이는 방화벽 뒤의 환경에서 Teleport Proxy 서비스로의 역 SSH 터널을 생성함으로써 작동합니다.

방화벽 뒤의 클러스터 간에 신뢰 관계를 설정하는 방법에 대한 자세한 내용은 Configure Trusted Clusters를 참조하십시오.

tsh --proxy=work clusters

클러스터 이름     상태
------------     ------
staging          online
production       offline

tsh --proxy=mytenant.teleport.sh clusters

클러스터 이름     상태
------------     ------
staging          online
production       offline

CLI Docs - tsh clusters

이제 tsh 명령과 함께 --cluster 플래그를 사용할 수 있습니다. 예를 들어, production 클러스터의 SSH 노드를 목록화하려면 간단히 다음을 실행하세요:

tsh --proxy=work ls --cluster=production

노드 이름     노드 ID       주소              레이블
---------     -------       -------          ------
db-1          xxxxxxxxx     10.0.20.31:3022  kernel:4.4
db-2          xxxxxxxxx     10.0.20.41:3022  kernel:4.2

tsh --proxy=mytenant.teleport.sh ls --cluster=production

노드 이름     노드 ID       주소              레이블
---------     -------       -------          ------
db-1          xxxxxxxxx     10.0.20.31:3022  kernel:4.4
db-2          xxxxxxxxx     10.0.20.41:3022  kernel:4.2

마찬가지로 production 클러스터 내의 db-1 에 SSH로 연결하고 싶다면:

tsh --proxy=work ssh --cluster=production db-1

tsh --proxy=mytenant.teleport.sh ssh --cluster=production db-1

X11 포워딩

SSH 세션 내에서 그래픽 프로그램을 실행하려면, Virtual Studio Code와 같은 IDE를 사용하여, -X 플래그를 사용하여 세션에 대한 X11 포워딩을 요청해야 합니다.

tsh ssh -X node01

X11 포워딩은 서버가 로컬 X 서버에 안전하게 접근할 수 있도록 하여, 서버가 로컬 디스플레이 및 I/O 장치와 직접 통신할 수 있게 해줍니다.

X11 포워딩을 사용하려면 Teleport 노드에서 이를 활성화해야 합니다. 또한, 사용자가 permit_x11_forwarding 역할 옵션을 갖고 있는지 확인해야 합니다:

tsh status
> 프로필 URL:        https://proxy.example.com:3080  로그인한 사용자:   dev  ...  확장:             permit-X11-forwarding

사용자 정의 별칭 및 기본값

tsh 를 구성하여 별칭, 사용자 정의 명령 및 명령별 플래그 기본값을 정의할 수 있습니다. 별칭을 사용하면 자주 사용하는 tsh 명령을 더 쉽게 실행할 수 있습니다.

별칭은 다음 구문을 사용하여 구성 파일에 정의됩니다:

aliases:
  "<alias>": "<command>"

<alias>는 최상위 서브 커맨드만 될 수 있습니다. 즉, tsh mycommand 별칭은 정의할 수 있지만 tsh my command 는 정의할 수 없습니다.

tsh 는 두 가지 유형의 구성 파일을 불러옵니다:

• 전역: 제공되지 않는 경우 $TELEPORT_GLOBAL_TSH_CONFIG 환경 변수를 통해 설정하며, 비 윈도우 운영 체제에서는 기본적으로 /etc/tsh.yaml 으로 설정됩니다.
• 사용자별: $TELEPORT_HOME/config/config.yaml , 기본적으로 ~/.tsh/config/config.yaml 로 해결됩니다.

tsh 는 사용자별 구성과 전역 구성을 병합합니다. 충돌이 발생할 경우(즉, 두 파일에 동일한 별칭이 정의된 경우), 사용자별 구성이 더 높은 우선순위를 가집니다.

이 두 파일 중에서 다음과 같이 별칭을 정의할 수 있습니다:

aliases:
  "l": "tsh login --auth=okta"

이제부터 tsh l 은 tsh login --auth=okta 로 해석됩니다.

일반 tsh 명령의 기본값을 변경하는 것도 가능합니다:

aliases:
  "status": "tsh status --format=json"

tsh 외부 프로그램을 호출하는 것도 가능합니다:

aliases:
  "connect": "bash -c 'tsh login $0 && tsh ssh $1'"

위 예시는 변수 $0 및 $1 의 사용을 보여줍니다. 이들은 별칭에 제공된 인수를 나타냅니다. 위 정의에 따르면, tsh connect foo bar 는 bash -c 'tsh login foo && tsh ssh bar' 로 해석됩니다.

별칭은 필요한 만큼 많은 인수를 사용할 수 있습니다. 만약 인수가 너무 적게 제공되면 tsh 는 오류를 보고합니다. 반대로, 추가 인수를 제공하는 것은 오류가 아닙니다. tsh 는 추가 인수를 별칭 정의의 끝에 추가합니다.

다음 구성으로:

aliases:
  "example": "bash -c 'echo first=$0 $0-$1 $3'"

tsh example 0 1 unused-2 3 unused-4 는 bash -c 'echo first=0 0-1 3 unused-2 unused-4' 로 확장됩니다.

별칭 정의에 $TSH 변수를 추가할 수도 있습니다. 별칭을 호출할 때, tsh 는 이를 현재 tsh 실행 파일의 절대 경로로 확장합니다. 이는 여러 버전의 tsh 가 설치되어 있는 경우나 현재 사용 중인 버전이 PATH 에 없는 경우 유용할 수 있습니다.

aliases:
  "status": "$TSH status --format=json"

별칭 치환은 명령줄 플래그가 완전히 파싱되기 전에 발생합니다. 이는 --debug 플래그의 영향을 받지 않음을 의미합니다. 별칭 문제를 해결하기 위해 TELEPORT_DEBUG=1 환경 변수를 설정하십시오. 이렇게 하면 tsh 로그가 콘솔에 인쇄됩니다:

TELEPORT_DEBUG=1 tsh status
DEBU [TSH]       Self re-exec command: tsh [status --format=json]. tsh/aliases.go:203...

기록된 세션 검토

tsh 를 사용하여 Teleport로 보호되는 리소스에서 사용자가 완료한 세션을 검토할 수 있습니다. 이 섹션에서는 tsh 로 Teleport 세션 녹음을 나열하고 재생하는 방법을 설명합니다.

세션 녹음을 Teleport 웹 UI에서도 재생할 수 있습니다. 그렇게 하려면, 사이드바 상단의 액세스 관리 탭으로 이동하고 왼쪽 사이드바에서 세션 녹음 탭을 확인하세요.

녹음 나열하기

다음 명령을 실행하여 기록된 세션을 검토합니다:

tsh recordings ls
ID                                   Type Participants Hostname Timestamp------------------------------------ ---- ------------ -------- -------------------b0a04442-70dc-4be8-9308-7b7901d2d600 ssh  jeff         dev       Nov 26 16:36:16 UTCc0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTCd0a04442-70dc-4be8-9308-7b7901d2d600 ssh  navin        test      Nov 26 16:36:16 UTC

녹음 재생하기

세션 녹음을 재생하려면 tsh play 명령을 실행하고 tsh recordings ls 를 통해 반환된 세션의 ID를 사용합니다:

t sh play c0a02222-70dc-4be8-9308-7b7901d2d600

세션 녹음이 포함된 TAR 파일의 경로로 t sh play를 실행할 수도 있습니다:

t sh play ./my-recording.tar

세션 녹음 파일을 TAR로 복구하려면 세션 녹음 백엔드에 대한 액세스 권한이 있어야 합니다. 이는 자체 호스트 Teleport 클러스터 또는 외부 감사 저장소가 필요합니다.

tsh play 명령은 기록된 세션이 상호 작용하는 리소스 유형에 따라 여러 형식으로 녹음을 인쇄할 수 있습니다. 형식을 선택하려면 tsh play 의 --format 플래그를 사용합니다:

재생 속도는 --speed 플래그로 사용자 정의할 수 있으며, 해당 값은 0.5x , 1x , 2x , 4x , 또는 8x 중 하나여야 합니다.

tsh play --speed=8x UUID

재생 속도를 높이는 또 다른 방법은 --skip-idle-time 플래그로 녹음의 유휴 시간을 건너뛰는 것입니다. 이 기능을 활성화하면, t sh는 녹음의 활성 부분 동안 구성된 재생 속도를 준수하지만, 더 긴 비활성 기간은 건너뜁니다.

t sh 구성 파일

구성 파일을 사용하여 t sh의 동작을 제어할 수 있습니다. 구성 파일의 범위는 위치에 따라 달라집니다:

• /etc/tsh.yaml 은 글로벌 공유 구성 설정의 기본 위치입니다. TELEPORT_GLOBAL_TSH_CONFIG 환경 변수를 사용하여 위치를 덮어쓸 수 있습니다.
• $TELEPORT_HOME/config/config.yaml 은 사용자별 구성 설정의 기본 위치입니다. TELEPORT_HOME의 기본 위치는 ~/.tsh 입니다.

t sh는 두 구성 파일 위치의 설정을 병합하며, 사용자 구성 설정이 우선합니다.

추가 프록시 헤더

tsh 구성 파일을 사용하면 proxy 필드와 일치하는 주소에 대해 Teleport 프록시 서버에 대한 요청에 포함할 HTTP 헤더를 지정할 수 있습니다.

add_headers:
  - proxy: "*.example.com" # 일치하는 프록시는 헤더가 포함됩니다
    headers: # 헤더는 HTTP 헤더에 포함할 쌍입니다
      foo: bar # HTTP 요청에 포함할 Key/Value

예를 들어, HTTP 헤더를 추가하는 것은 인증 토큰을 설정해야 하는 중간 HTTP 프록시가 존재하는 경우 유용할 수 있습니다:

add_headers:
  - proxy: "*.infra.corp.xyz"
    headers:
      "Authorization": "Bearer tokentokentoken"

별칭

별칭을 사용하면 사용자 정의 명령을 정의하거나 기존 명령에 대한 기본 플래그 값을 변경할 수 있습니다. 다음 구문을 사용합니다:

aliases:
  "<alias>": "<command>"

<alias>는 최상위 하위 명령만 가능하다는 점에 유의하세요. 즉, tsh mycommand 별칭을 정의할 수 있지만 tsh my command 는 정의할 수 없습니다.

새 명령 tsh l :

aliases:
  "l": "tsh login --auth=okta"

tsh status 를 JSON을 기본 형식으로 사용하도록 설정:

aliases:
  "status": "tsh status --format=json"

별칭은 임의의 수의 인수를 사용할 수 있습니다. 인수 변수 $N 이 참조되는 경우, tsh 는 별칭 호출에 대해 최소한 N+1 개의 인수가 제공되었는지 확인합니다. 주어진 인수 중 별칭 정의에 참조되지 않은 모든 인수는 끝에 추가됩니다.

bash 를 사용하여 사용자 정의 명령을 정의합니다. $0 및 $1 변수가 명령 인수로 대체됩니다.

aliases:
  "connect": "bash -c 'tsh login $0 && tsh ssh $1'"

첫 번째 인수가 --auth 옵션을 지정하는 사용자 정의 로그인 명령을 정의합니다.

aliases:
  "ap": "tsh login --auth=$0 --proxy=teleport.example.com"

구성에 따라:

aliases:
  "example": "bash -c 'echo first=$0 $0-$1 $3'"

tsh example 0 1 unused-2 3 unused-4 는 bash -c 'echo first=0 0-1 3 unused-2 unused-4'로 확장됩니다.

별칭 정의는 $TSH 변수를 참조할 수도 있습니다. 별칭에서 $TSH 변수를 사용하면 tsh 는 변수를 현재 tsh 실행 파일의 절대 경로로 확장합니다. 이 동작은 여러 버전의 tsh 가 설치되어 있거나 현재 사용 중인 버전이 PATH 에 없을 때 유용할 수 있습니다:

aliases:
  "status": "$TSH status --format=json"

별칭 문제를 해결하려면 TELEPORT_DEBUG=1 환경 변수를 설정하십시오. 이렇게 하면 자세한 로그가 표준 오류로 출력됩니다:

TELEPORT_DEBUG=1 tsh status
DEBU [TSH]       Self re-exec command: tsh [status --format=json]. tsh/aliases.go:203...

프록시 템플릿

프록시 템플릿을 사용하면 tsh 가 tsh ssh 또는 tsh proxy ssh 명령에서 목적지 호스트의 주소를 기반으로 연결할 Teleport 프록시 서비스의 주소를 동적으로 결정합니다:

proxy_templates:
  # 호스트 서버 주소 `%h:%p` 에 대해 일치하는 정규 표현식.
  # 아래의 "치환 규칙"은 이 정규 표현식의 캡처 그룹을 참조할 수 있습니다 (`$1` , `$2` 등).
  - template: '^(\w+)\.(\w+):([0-9]+)$' # <nodename>.<clustername>:<port>

    # 프록시 점프를 위한 선택적 웹 프록시 주소(`--jumphost` , `-J` ).
    #
    # 프록시 점프는 리전별로 분산된 신뢰 클러스터에서 대기 시간을 줄이기 위해 사용됩니다.
    # 루트 프록시가 아닌 리프 프록시를 통해 리프 노드에 연결할 수 있습니다.
    proxy: "$2.eu.example.com:443"

    # 연결할 선택적 클러스터 이름(`--cluster` ).
    #
    # 클러스터는 루트 프록시에서 리프 노드에 로그인하지 않고도 연결하는 데 사용할 수 있습니다.
    # 이는 리프 클러스터가 자체 공용 프록시를 갖고 있지 않은 경우와 같은 경우에 유용할 수 있습니다.
    cluster: "$2"

    # 연결할 선택적 호스트 서버 주소(`%h:%p` ).
    #
    # 포트는 명시적으로 `--port` 와 함께 제공되지 않으면 기본적으로 3022로 설정됩니다.
    # 제공된 경우, 호스트 조회를 우선하여 쿼리 또는 검색을 통해 대체됩니다.
    host: "$1:$3"

    # 대상을 해결하기 위한 선택적 조건 표현식.
    #
    # `tsh ls --query` 와 유사하게 조건 표현식으로 쿼리합니다.
    # 검색보다 우선 순위가 있지만 호스트가 제공된 경우 무시됩니다.
    query: "labels.env == $1"

    # 대상을 해결하기 위한 선택적 퍼지 검색 용어.
    #
    # `tsh ls --search` 와 유사하게 쉼표로 구분된 키워드 목록으로 검색합니다.
    # 호스트와 검색이 제공되지 않으면 적용됩니다.
    search: "$1"

  # 여러 템플릿을 제공할 수 있습니다. 이들은 순서대로 평가되며 첫 번째 일치하는 항목이 적용됩니다.
  - template: ...

위 구성에서 query 는 조건 표현식을 허용합니다. 이는 검색보다 우선하며 호스트가 제공된 경우 무시됩니다. 조건 언어 문서에서 조건 표현식 예제를 참조하십시오.

tsh -J {{proxy}} ssh 와 tsh -J {{proxy}} proxy ssh 는 호스트 서버 주소 %h:%p 를 구성된 템플릿과 일치시키려고 시도합니다. 각 치환 규칙 세트에 대해 해당 CLI 값이 설정됩니다.

노드에 연결하기 위해 리프 인증서가 필요한 경우, tsh 는 루트 클러스터에서 리프 인증서를 자동으로 검색합니다:

tsh ssh -J {{proxy}} node1.leaf1
becomes
tsh ssh -J leaf1.eu.example.com:443 --cluster leaf1 node1

템플릿과 일치하지 않는 경우 오류가 반환됩니다.

tsh ssh -J {{proxy}} node1.none.example.com
ERROR: proxy jump contains {{proxy}} variable but did not match any of the templates in tsh config

프록시 변수를 명시적으로 제공하지 않는 경우 -J {{proxy}}, tsh 는 여전히 템플릿과 일치시켜 보지만 일치하지 않을 경우 실패하지 않습니다. 또한, tsh 는 클라이언트에 의해 명시적으로 설정된 proxy 값을 교체하지 않습니다:

tsh ssh -J leaf2.us.example.com:443 node1.leaf2
becomes
tsh ssh -J leaf2.us.example.com:443 --cluster leaf2 node1

프록시 템플릿은 ~/.ssh/config 에서 ProxyCommand 를 설정하여 tsh proxy ssh 를 사용할 수 있도록 OpenSSH와 함께 사용할 수 있습니다.

Host *.example.com
    Port 3022
    ProxyCommand tsh proxy ssh -J {{proxy}} %r@%h:%p

그 결과, tsh ssh 와 ssh 를 서로 바꿔 사용할 수 있습니다.

tsh ssh node1.leaf1
is equivalent to
ssh node1.leaf1

tsh 제거하기

tsh 및 관련 사용자 데이터를 제거하려면 Teleport 제거하기를 참조하세요.

추가 읽기

모든 tsh 명령어와 그 옵션에 대한 tsh CLI 참조를 읽어보세요.