Documentation improvements

- Faster docs build time due to parallel builds
- Added "agentless" entry to Q&A
- Documented -o flag support for `tsh ssh`. Closes #2330

Makefile

@@ -18,7 +18,6 @@ BINDIR ?= /usr/local/bin
 DATADIR ?= /usr/local/share/teleport
 ADDFLAGS ?=
 PWD ?= `pwd`
-GOCACHEDIR ?= `go env GOCACHE`
 GOPKGDIR ?= `go env GOPATH`/pkg/`go env GOHOSTOS`_`go env GOARCH`/github.com/gravitational/teleport*
 TELEPORT_DEBUG ?= no
 GITTAG=v$(VERSION)
@@ -100,7 +99,7 @@ endif
 clean:
 	@echo "---> Cleaning up OSS build artifacts."
 	rm -rf $(BUILDDIR)
-	rm -rf $(GOCACHEDIR)
+	go clean -cache
 	rm -rf $(GOPKGDIR)
 	rm -rf teleport
 	rm -rf *.gz

build.assets/Makefile

@@ -99,7 +99,6 @@ docs: docsbox
 		-w $(DOCSDIR) \
 		-h $(DOCSHOST) $(DOCSBOX) \
 		./docs/build.sh
-	@echo "\nSUCCESS: Teleport docs ----> build/docs\n"
 
 #
 # allows to enter into bash shell of docs container

build.assets/docs.dockerfile

@@ -5,7 +5,8 @@ ARG GID
 ARG USER
 ARG WORKDIR
 
-RUN apt-get install -q -y ruby-sass
+RUN apt-get update -y
+RUN apt-get install -q -y ruby-sass parallel
 
 RUN groupadd $USER --gid=$GID -o && useradd $USER --uid=$UID --gid=$GID --create-home --shell=/bin/bash
 RUN echo "source /etc/profile" > /home/$USER/.bashrc

docs/3.1/faq.md

@@ -2,30 +2,39 @@
 
 ### Can I use Teleport in production today?
 
-Teleport has completed several security audits from nationally recognized
-technology security companies, so we are comfortable with the use of Teleport
-from a security perspective. We are actively
-supporting Teleport and addressing any issues that are submitted to
-the [github repo](https://github.com/gravitational/teleport).
+Teleport has been deployed on server clusters with thousands of nodes at
+Fortune 500 companies. It has been through several security audits from
+nationally recognized technology security companies, so we are comfortable with
+the stability of Teleport from a security perspective. 
 
-### Can I connect to nodes behind a firewall?
+### Can Teleport be deployed in agentless mode?
 
-Yes, Teleport supports reverse SSH tunnels out of the box. To configure behind-firewall clusters
-refer to [Trusted Clusters](admin-guide.md#trusted-clusters) section of the Admin Manual.
+Yes. Teleport can be deployed with a tiny footprint as an authentication
+gateway/proxy and you can keep your existing SSH servers on the nodes. But some
+innovating Teleport features, such as cluster introspection, will not be
+available unless the Teleport SSH daemon is present on all cluster nodes.
 
-### Does Web UI support copy and paste?
+### Can I use OpenSSH with a Teleport cluster?
+
+Yes, this question comes up often and is related to the previous one. Take a 
+look at [Using OpenSSH client](user-manual.md##using-teleport-with-openssh) 
+section in the User Manual and [Using OpenSSH servers](admin-guide.md) in the 
+Admin Manual.
 
-Yes. You can copy&paste using the mouse. For working with a keyboard, Teleport employs `tmux`-like
-"prefix" mode. To enter prefix mode, press `Ctrl+A`.
+### Can I connect to nodes behind a firewall?
 
-While in prefix mode, you can press `Ctrl+V` to paste, or enter text selection mode by pressing `[`.
-When in text selection mode, move around using `hjkl`, select text by toggling `space` and copy
-it via `Ctrl+C`.
+Yes, Teleport supports reverse SSH tunnels out of the box. To configure
+behind-firewall clusters refer to [Trusted Clusters](admin-guide.md#trusted-clusters) 
+section of the Admin Manual.
 
-### Can I use OpenSSH with a Teleport cluster?
+### Does Web UI support copy and paste?
+
+Yes. You can copy&paste using the mouse. For working with a keyboard, Teleport employs 
+`tmux`-like "prefix" mode. To enter prefix mode, press `Ctrl+A`.
 
-Yes. Take a look at [Using OpenSSH client](user-manual.md##using-teleport-with-openssh) section in the User Manual
-and [Using OpenSSH servers](admin-guide.md) in the Admin Manual.
+While in prefix mode, you can press `Ctrl+V` to paste, or enter text selection
+mode by pressing `[`. When in text selection mode, move around using `hjkl`, select 
+text by toggling `space` and copy it via `Ctrl+C`.
 
 ### What TCP ports does Teleport use?
 
@@ -42,7 +51,8 @@ Gravitational offers this feature for the [commercial versions of Teleport](ente
 The Teleport Enterprise offering gives users the following additional features:
 
 * Role-based access control, also known as [RBAC](enterprise#rbac).
-* Authentication via SAML and OpenID with providers like Okta, Active Directory, Auth0, etc. (aka, [SSO](http://localhost:6600/ssh_sso/)).
+* Authentication via SAML and OpenID with providers like Okta, Active
+  Directory, Auth0, etc. (aka, [SSO](http://localhost:6600/ssh_sso/)).
 * Premium support.
 
 We also offer implementation services, to help you integrate
@@ -52,14 +62,17 @@ You can read more in the [Teleport Enterprise section of the docs](enterprise.md
 
 ### Does Teleport send any data to Gravitational?
 
-The open source edition of Teleport does not send any information
-to Gravitational and can be used on servers without internet access. The commercial versions of Teleport may or may not be configured to send anonymized information to
-Gravitational, depending on the license purchased. This information contains the following:
+The open source edition of Teleport does not send any information to
+Gravitational and can be used on servers without internet access. The
+commercial versions of Teleport may or may not be configured to send anonymized
+information to Gravitational, depending on the license purchased. This
+information contains the following:
 
 * Anonymized user ID: SHA256 hash of a username with a randomly generated prefix.
 * Anonymized server ID: SHA256 hash of a server IP with a randomly generated prefix.
 
 This allows Teleport Pro to print a warning if users are exceeding the usage limits
 of their license. The reporting library code is [on Github](https://github.com/gravitational/reporting).
 
-Reach out to `sales@gravitational.com` if you have questions about commercial edition of Teleport.
+Reach out to `sales@gravitational.com` if you have questions about commercial
+edition of Teleport.

docs/3.1/intro.md

@@ -6,22 +6,28 @@ Gravitational Teleport is a gateway for managing access to clusters of Linux
 servers via SSH or the Kubernetes API. It is intended to be used instead of
 traditional OpenSSH for organizations that need to:
 
-* Secure their infrastructure and comply with security best-practices and regulatory requirements.
+* Secure their infrastructure and comply with security best-practices and
+  regulatory requirements.
 * Have complete visibility into activity happening across their infrastructure.
-* Reduce the operational overhead of privileged access management across both traditional and cloud-native infrastructure.
+* Reduce the operational overhead of privileged access management across both
+  traditional and cloud-native infrastructure.
 
 ![teleport diagram](/images/diagram-teleport.png)
 
-Teleport gives teams that manage infrastructure access:
+Teleport aims to be a cloud-native SSH solution, i.e. it makes it natural to think of
+environments, not servers. Below is the list of most popular Teleport features:
 
-* The ability to manage trust between teams, organizations and data centers.
+* Single SSH/Kubernetes access gateway for an entire organization.
 * Certificate based authentication instead of static keys.
-* SSH access into behind-firewall environments without any open ports.
+* The ability to manage trust between teams, organizations and data centers.
+* SSH/Kubernetes access into behind-firewall environments without any open ports.
 * Role-based access control (RBAC) for SSH.
 * A single tool ("pane of glass") to manage RBAC for both SSH and Kubernetes.
-* SSH audit log with session recording/replay.
+* Audit log with session recording/replay.
 * Kubernetes audit log, including the recording of interactive commands executed via `kubectl`.
 * The same workflows and ease of that they get with familiar `ssh` / `kubectl` commands.
+* Ability to run in "agentless" mode, i.e. most of Teleport features are
+  available on clusters with pre-existing SSH daemons, usually `sshd`.
 
 Teleport is available through the free, open source edition ("Teleport Community Edition")
 or a commercial edition ("Teleport Enterprise Edition").

docs/3.1/user-manual.md

@@ -14,10 +14,21 @@ In addition to this document, you can always simply type `tsh` into your termina
 the CLI reference.
 
 ```bash
-$ tsh
-usage: tsh [<flags>] <command> [<command-args> ...]
+Usage: tsh [<flags>] <command> [<args> ...]
 
-Gravitational Teleport SSH tool
+TSH: Teleport SSH client
+
+Flags:
+  -l, --login               Remote host login
+      --proxy               SSH proxy address
+      --user                SSH proxy user [ekontsevoy]
+      --ttl                 Minutes to live for a SSH session
+  -i, --identity            Identity file
+      --cert-format         SSH certificate format
+      --insecure            Do not verify servers certificate and host name.
+      --auth                Specify the type of authentication connector to use.
+      --skip-version-check  Skip version checking between server and client.
+  -d, --debug               Verbose logging to stdout
 
 Commands:
   help         Show help.
@@ -28,12 +39,41 @@ Commands:
   scp          Secure file copy
   ls           List remote SSH nodes
   clusters     List available Teleport clusters
-  login        Log in to the cluster and store the session certificate to avoid login prompts
+  login        Log in to a cluster and retrieve the session certificate
   logout       Delete a cluster certificate
+  status       Display the list of proxy servers and retrieved certificates
+```
+
+## Introduction
+
+For the impatient, here's an example of how a user would typically use `tsh`:
+
+```bash
+# Login into a Teleport cluster. This command retrieves user's certificates
+# and saves them into ~/.tsh/teleport.example.com
+$ tsh login --proxy=teleport.example.com
+
+# SSH into a node, as usual:
+$ tsh ssh user@node
+
+# `tsh ssh` takes the same arguments as OpenSSH client:
+$ tsh ssh -o ForwardAgent=yes user@node
+$ tsh ssh -o AddKeysToAgent=yes user@node
 
-# Run `tsh help <command>` to get help for <command> like `tsh help ssh`
+# you can even create a convenient symlink:
+$ ln -s /path/to/tsh /path/to/ssh
+
+# ... and now your 'ssh' command is calling Teleport's `tsh ssh`
+$ ssh user@host
+
+# This command removes SSH certificates from a user's machine:
+$ tsh logout
 ```
 
+In other words, Teleport was designed to be fully compatible with existing
+SSH-based workflows and does not require users to learn anything new, other
+than to call `tsh login` in the beginning.
+
 ## User Identities
 
 A user identity in Teleport exists in the scope of a cluster. The member nodes
@@ -44,16 +84,10 @@ 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':
-
 ```bash
-# Authenticate against cluster 'work' as 'joe' and then login into 'node'
+# Authenticate against the "work" cluster as joe and then login into the 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
 ```
 
 ## Logging In
@@ -218,7 +252,7 @@ command:
 ```bash
 $ tsh ssh --help
 
-usage: t ssh [<flags>] <[user@]host> [<command>...]
+Usage: tsh ssh [<flags>] <[user@]host> [<command>...]
 Run shell or execute a command on a remote SSH node.
 
 Flags:
@@ -231,6 +265,9 @@ Flags:
   -l, --login     Remote host login
   -L, --forward   Forward localhost connections to remote server
       --local     Execute command on localhost after connecting to SSH node
+  -t, --tty       Allocate TTY
+      --cluster   Specify the cluster to connect
+  -o, --option    OpenSSH options in the format used in the configuration file
 
 Args:
   <[user@]host>  Remote hostname and the login to use
@@ -239,12 +276,21 @@ Args:
 
 `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 --proxy=work.example.com --user=myname"` then you can continue
+~/.bashrc: `alias ssh="tsh ssh"` then you can continue
 using familiar SSH syntax:
 
 ```bash
-$ ssh root@host
-$ ssh -p 6122 root@host ls
+# Have this alias configured, perhaps via ~/.bashrc
+$ alias ssh=/usr/local/bin/tsh
+
+# Login into a cluster and retreive 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
 ```
 
 ### Proxy Ports

docs/build.sh

@@ -11,22 +11,27 @@ rm -f latest.yaml
 # will be set to the latest version after the loop below
 doc_ver=""
 
-for conf_file in $(ls *.yaml | sort); do
-    doc_ver=${conf_file%.yaml}
-    echo "Building docs version --> $doc_ver"
-    mkdocs build --config-file $conf_file || exit $?
-done
+# find all *.yaml files and convert them to array, pick the latest
+cfiles=$(ls *.yaml | sort)
+cfiles_array=($cfiles)
+latest_cfile=$(echo ${cfiles_array[-1]}) # becomes "3.1.yaml"
+latest_ver=${latest_cfile%.yaml}         # becomes "3.1"
+
+# build all documentation versions at the same time (4-8x speedup)
+parallel --will-cite mkdocs build --config-file ::: $cfiles
 
 # drop the 'latest.yml' symlink to the latest version so `mkdocs serve` will
 # automatically serve the latest
-echo "Latest version --> $conf_file"
-ln -fs $conf_file latest.yaml
+echo "Latest version: $latest_ver"
+ln -fs $latest_cfile latest.yaml
 
 # copy the index file which serves /docs requests and redirects
 # visitors to the latest verion of QuickStart
 cp index.html ../build/docs/index.html
 
-# create a symlink to the latest
+# create a symlink called 'latest' to the latest directory, like "3.1"
 cd ../build/docs
 rm -f latest
-ln -s $doc_ver latest
+ln -s $latest_ver latest
+
+echo "The docs have been built and saved in 'build/docs'"