SSO, 세션 녹화 요약, 적시(just-in-time) 접근 요청과 같은 Teleport Enterprise 기능을 무료로 체험해 볼 수 있습니다. 결제 정보는 필요하지 않습니다.

이 가이드는 Teleport 클라이언트 도구인 tsh를 사용하여 클러스터의 인프라 리소스에 연결하는 방법을 보여줍니다.

이 가이드에서 배울 내용은 다음과 같습니다:

• Teleport에 연결된 리소스를 나열하고, 접근하고, 상호작용하는 방법
• 동료와 대화형 셸 세션을 공유하거나 다른 사람의 세션에 참여하는 방법
• 녹화된 대화형 세션을 나열하고 재생하는 방법

이 문서 외에도, 터미널에 tsh를 입력하여 CLI 참조를 확인하거나 문서에서 tsh CLI 참조를 살펴볼 수 있습니다.

tsh를 사용하여 접근 요청을 관리할 수도 있습니다. 자세한 내용은 접근 요청을 참고하세요.

tsh 설치하기#

아래 안내에 따라 tsh 바이너리를 설치하세요.

1. 설치할 tsh 버전을 결정합니다. Teleport 클러스터에서 사용 중인 버전과 동일한 메이저 버전을 설치하는 것을 권장합니다. 다음 중 하나를 사용하세요:

   • Web UI에서 우측 상단의 사용자 이름을 선택한 다음 Help & Support를 클릭합니다. Cluster Information 아래에서 Teleport 클러스터의 버전을 확인할 수 있습니다.

   • curl과 jq를 사용합니다. teleport.example.com을 여러분의 프록시 서비스 주소(예: Teleport Enterprise Cloud의 경우 mytenant.teleport.sh)로 바꾸세요:

     $ curl https://teleport.example.com/webapi/find | jq '.server_version'
     "(=teleport.version=)"
     

2. tsh가 포함된 패키지를 설치합니다:

Mac

`tsh`가 포함된, 서명된 Teleport용 macOS .pkg 설치 프로그램을 다운로드합니다.
Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다:

```code
$ curl -O https://cdn.teleport.dev/teleport-(=teleport.version=).pkg
```

  Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
  Teleport 패키지는 Teleport에서 관리하지 않으며, 신뢰성이나 보안을
  보장할 수 없습니다.

Windows - Powershell

```code
$ curl.exe -O https://cdn.teleport.dev/teleport-v(=teleport.version=)-windows-amd64-bin.zip
# Unzip the archive and move tsh.exe to your %PATH%
# NOTE: Do not place tsh.exe in the System32 directory, as this can cause issues when using WinSCP.
# Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
```

Linux

Linux 설치판의 모든 Teleport 바이너리에는 `tsh`가 포함되어 있습니다. RPM/DEB
패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
[설치 페이지](../installation/installation.mdx)를 참조하십시오.

```code
$ curl -O https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
$ tar -xzf teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
$ cd teleport
$ sudo ./install
# Teleport binaries have been copied to /usr/local/bin
```

기본 사용법#

tsh를 사용하면 Teleport에서 접근할 수 있는 인프라 리소스를 확인하고 해당 리소스에 연결할 수 있습니다. 이 섹션에서는 tsh를 사용하여 인프라 리소스에 접근하는 주요 워크플로를 보여줍니다.

Teleport에 로그인하기#

Teleport 클러스터에 로그인합니다. 이때 teleport.example.com에는 클러스터의 Teleport 프록시 서비스 도메인 이름을, myuser에는 여러분의 Teleport 사용자 이름을 지정하세요:

$ tsh login --proxy=teleport.example.com --user=myuser

이 명령은 사용자의 인증서를 가져와서 ~/.tsh/<code>teleport.example.com</code>에 저장합니다.

접근할 수 있는 리소스 나열하기#

Teleport 클러스터에서는 모든 Teleport 에이전트가 주기적으로 클러스터의 Auth 서비스에 핑을 보내 자신의 상태를 업데이트합니다. 이를 통해 Teleport 사용자는 어떤 Teleport 보호 리소스가 온라인 상태인지 확인할 수 있습니다.

다음 명령은 접근 권한이 있는 클러스터의 모든 연결된 서버를 나열합니다:

$ tsh ls

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

tsh 명령을 사용하여 다른 종류의 리소스도 나열할 수 있습니다. 자세한 내용은 다음 리소스 유형에 대한 tsh 참조 항목을 확인하세요:

Windows 데스크톱은 Teleport Connect와 Teleport Web UI에서 나열할 수 있습니다.

tsh <resource> ls 명령은 리소스의 라벨을 기준으로 필터를 적용할 수 있습니다. 예를 들어, os 라벨이 osx로 설정된 서버만 표시하려면 다음 명령을 실행하세요:

$ tsh ls os=osx

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

리소스에 연결하기#

연결할 리소스를 결정했다면, 다음 단계는 tsh로 해당 리소스에 접근하는 것입니다. tsh는 Teleport 클러스터에 대한 인증과 로컬 클라이언트 간의 트래픽 라우팅을 처리합니다.

Windows 데스크톱은 Teleport Web UI 또는 Teleport Connect를 통해서만 연결할 수 있습니다.

tsh로 리소스에 연결하는 방법을 확인하려면 리소스 유형을 선택하세요:

$ tsh ssh root@mynode

$ tsh proxy app myapp

$ tsh apps login grafana

$ curl \
  --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \
  --key /Users/alice/.tsh/keys/teleport.example.com/alice \
  https://grafana.teleport.example.com:3080

$ tsh db connect --db-user=my-database-user mydb

$ tsh db logout

$ tsh proxy db --tunnel mydb

$ tsh kube login mycluster

$ tsh kubectl exec my-pod -- date

로그인하기#

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

# Full form:
$ tsh login --proxy=proxy_host:<https_proxy_port>

# Using default ports:
$ tsh login --proxy=work.example.com

# Using custom HTTPS port:
$ tsh login --proxy=work.example.com:5000

# Full form:
$ tsh login --proxy=proxy_host:<https_proxy_port>

$ tsh login --proxy=mytenant.teleport.sh

CLI 문서 - tsh login

login 명령은 사용자의 인증서를 가져와 ~/.tsh 디렉터리와, 실행 중인 ssh agent가 있다면 그곳에도 함께 저장합니다.

이를 통해 하루의 시작 시점 등에 단 한 번만 인증하면 됩니다. 이후의 tsh ssh 명령은 임시 인증서가 만료될 때까지 자격 증명을 다시 요구하지 않고 실행됩니다. 기본적으로 Teleport는 사용자 인증서의 TTL(time to live)을 12시간으로 발급합니다.

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

# Log in using the local Teleport 'admin' user:
$ tsh --proxy=proxy.example.com --auth=local --user=admin login

# Log in using GitHub as an SSO provider, assuming the GitHub connector is called "github"
$ tsh --proxy=proxy.example.com --auth=github login

# Don't open the system default browser when logging in
$ tsh login --proxy=work.example.com --browser=none

# Log in using the local Teleport 'admin' user:
$ tsh --proxy=mytenant.teleport.sh --auth=local --user=admin login

# Log in using GitHub as an SSO provider, assuming the GitHub connector is called "github"
$ tsh --proxy=mytenant.teleport.sh --auth=github login

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

# Don't open the system default browser when logging in
$ tsh login --proxy=mytenant.teleport.sh --browser=none

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

CLI 문서 - tsh login

MFA 모드#

명령에 MFA가 필요한 경우, tsh는 --mfa-mode 플래그를 사용하여 MFA 검사를 완료하는 방식을 결정합니다. 생략하면 기본값은 auto이며, 성공할 때까지 다음 방식을 순서대로 시도합니다:

1. WebAuthn(사용 가능한 경우 TOTP 포함)
2. SSO
3. 브라우저 MFA
4. TOTP

브라우저 MFA를 사용하면, 등록된 MFA 장치가 브라우저 기반(예: 패스키 또는 Touch ID)뿐인 사용자도 브라우저 창을 열어 CLI에서 MFA 검사를 완료할 수 있습니다.

SSH 인증서 확인하기#

~/.tsh에 있는 SSH 인증서를 확인하려면, 사용자는 다음 명령을 실행하면 됩니다:

$ tsh status

# > Profile URL:  https://proxy.example.com:3080
#   Logged in as: johndoe
#  Cluster:      proxy.example.com
#   Roles:        access, auditor, editor
#   Logins:       root, admin, guest
#   Kubernetes:   enabled
#  Valid until:  2017-04-25 15:02:30 -0700 PDT [valid for 1h0m0s]
#  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty

$ tsh status

# > Profile URL:  https://mytenant.teleport.sh:443
#   Logged in as: johndoe
#  Cluster:      mytenant.teleport.sh
#   Roles:        access, editor, auditor
#   Logins:       root, admin, guest
#   Kubernetes:   enabled
#  Valid until:  2017-04-25 15:02:30 -0700 PDT [valid for 1h0m0s]
#  Extensions:   permit-agent-forwarding, permit-port-forwarding, permit-pty

CLI 문서 - tsh status

아이덴티티 파일#

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

# Authenticate the user against proxy.example.com and save the user
# certificate to joe.pem
$ tsh login --proxy=proxy.example.com --out=joe

# Use joe.pem to log in to the server 'db'
$ tsh ssh --proxy=proxy.example.com -i joe joe@db

# Authenticate the user against mytenant.teleport.sh and save the user
# certificate to joe.pem
$ tsh login --proxy=mytenant.teleport.sh --out=joe

# Use joe.pem to log in to the server '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

# total 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

# total 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 & Workload Identity를 사용하는 것입니다. 이렇게 하면 자동화가 단기 자격 증명의 보안 속성을 그대로 활용할 수 있습니다.

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

이 예시에서는 jenkins 사용자에 대해 TTL이 1시간인 인증서를 생성하여 jenkins.pem 파일에 저장합니다. 이 파일은 이후 tsh의 -i(identity) 플래그와 함께 사용할 수 있습니다.

# Log in to your cluster with tsh so you can use tctl from your local machine.
# You can also run tctl on your Auth Service host without running "tsh login"
# first.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem

# Log in to your Teleport Cloud cluster so you can use tctl locally.
$ tsh login --proxy=myinstance.teleport.sh --user=email@example.com
$ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem

CLI 문서 - tctl auth sign

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

tctl auth sign은 tsh login --out의 관리자용 버전이며, 제한 없는 인증서 TTL 값을 허용합니다.

SSH 서버에 연결하기#

이 섹션에서는 tsh를 사용하여 Teleport 클러스터에 등록된 SSH 서버에 연결하는 방법에 대한 자세한 정보를 제공합니다.

사용자 아이덴티티#

Teleport의 사용자 아이덴티티는 클러스터 범위 내에 존재합니다. 클러스터의 멤버 노드에는 여러 OS 사용자가 있을 수 있습니다. Teleport 관리자는 모든 Teleport 사용자 계정에 허용된 로그인 계정을 할당합니다.

원격 노드에 로그인할 때는 Teleport 로그인과 OS 로그인을 모두 지정해야 합니다. Teleport 아이덴티티는 --user 플래그로 전달해야 하며, OS 로그인은 기존 ssh 명령과 호환되는 문법인 login@host 형식으로 전달합니다.

다음 명령은 teleport.example.com 클러스터에 대해 인증하고, 서버 node에 root로 로그인합니다:

$ tsh ssh --proxy=teleport.example.com --user=joe root@node

프록시 포트#

기본적으로 Teleport 프록시 서비스는 포트 3080에서 리스닝합니다.

Teleport 프록시 서비스 인스턴스가 기본이 아닌 포트에서 리스닝하도록 구성되어 있다면, 아래와 같이 --proxy 플래그로 포트를 지정해야 합니다:

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

이 tsh 명령은 프록시 서비스의 포트 5000을 사용합니다.

포트 포워딩#

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 에이전트 지원#

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

$ ssh-add -L

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

SSH 에이전트 통합을 비활성화하려면, tsh에 --add-keys-to-agent=no를 전달하세요. 이를 영구적으로 적용하려면 셸 프로필에서 TELEPORT_ADD_KEYS_TO_AGENT 환경 변수를 no로 설정할 수도 있습니다.

tsh 플래그와 환경 변수의 전체 참조는 tsh 참조를 확인하세요.

SSH 점프 호스트#

Teleport에서 ProxyJump를 구현하면서, 이 기능을 tsh로 확장했습니다.

$ tsh ssh -J proxy.example.com telenode

$ tsh ssh -J mytenant.teleport.sh telenode

알려진 제약 사항:

• 점프 호스트는 하나만 지원됩니다(-J는 체이닝을 지원하지만 Teleport는 이를 활용하지 않습니다). 두 개의 점프 호스트, 즉 -J proxy-1.example.com,proxy-2.example.com을 사용하면 tsh는 오류를 반환하며 동작하지 않습니다.
• tsh ssh -J user@proxy를 사용하면 tsh 프로필에 정의된 SSH 프록시를 재정의하며, 기존의 Teleport 프록시 서브시스템 대신 포트 포워딩이 사용됩니다.

서버 이름 확인하기#

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

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

os:linux 라벨을 가진 노드 하나와 os:osx 라벨을 가진 노드 하나가 있는 경우, 다음 명령으로 OSX 노드에 로그인할 수 있습니다:

$ tsh ssh os=osx

이는 os:osx 라벨을 가진 원격 노드가 하나뿐인 경우에만 동작하지만, 라벨을 선택자로 사용하여 여러 노드에서 SSH로 명령을 실행할 수도 있습니다. 다음 명령은 Linux를 실행하는 모든 머신의 시스템 패키지를 업데이트합니다:

$ tsh ssh os=ubuntu apt-get update -y

단기 세션#

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

$ tsh --ttl=1 login

1분 후에는 자동으로 로그아웃되지만, 즉시 로그아웃하고 싶다면 언제든지 다음 명령을 실행하면 됩니다:

$ tsh logout

방화벽 뒤의 SSH 클러스터에 연결하기#

Teleport는 개방된 리스닝 TCP 포트가 전혀 없는 방화벽 뒤에 있는 서버들의 클러스터를 만들 수 있도록 지원합니다. 이는 방화벽 뒤 환경에서 여러분이 접근할 수 있는 Teleport 프록시 서비스로 리버스 SSH 터널을 생성하는 방식으로 동작합니다.

방화벽 뒤에 있는 클러스터 간에 신뢰 관계를 설정하는 방법에 대해 자세히 알아보려면 트러스티드 클러스터 구성하기를 참고하세요.

work라는 Teleport 프록시 서버가 여러 트러스티드 클러스터로 구성되어 있다고 가정하면, tsh clusters 명령을 사용하여 서버에 있는 모든 트러스티드 클러스터 목록을 확인할 수 있습니다:

$ tsh --proxy=work clusters

# Cluster Name     Status
# ------------     ------
# staging          online
# production       offline

CLI 문서 - tsh clusters

이제 어떤 tsh 명령에서든 --cluster 플래그를 사용할 수 있습니다. 예를 들어, production 클러스터에 속한 SSH 노드를 나열하려면 다음과 같이 실행하면 됩니다:

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

# Node Name     Node ID       Address            Labels
# ---------     -------       -------            ------
# 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

이는 production 클러스터의 노드가 개방된 포트 없이 방화벽 뒤에 있는 경우에도 가능합니다. 이는 production 클러스터가 work라는 프록시 서비스로 리버스 SSH 터널을 구축하기 때문에 가능하며, 이 터널을 통해 인바운드 SSH 연결이 이루어집니다.

X11 포워딩#

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

$ tsh ssh -X node01

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

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

$ tsh status
> Profile URL:        https://proxy.example.com:3080
  Logged in as:       dev
  ...
  Extensions:         permit-X11-forwarding

SSH 서버와 상호작용하기#

이 섹션에서는 tsh로 SSH 서버와 상호작용하는 방법에 대한 세부 정보를 확인할 수 있습니다.

대화형 셸#

원격 노드에서 대화형 셸을 실행하거나 명령을 실행하려면 tsh ssh를 사용하세요.

tsh는 가능한 한 ssh와 유사한 경험을 제공하도록 만들어져 있어서, -p, -l, -L과 같이 자주 쓰이는 ssh 플래그를 지원합니다. 예를 들어, ~/.bashrc에 alias ssh="tsh ssh"와 같은 별칭이 정의되어 있다면, 익숙한 SSH 문법을 계속 사용할 수 있습니다:

# Have this alias configured, perhaps via ~/.bashrc
$ alias ssh="/usr/local/bin/tsh ssh"

# Login in to a cluster and retrieve your SSH certificate:
$ tsh --proxy=proxy.example.com login

# These commands execute `tsh ssh` under the hood:
$ ssh user@node
$ ssh -p 6122 user@node ls
$ ssh -o ForwardAgent=yes user@node
$ ssh -o AddKeysToAgent=yes user@node

# Have this alias configured, perhaps via ~/.bashrc
$ alias ssh="/usr/local/bin/tsh ssh"

# Login in to a cluster and retrieve your SSH certificate:
$ tsh --proxy=mytenant.teleport.sh login

# These commands execute `tsh ssh` under the hood:
$ ssh user@node
$ ssh -p 6122 user@node ls
$ ssh -o ForwardAgent=yes user@node
$ ssh -o AddKeysToAgent=yes user@node

파일 복사하기#

클러스터 노드로/노드에서 파일을 안전하게 복사하려면 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 프로토콜을 모두 지원합니다. tsh scp 대신 원한다면 OpenSSH의 scp 또는 sftp 명령을 사용해도 됩니다.

세션 공유하기#

원격 서버에서 문제를 해결하려 한다고 가정해 봅시다. 때로는 다른 팀원에게 도움을 요청하는 것이 합리적일 수 있습니다. 전통적으로는 어떤 호스트에 있는지 알려준 다음, SSH로 접속시켜 screen과 같은 터미널 멀티플렉서를 시작하고 세션에 참여하게 하는 방식으로 이를 수행했습니다.

Teleport는 이를 훨씬 더 편리하게 만들어 줍니다. luna라는 서버에 로그인하여 현재 세션 상태를 Teleport에 물어보겠습니다:

$ tsh ssh luna
# on host luna
$ teleport status

# User ID    : joe, logged in as joe from 10.0.10.1 43026 3022
# Session ID : 7645d523-60cb-436d-b732-99c5df14b7c4
Session URL: https://work:3080/web/sessions/7645d523-60cb-436d-b732-99c5df14b7c4

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

$ tsh join <session_ID>

tsh sessions ls 명령으로 활성 세션 목록을 확인할 수도 있습니다.

Git 명령 프록시하기#

디버그 로그#

명령에 --debug 플래그를 추가하거나 TELEPORT_DEBUG 환경 변수를 1로 설정하면 tsh가 표준 출력으로 디버그 로그를 출력합니다.

macOS의 통합 로깅 시스템#

macOS에서는 --debug 대신 --os-log 플래그를 사용하여 디버그 로그를 통합 로깅 시스템으로 보낼 수 있습니다. 이 동작은 TELEPORT_OS_LOG 환경 변수로도 제어할 수 있습니다.

별도의 셸 세션에서 로그를 스트리밍하려면:

$ log stream --predicate 'subsystem CONTAINS "tsh"' --style syslog --level debug

지금까지 캡처된 로그를 파일로 덤프하려면:

$ log show --predicate 'subsystem CONTAINS "tsh"' --style syslog --info --debug > tsh.log

로그는 Console 앱에서도 확인할 수 있습니다. 정보 및 디버그 로그는 기본적으로 표시되지 않으므로, Action 메뉴에서 "Include Info Messages"와 "Include Debug Messages"를 선택해야 합니다.

녹화된 세션 검토하기#

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

녹화를 보려면 Teleport Web UI에서 Audit을 선택한 다음 메뉴에서 Session Recordings를 클릭하세요.

녹화 목록 확인하기#

녹화된 세션을 검토하려면 다음 명령을 실행하세요:

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

녹화 재생하기#

세션 녹화를 재생하려면, tsh recordings ls가 반환한 세션 ID로 tsh play 명령을 실행하세요:

$ tsh play c0a02222-70dc-4be8-9308-7b7901d2d600

세션 녹화가 담긴 TAR 파일의 경로로 tsh play를 실행할 수도 있습니다:

$ tsh 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 플래그로 녹화 내의 유휴 시간을 건너뛰는 것입니다. 이를 활성화하면, tsh는 녹화의 활성 구간 동안에는 설정된 재생 속도를 그대로 사용하지만, 더 긴 비활성 구간은 건너뜁니다.

tsh 구성 파일#

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

• /etc/tsh.yaml은 전역 공유 구성 설정을 위한 기본 위치입니다. TELEPORT_GLOBAL_TSH_CONFIG 환경 변수로 위치를 재정의할 수 있습니다.
• $TELEPORT_HOME/config/config.yaml은 사용자별 구성 설정을 위한 기본 위치입니다. TELEPORT_HOME의 기본 위치는 ~/.tsh입니다.

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

추가 프록시 헤더#

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

add_headers:
  - proxy: "*.example.com" # matching proxies will have headers included
    headers: # headers are pairs to include in the http headers
      foo: bar # Key/Value to be included in the http request

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

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

별칭(Aliases)#

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

별칭을 사용하면 tsh 구성 파일에서 다음과 같은 문법으로 커스텀 명령을 정의하거나 기존 명령의 기본 플래그 값을 변경할 수 있습니다:

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 옵션을 지정하는 커스텀 login 명령을 정의합니다.

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:

# Regular expression that the host server address `%h:%p` is matched against.
# The "replace rules" below can reference capturing groups from this regular
# expression (`$1`, `$2`, etc.).
- template: '^(\w+)\.(\w+):([0-9]+)$' # <nodename>.<clustername>:<port>

  # Optional web proxy address to use for proxy jump (`--jumphost`, `-J`).
  #
  # Proxy Jump can be used to reduce latency in regionally distributed trusted
  # clusters by connecting to a leaf node through the leaf proxy instead of the
  # root proxy.
  proxy: "$2.eu.example.com:443"

  # Optional cluster name to connect to (`--cluster`).
  #
  # Cluster can be used to connect to leaf nodes from the root proxy without
  # first logging in to the leaf cluster. This may be useful in cases where
  # proxy jump is not applicable, such as when the leaf clusters do not have
  # their own public proxies.
  cluster: "$2"

  # Optional host server address to connect to (`%h:%p`).
  #
  # Port defaults to 3022 if not explicitly provided with `--port`.
  # If provided, it will take precedence over host resolution via
  # query or search.
  host: "$1:$3"

  # Optional predicate expression to resolve the target host with.
  #
  # Query by predicate expression similar to tsh ls --query.
  # Has priority over search but will be ignored if a host is provided.
  query: "labels.env == $1"

  # Optional fuzzy search terms to resolve the target host with.
  #
  # Search by a list of comma separated keywords similar to tsh ls --search.
  # Only applied if host and search are not provided.
  search: "$1"

# Multiple templates can be provided. They are evaluated in order and the first
# match takes effect.
- template: ...

위 구성에서, query는 프레디킷 표현식을 받습니다. 이는 search보다 우선순위가 높지만, 호스트가 제공된 경우에는 무시됩니다. 프레디킷 표현식 예시는 프레디킷 언어 문서를 참고하세요.

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는 여전히 템플릿과의 매칭을 시도하지만, 일치하는 항목이 없어도 실패하지는 않습니다. 또한, 클라이언트가 proxy 값을 명시적으로 설정한 경우 tsh는 이를 치환하지 않습니다:

$ 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 참조를 읽어보세요.