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

다음 내용을 학습합니다:

• Teleport에 연결된 리소스를 나열, 접근, 상호작용하기.
• 동료와 인터랙티브 셸 세션을 공유하거나 다른 사람의 세션에 참여하기.
• 녹화된 인터랙티브 세션을 나열하고 재생하기.

이 문서 외에도, 터미널에 tsh를 입력하면 CLI 레퍼런스를 확인할 수 있으며, 문서에서 tsh CLI 레퍼런스를 탐색할 수 있습니다.

tsh를 사용하여 액세스 요청을 관리할 수도 있습니다. 지침은 액세스 요청을 참조하세요.

tsh 설치#

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

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

   • Web UI에서 오른쪽 상단의 사용자 이름을 선택한 후 도움말 및 지원을 클릭하세요. 클러스터 정보 아래에서 Teleport 클러스터 버전을 확인할 수 있습니다.

   • curl과 jq를 사용하세요. 을 프록시 서비스 주소로 교체하세요(예: Teleport Enterprise Cloud의 경우 mytenant.teleport.sh):

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

2. tsh가 포함된 패키지를 설치하세요:

기본 사용법#

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

Teleport에 로그인#

Teleport 클러스터에 로그인합니다. 을 클러스터의 Teleport 프록시 서비스 도메인 이름으로 지정하고, 를 Teleport 사용자 이름으로 지정하세요:

$ tsh login --proxy= --user=

This command retrieves the user's certificates and saves them into ~/.tsh/.

List resources that you can access#

In a Teleport cluster, all Teleport Agents periodically ping the cluster's Auth Service and update their status. This allows Teleport users to see which Teleport-protected resources are online.

This command lists all connected servers in the cluster that you have permission to access:

$ tsh ls

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

You can use tsh commands to list other kinds of resources. For more information, see the tsh reference entries for the following resource types:

Windows desktops are available to list in Teleport Connect and the Teleport Web UI.

tsh <resource> ls commands can apply a filter based on the resource's labels. For example, to only show servers with the os label set to osx, you can run the following command:

$ tsh ls os=osx

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

Connect to a resource#

Once you have determined a resource to connect to, the next step is to access the resource with tsh, which handles authentication to your Teleport cluster and routing traffic to and from local clients.

You can only connect to a Windows desktop using the Teleport Web UI or Teleport Connect.

Select a resource type for instructions on connecting to the resource with 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

Logging in#

To retrieve a user's certificate, execute:

# 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 Docs - tsh login

The login command retrieves a user's certificate and stores it in ~/.tsh directory as well as in the ssh agent if there is one running.

This allows you to authenticate just once, maybe at the beginning of the day. Subsequent tsh ssh commands will run without asking for credentials until the temporary certificate expires. By default, Teleport issues user certificates with a time to live (TTL) of 12 hours.

A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called admin while regular users should authenticate via GitHub. In this case, you have to pass --auth flag to tsh login to specify which identity storage to use:

# 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

When using an external identity provider to log in, tsh will need to open a web browser to complete the authentication flow. By default, tsh will use your system's default browser. If you wish to suppress this behavior, you can use the --browser=none flag:

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

In this situation, a link will be printed on the screen. You can copy and paste this link into a browser of your choice to continue the login flow.

CLI Docs - tsh login

MFA 모드#

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

1. WebAuthn (TOTP가 사용 가능한 경우 함께)
2. SSO
3. Browser MFA
4. TOTP

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

SSH 인증서 검사#

To inspect the SSH certificates in ~/.tsh, a user may execute the following command:

$ 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 Docs - tsh status

Identity files#

tsh login can also save the user certificate into a file:

# 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

By default, the --out flag will create an identity file suitable for tsh -i. If compatibility with OpenSSH is needed, --format=openssh must be specified. In this case, the identity will be saved into two files, joe and 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 certificates for automation#

Regular users of Teleport must request an auto-expiring SSH certificate, usually every day. This doesn't work for non-interactive scripts, like cron jobs or a CI/CD pipeline.

The most secure way to generate certificates for automation purposes is to use 머신 및 워크로드 아이덴티티. This ensures that your automation is taking advantage of the security properties of short-lived credentials.

If 머신 및 워크로드 아이덴티티 does not support your preferred CI/CD platform, you can create a local user for use in automation and request a long-lived certificate for that user.

In this example, we're creating a certificate with a TTL of one hour for the jenkins user and storing it in a jenkins.pem file, which can be later used with -i (identity) flag for tsh.

# 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 Docs - tctl auth sign

Now jenkins.pem can be copied to the Jenkins server and passed to the -i (identity file) flag of tsh.

tctl auth sign is an admin's equivalent of tsh login --out and allows for unrestricted certificate TTL values.

Connecting to SSH servers#

This section provides detailed information about using tsh to connect to SSH servers registered with your Teleport cluster.

User identities#

A user identity in Teleport exists in the scope of a cluster. The member nodes of a cluster may have multiple OS users on them. A Teleport administrator assigns allowed logins to every Teleport user account.

When logging into a remote node, you will have to specify both the Teleport login and the OS login. A Teleport identity will have to be passed via the --user flag while the OS login will be passed as login@host using syntax compatible with the traditional ssh command.

The following command authenticates against the cluster and logs into the server node as root:

$ tsh ssh --proxy= --user=joe root@node

Proxy ports#

By default, the Teleport Proxy Service listens on port 3080.

If a Teleport Proxy Service instance is configured to listen on non-default ports, they must be specified via --proxy flag as shown:

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

This tsh command will use port 5000 of the Proxy Service.

Port forwarding#

tsh ssh supports the OpenSSH -L flag which forwards incoming connections from localhost to the specified remote host:port. The syntax of -L flag is as follows, where "bind_ip" defaults to 127.0.0.1:

$ -L [bind_ip]:listen_port:remote_host:remote_port

Example:

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

This will connect to remote server node via the Proxy Service, then open a listening socket on localhost:5000. Finally, it will forward all incoming connections to web.remote:80 via this SSH tunnel.

It is often convenient to establish port forwarding, execute a local command which uses the connection, and then disconnect. You can do this with the --local flag.

Example:

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

This command:

• Connects to node.
• Binds the local port 5000 to port 80 on google.com.
• Executes curl command locally, which results in curl hitting google.com:80 via node.

SSH agent support#

If there is an ssh agent running, tsh login will store the user certificate in the agent. This can be verified via:

$ ssh-add -L

The SSH agent can be used to feed the certificate to other SSH clients, for example to OpenSSH (ssh).

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

tsh 플래그 및 환경 변수의 전체 레퍼런스는 tsh 레퍼런스를 참조하세요.

SSH jump host#

While implementing ProxyJump for Teleport, we have extended the feature to tsh.

$ tsh ssh -J proxy.example.com telenode

$ tsh ssh -J mytenant.teleport.sh telenode

Known limitations:

• Only one jump host is supported (-J supports chaining that Teleport does not utilize) and tsh will return with error in the case of two jump hosts, i.e. -J proxy-1.example.com,proxy-2.example.com will not work.
• When tsh ssh -J user@proxy is used, it overrides the SSH proxy defined in the tsh profile, and port forwarding is used instead of the existing Teleport proxy subsystem.

Resolving server names#

tsh supports multiple methods to resolve remote Node names.

• Traditional: by IP address or via DNS.
• Nodename setting: the teleport daemon supports the nodename flag, which allows Teleport administrators to assign alternative Node names.
• Labels: you can address a Node by name=value pair.

두 개의 노드가 있고 하나는 os:linux 레이블, 다른 하나는 os:osx 레이블을 가진 경우, OSX 노드에 다음과 같이 로그인할 수 있습니다:

$ tsh ssh os=osx

This only works if there is only one remote node with the os:osx label, but you can still execute commands via SSH on multiple Nodes using labels as a selector. This command will update all system packages on machines that run Linux:

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

Short-lived sessions#

The default TTL of a Teleport user certificate is 12 hours. This can be modified at login with the --ttl flag. This command logs you into the cluster with a very short-lived (1 minute) temporary certificate:

$ tsh --ttl=1 login

You will be logged out after one minute, but if you want to log out immediately, you can always run:

$ tsh logout

Connecting to SSH clusters behind firewalls#

Teleport supports creating clusters of servers located behind firewalls without any open listening TCP ports. This works by creating reverse SSH tunnels from behind-firewall environments into a Teleport Proxy Service you have access to.

방화벽 뒤 클러스터 간 신뢰 관계 설정에 대해 자세히 알아보려면 신뢰할 수 있는 클러스터 구성을 참조하세요.

Assuming the Teleport Proxy Server called work is configured with a few trusted clusters, you can use the tsh clusters command to see a list of all the trusted clusters on the server:

$ tsh --proxy=work clusters

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

CLI Docs - tsh clusters

Now you can use the --cluster flag with any tsh command. For example, to list SSH nodes that are members of the production cluster, simply run:

$ 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

Similarly, if you want to SSH into db-1 inside the production cluster:

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

This is possible even if Nodes in the production cluster are located behind a firewall without open ports. This works because the production cluster establishes a reverse SSH tunnel back into the Proxy Service called work, and this tunnel is used to establish inbound SSH connections.

X11 forwarding#

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

$ tsh ssh -X node01

X11 forwarding provides the server with secure access to your local X Server so that it can communicate directly with your local display and I/O devices.

In order to use X11 forwarding, you'll need to enable it on the Teleport Node. You'll also need to ensure that your user has the permit_x11_forwarding role option:

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

Interacting with SSH servers#

In this section, you will find details on interacting with SSH servers with tsh.

Interactive shell#

To launch an interactive shell on a remote Node or to execute a command, use tsh ssh.

tsh tries to mimic the ssh experience as much as possible, so it supports the most popular ssh flags like -p, -l or -L. For example, if you have the following alias defined in your ~/.bashrc: alias ssh="tsh ssh" then you can continue using familiar SSH syntax:

# 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

Copying files#

To securely copy files to and from cluster Nodes, use the tsh scp command. It is designed to mimic OpenSSH's scp command as much as possible:

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

Again, you may want to create a bash alias like alias scp="tsh --proxy=work scp" and use the familiar syntax:

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

Teleport supports both the SCP and SFTP protocols. OpenSSH scp or sftp commands can both be used in place of tsh scp if desired.

Sharing sessions#

Suppose you are trying to troubleshoot a problem on a remote server. Sometimes it makes sense to ask another team member for help. Traditionally, this could be done by letting them know which host you're on, having them SSH in, start a terminal multiplexer like screen, and join a session there.

Teleport makes this more convenient. Let's log in to a server named luna and ask Teleport for our current session status:

$ 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

Now you can invite another user account to the work cluster. You can share the URL for access through a web browser, or you can share the session ID, and the other user can join you through their terminal by typing:

$ tsh join <session_ID>

You can also list active sessions with the tsh sessions ls command.

Proxying Git commands#

Debug logs#

Adding the --debug flag to a command or setting the TELEPORT_DEBUG env var to 1 makes tsh print debug logs to standard output.

Unified logging system on macOS#

On macOS, the --os-log flag can be used instead of --debug to send debug logs to the unified logging system. This behavior can also be controlled through the TELEPORT_OS_LOG env var.

To stream logs in a separate shell session:

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

To dump logs captured so far to a file:

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

The logs can also be inspected in the Console app. Info and debug logs are not shown by default, so make sure to select "Include Info Messages" and "Include Debug Messages" from the Action menu.

Examining recorded sessions#

You can use tsh to examine sessions that users have completed in resources protected by Teleport. This section explains how to list and play Teleport session recordings with tsh.

To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.

Listing recordings#

Run the following command to review recorded sessions:

$ 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

Playing recordings#

To play a session recording, run the tsh play command with the ID of a session as returned by tsh recordings ls:

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

You can also run tsh play with the path to a TAR file that contains a session recording:

$ tsh play ./my-recording.tar

To retrieve a TAR file containing a session recording, you must have access to the session recording backend. This requires either a self-hosted Teleport cluster or external audit storage.

The tsh play command can print recordings in several formats, depending on the kind of resource the recorded session interacts with. To choose a format, use the --format flag of tsh play:

The playback speed can be customized with the --speed flag, which must be one of 0.5x, 1x, 2x, 4x, or 8x.

tsh play --speed=8x UUID

Another way to speed up playback is to skip idle time in the recording with the --skip-idle-time flag. When enabled, tsh will respect the configured playback speed during active sections of the recording, but it will skip over larger periods of inactivity.

tsh configuration files#

You can use a configuration file to control the behavior of tsh. The scope of the configuration file depends on its location:

• /etc/tsh.yaml is the default location for global, shared configuration settings. You can override the location with the TELEPORT_GLOBAL_TSH_CONFIG environment variable.
• $TELEPORT_HOME/config/config.yaml is the default location for user-specific configuration settings. The default location for TELEPORT_HOME is ~/.tsh.

tsh merges the settings from both configuration file locations, with the user configuration settings taking precedence.

Extra proxy headers#

The tsh configuration file enables you to specify HTTP headers to be included in requests to Teleport Proxy Servers with addresses matching the proxy field.

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

For example, adding HTTP headers can be useful if an intermediate HTTP proxy is in place that requires setting an authentication token:

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

Aliases#

You can configure tsh to define aliases, custom commands and command-specific flag defaults. Using aliases, you can run frequently used tsh commands more easily.

Aliases allow you to define custom commands or change the default flag values for existing commands using the following syntax in tsh configuration files:

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

The <alias> can only be a top-level subcommand. In other words, you can define a tsh mycommand alias but not tsh my command.

New command tsh l:

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

Make tsh status use JSON as a default format:

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

The alias can use an arbitrary number of arguments. If an argument variable $N is referenced, tsh will check that at least N+1 arguments were given to the alias invocation. All arguments that were given but not referenced in the alias definition will be appended at the end.

Define a custom command using bash. The $0 and $1 variables will be substituted with command arguments.

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

Define a custom login command where first argument specifies --auth option.

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

Given the configuration:

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

tsh example 0 1 unused-2 3 unused-4 will expand to bash -c 'echo first=0 0-1 3 unused-2 unused-4'.

An alias definition can also reference the $TSH variable. If you use the $TSH variable in an alias, tsh expands the variable to the absolute path of the current tsh executable. This behavior can be useful if there are multiple tsh versions installed, or the version you're currently using is not in the PATH:

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

To troubleshoot aliases, set the TELEPORT_DEBUG=1 environment variable. This will cause detailed logs to be printed to standard error:

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

Proxy templates#

With proxy templates, tsh dynamically determines the address of the Teleport Proxy Service to connect to based on the address of the destination host in your tsh ssh or tsh proxy ssh command:

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: ...

In the configuration above, query accepts an predicate expression. This has priority over search but will be ignored if a host is provided. See the predicate language documentation for predicate expression examples.

tsh -J {{proxy}} ssh and tsh -J {{proxy}} proxy ssh will attempt to match the host server address %h:%p with the configured templates. For each replace rule set, the corresponding cli value will be set.

If leaf certificates are required to connect to the node, tsh automatically retrieves leaf certificates from the root cluster:

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

If there is no template matched, an error is returned.

$ 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

If you don't explicitly provide the proxy variable -J {{proxy}}, tsh still attempts to match a template, but won't fail if there isn't a match. Additionally, tsh won't replace the proxy value if it's explicitly set by the client:

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

Proxy Templates can also be used with OpenSSH by setting the ProxyCommand in ~/.ssh/config to use tsh proxy ssh.

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

As a result, you can use tsh ssh and ssh interchangeably.

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

Uninstalling tsh#

To remove tsh and associated user data see Uninstalling Teleport.

Further reading#

Read the tsh CLI Reference for all tsh commands and their options.