teleport/docs/user-manual.md

User Manual

Introduction

This User Manual covers usage of the Teleport client tool tsh. In this document you will learn how to:

• Securely login into interactive shell on remote cluster nodes.
• Execute commands on cluster nodes.
• Securely copy files to and from cluster nodes.
• Explore a cluster and execute commands on those nodes in a cluster that match your criteria.
• Share interactive shell sessions with colleagues or join someone else's session.
• Replay recorded interactive sessions.
• Use Teleport with OpenSSH client: ssh or with other tools that use SSH under the hood like Chef and Ansible.

In addition to this document, you can always type tsh into your terminal for the CLI reference.

> tsh
usage: tsh [<flags>] <command> [<command-args> ...]

Gravitational Teleport SSH tool

Commands:
  help       shows help for a given command
  ssh        connect and log into a remote host(s) for executing commands
  scp        secure copy file(s) to a remote SSH host(s)
  share      invite a colleague to share your current terminal
  join       join a colleague who invited you into his SSH session
  ls         list remote SSH hosts available via SSH proxy (bastion)
  login      logs in the SSH proxy and enables usage of OpenSSH client
  logout     logs off the SSH proxy
  agent      starts SSH session agent for compatibility with OpenSSH client
  configure  dump a sample profile file into stdout

Notes:

  - Most of the flags can be set in a profile file ~/.tshconfig
  - Run `tsh help <command>` to get help for <command> like `tsh help ssh`

Difference vs OpenSSH

There are many differences between Teleport's tsh and OpenSSH's ssh but the most obvious two are:

• tsh always requires --proxy flag because tsh needs to know which cluster you are connecting to.

• tsh needs two usernames: one for the cluster and another for the node you are trying to login into. See "Teleport Identity" section below. For convenience, tsh assumes $USER for both logins by default.

While it may appear less convenient than ssh, we hope that the default behavior and techniques like bash aliases will help to minimize the amount of typing.

Your Teleport Identity

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 "user mappings" to every Teleport user account.

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

These examples assume your localhost username is 'joe':

# Authenticate against cluster 'work' as 'joe' and then login into 'node'
# as root:
> tsh ssh --proxy=work.example.com --user=joe root@node

# Authenticate against cluster 'work' as 'joe' and then login into 'node'
# as joe (by default tsh uses $USER for both):
> tsh ssh --proxy=work.example.com node

tsh allows to login into the cluster without connecting to any master nodes:

> tsh login --proxy=work.example.com

This allows you to supply your password and the 2nd factor authentication at the beginning of the day. Subsequent tsh ssh commands will run without asking for your credentials until the temporary certificate expires (by default 12 hours).

Exploring the Cluster

In a Teleport cluster all nodes periodically ping the cluster's auth server and update their statuses. This allows Teleport users to see which nodes are online:

# Connect to cluster 'work' as $USER and list all nodes in 
# a cluster:
> tsh --proxy=work ls

# Output:
Node Name     Node ID                Address            Labels
---------     -------                -------            ------
turing        11111111-dddd-4132     10.1.0.5:3022     os:linux
turing        22222222-cccc-8274     10.1.0.6:3022     os:linux
graviton      33333333-aaaa-1284     10.1.0.7:3022     os:osx

You can filter out nodes based on their labels. Let's only list OSX machines:

> tsh --proxy=work ls os=osx

Node Name     Node ID                Address            Labels
---------     -------                -------            ------
graviton      33333333-aaaa-1284     10.1.0.7:3022     os:osx

Interactive Shell

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

> tsh ssh --help

usage: t ssh [<flags>] <[user@]host> [<command>...]
Run shell or execute a command on a remote SSH node.

Flags:
      --user      SSH proxy user [ekontsevoy]
      --proxy     SSH proxy host or IP address
      --ttl       Minutes to live for a SSH session 
      --insecure  Do not verify server's certificate and host name. Use only in test environments
  -d, --debug     Verbose logging to stdout
  -p, --port      SSH port on a remote host
  -l, --login     Remote host login

Args:
  <[user@]host>  Remote hostname and the login to use
  [<command>]    Command to execute on a remote host

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

> ssh root@host
> ssh -p 6122 root@host ls

Resolving Node Names

tsh supports multiple methods to resolve remote node names.

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

In the example above, we have two nodes with os:linux label and one node with os:osx. Lets login into the OSX node:

> tsh --proxy=work ssh os=osx

This only works if there is only one remote node with 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 --proxy=work ssh os=linux apt-get update -y

Temporary Logins

Suppose you are borrowing someone else's computer to login into a cluster. You probably don't want to stay authenticated on this computer for 12 hours (Teleport default). This is where --ttl flag can help.

This command logs you into the cluster with a very short-lived (1 minute) temporary certificate:

tsh --proxy=work --ttl=1 ssh

You will be logged out after one minute.

Copying Files

To securely copy files to and from cluster nodes use tsh scp command. It is designed to mimic traditional scp as much as possible:

> tsh scp --help

usage: tsh scp [<flags>] <from, to>...
Secure file copy

Flags:
      --user       SSH proxy user [ekontsevoy]
      --proxy      SSH proxy host or IP address
      --ttl        Minutes to live for a SSH session
      --insecure   Do not verify server's certificate and host name. Use only in test environments
  -P, --debug      Verbose logging to stdout
  -d, --debug      Verbose logging to stdout
  -r, --recursive  Recursive copy of subdirectories

Args:
  <from, to>       Source and the destination

Examples:

> tsh --proxy=work 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 sytanx:

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

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 node you're on, having them SSH in, start a terminal multiplexer like screen and join a session there.

Teleport makes this a bit more convenient. Let's login into "luna" and ask Teleport for your current session status:

> tsh --proxy=work ssh luna
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 in the "work" cluster. You can share the URL for access through a web browser. Or you can share the session ID and she can join you through her terminal by typing:

> tsh --proxy=work join 7645d523-60cb-436d-b732-99c5df14b7c4

Troubleshooting

If you encounter strange behaviour, you may want to try to solve it by enabling the verbose logging by specifying -d flag when launching tsh.

Also you may want to reset it to a clean state by deleting temporary keys and other data from ~/.tsh

Getting Help

Please open an issue on Github. Alternatively, you can reach through the contact form on our website.

For commercial support, custom features or to try our multi-cluster edition of Teleport, please reach out to us: sales@gravitational.com.