From 7f0f3c4c7f38a52ddfb78ce7cf85577f3d99f5fa Mon Sep 17 00:00:00 2001 From: Lisa Kim Date: Wed, 18 Mar 2020 10:43:40 -0700 Subject: [PATCH] Update tsh docs (#3450) * Add helpful instructions and modify commands on quickstart.md * Add missing filesystem for tsh Co-authored-by: Ben Arent --- docs/4.2/admin-guide.md | 10 ++++++++-- docs/4.2/quickstart.md | 42 +++++++++++++++++++++++++++-------------- 2 files changed, 36 insertions(+), 16 deletions(-) diff --git a/docs/4.2/admin-guide.md b/docs/4.2/admin-guide.md index 4580d36b40d61..1cb78efb46478 100644 --- a/docs/4.2/admin-guide.md +++ b/docs/4.2/admin-guide.md @@ -51,7 +51,7 @@ $ shasum -a 256 teleport-v{{ teleport.version }}-darwin-amd64-bin.tar.gz **Checking Checksum on Linux** ``` bash -$ sha256sum teleport-v4.0.8-darwin-amd64-bin.tar.gz +$ sha256sum teleport-v{{ teleport.version }}-darwin-amd64-bin.tar.gz {{ teleport.sha }} teleport-v{{ teleport.version }}-darwin-amd64-bin.tar.gz ``` @@ -162,6 +162,7 @@ numbers. ### Filesystem Layout +#### A Teleport node By default, a Teleport node has the following files present. The location of all of them is configurable. @@ -172,6 +173,11 @@ of them is configurable. | `/usr/local/bin/tctl` | Teleport admin tool. It is only needed for auth servers.| | `/var/lib/teleport` | Teleport data directory. Nodes keep their keys and certificates there. Auth servers store the audit log and the cluster keys there, but the audit log storage can be further configured via `auth_service` section in the config file.| +#### tsh +| Full path | Purpose | +|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `~/.tsh` | Temporary store for Proxy Address, Username, SSH certificates and user environment variables when reading `permit_user_env: trues`. | + ## Configuration You should use a [configuration file](#configuration-file) to configure the @@ -2069,7 +2075,7 @@ You can take advantage of the [Trusted Clusters](#trusted-clusters) feature of Teleport to federate trust across multiple Kubernetes clusters. When multiple trusted clusters are present behind a Teleport proxy, the -`kubeconfig` generated by [ `tsh login`](cli-docs.md#tsh-login) will contain the +`kubeconfig` generated by [`tsh login`](cli-docs.md#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [`tsh login`](cli-docs.md#tsh-login). diff --git a/docs/4.2/quickstart.md b/docs/4.2/quickstart.md index ce8e27ed05c47..5fe6807f132be 100644 --- a/docs/4.2/quickstart.md +++ b/docs/4.2/quickstart.md @@ -98,16 +98,23 @@ Congratulations - you are now running Teleport! ## Step 3: Create a User Signup Token We've got Teleport running but there are no users recognized by Teleport Auth -yet. Let's create one for your OS user. In this example the OS user is -`teleport` and the hostname of the node is `grav-00` . +yet. Let's create one for your OS user. + +For the following examples: `teleport@grav-00`, the **OS user** is +`teleport`, and the **hostname** of the node is `grav-00`. + +Replace `OS user` and `hostname` as it fits your OS: `@` !!! info "OS User Mappings" - The OS user `teleport` must exist! On Linux, if it - does not already exist, create it with `adduser teleport`. If you do not have + If you intend to use `teleport` as OS user (as shown in our examples), OS user `teleport` must exist! + And you must explicitly state user as `teleport` in some subsequent commands. (We will remind you). + + On Linux, if it does not already exist, create it with `adduser teleport`. If you do not have the permission to create new users on the VM, run `tctl users add teleport - ` to explicitly map ` teleport` to an existing OS user. If you - do not map to a real OS user you will get authentication errors later on in + ` to explicitly map ` teleport` to an existing OS user. + + If you do not map to a real OS user you will get authentication errors later on in this tutorial! ``` bash @@ -115,7 +122,7 @@ yet. Let's create one for your OS user. In this example the OS user is # mapping to an OS user of the same name # This is the same as running `tctl users add teleport teleport` [teleport@grav-00 ~]$ tctl users add teleport -Signup token has been created and is valid for 1 hours. Share this URL with the user: +User teleport has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s: https://grav-00:3080/web/newuser/3a8e9fb6a5093a47b547c0f32e3a98d4 NOTE: Make sure grav-00:3080 points at a Teleport proxy which users can access. @@ -180,6 +187,8 @@ accessible IP. ``` bash # here grav-00 is a resolvable hostname on the same network # --proxy can be an IP, hostname, or URL +# --user (not shown) by default, is implicitly set to your last login, or primary OS username +# if your primary OS user isn't teleport, you need to explicitly set by including: --user=teleport [teleport@grav-00 ~]$ tsh --proxy=grav-00 --insecure login WARNING: You are using insecure connection to SSH proxy https://grav-00:3080 Enter password for Teleport user teleport: @@ -201,18 +210,23 @@ WARNING: You are using insecure connection to SSH proxy https://grav-00:3080 ## Step 6: Start A Recorded Session -At this point you have authenticated with Teleport Auth and can now start a -recorded SSH session. You logged in as the `teleport` user in the last step so -the `--user` is defaulted to `teleport`. +At this point you have authenticated with Teleport Auth and can now start a recorded SSH session. + +Since you logged in the last step with `tsh --proxy=grav-00 login`, the `--user` is defaulted to `teleport` and `--proxy` is defaulted to `grav-00`. In other words they are implicitly set. ``` bash -$ tsh ssh --proxy=grav-00 grav-00 +# usage: tsh ssh [] <[user@]host> [...] +# by default, the user in <[user@]host>, is implicitly your primary OS user +# if you didn't map `teleport` to your primary OS user OR +# if your primary OS user isn't teleport, you need to explicitly include your user too: teleport@grav-00 +$ tsh ssh grav-00 $ echo 'howdy' howdy # run whatever you want here, this is a regular SSH session. ``` -_Note: The `tsh` client always requires the `--proxy` flag_ +_Note: The `tsh` client always requires the `--proxy` flag because `tsh` needs to know which cluster you are connecting to. +But if you execute `tsh --proxy=xxx login`, the current proxy (and user) will be saved in your `~/.tsh` profile and won't be needed for other tsh commands._ Your command prompt may not look different, but you are now in a new SSH session which has been authenticated by Teleport! @@ -248,7 +262,7 @@ machine (or any machine) you can also join a session on the CLI. ``` bash # This is the recorded session you started in Step 6 -$ tsh ssh --proxy=grav-00 grav-00 +$ tsh ssh grav-00 $ echo 'howdy' howdy # you might have run more stuff here... @@ -259,7 +273,7 @@ Session ID : cd908432-950a-4493-a561-9c272b0e0ea6 Session URL : https://grav-00:3080/web/cluster/grav-00/node/a3f67090-99cc-45cf-8f70-478d176b970e/teleport/cd908432-950a-4493-a561-9c272b0e0ea6 ``` -Copy the Session ID and open a new SSH session. +Copy the Session ID obtained by running `teleport status` inside the session and open a new SSH session. ``` bash %~$ tsh join -d --proxy grav-00 --insecure