Update tsh docs (gravitational#3450)

* Add helpful instructions and modify commands on quickstart.md * Add missing filesystem for tsh Co-authored-by: Ben Arent <[email protected]>
lobando · Mar 18, 2020 · 7f0f3c4 · 7f0f3c4
1 parent f0cc654
commit 7f0f3c4
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 16 deletions.
diff --git 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 `<cluster>` argument to [`tsh
 login`](cli-docs.md#tsh-login).
 

diff --git a/docs/4.2/quickstart.md b/docs/4.2/quickstart.md
@@ -98,24 +98,31 @@ 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: `<your OS user>@<your hostname>`
 
 !!! 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
-    <your-username> ` 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
+    <your-username> ` 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
 # A new Teleport user will be assigned a
 # 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 [<flags>] <[user@]host> [<command>...]
+# 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