From 51ab559872263accecf5ef07e2ef9127480e05f5 Mon Sep 17 00:00:00 2001 From: Ev Kontsevoy Date: Tue, 12 Feb 2019 16:27:11 -0800 Subject: [PATCH] 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 | 3 +- build.assets/Makefile | 1 - build.assets/docs.dockerfile | 3 +- docs/3.1/faq.md | 57 ++++++++++++++++---------- docs/3.1/intro.md | 18 ++++++--- docs/3.1/user-manual.md | 78 ++++++++++++++++++++++++++++-------- docs/build.sh | 23 ++++++----- 7 files changed, 126 insertions(+), 57 deletions(-) diff --git a/Makefile b/Makefile index 7e54a54b71ae5..6060d7f2e8065 100644 --- a/Makefile +++ b/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 diff --git a/build.assets/Makefile b/build.assets/Makefile index cc8517667d4f1..64285411020ca 100644 --- a/build.assets/Makefile +++ b/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 diff --git a/build.assets/docs.dockerfile b/build.assets/docs.dockerfile index e5cf77eef65a5..1cc6eb2db903a 100644 --- a/build.assets/docs.dockerfile +++ b/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 diff --git a/docs/3.1/faq.md b/docs/3.1/faq.md index 27e4e62bcd5bc..80099a2aa5f4e 100644 --- a/docs/3.1/faq.md +++ b/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,9 +62,11 @@ 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. @@ -62,4 +74,5 @@ Gravitational, depending on the license purchased. This information contains the 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. diff --git a/docs/3.1/intro.md b/docs/3.1/intro.md index 06be269bf75f9..f6015b4f70df5 100644 --- a/docs/3.1/intro.md +++ b/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"). diff --git a/docs/3.1/user-manual.md b/docs/3.1/user-manual.md index 3594da70b758f..34c83f14662c8 100644 --- a/docs/3.1/user-manual.md +++ b/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 [] [ ...] +Usage: tsh [] [ ...] -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 ` to get help for 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 [] <[user@]host> [...] +Usage: tsh ssh [] <[user@]host> [...] 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 diff --git a/docs/build.sh b/docs/build.sh index 494cafbf2fc15..ff89c2271aea0 100755 --- a/docs/build.sh +++ b/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'"