From 191e645011ced7165973ec7399a83c97aaf670bb Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 10 Aug 2023 09:56:47 -0400 Subject: [PATCH] Split up the CLI reference (#30129) Fixes #29957 Improves the page load performance of our CLI reference documentation by splitting up the long CLI reference page. This also has other benefits, including: - **SEO**: Users don't need to search for the Teleport CLI reference (and don't need to know that this page exists), but can search for a specific tool they want reference docs for. - **In-page search:** Users searching within a specific page will get results for the tool they are researching, not all of Teleport's CLI tools. --- CHANGELOG.md | 2 +- docs/config.json | 20 +- .../access-requests/resource-requests.mdx | 2 +- .../access-requests/role-requests.mdx | 2 +- .../compliance-frameworks/soc2.mdx | 2 +- .../pages/access-controls/guides/webauthn.mdx | 2 +- .../access-controls/login-rules/guide.mdx | 4 +- docs/pages/access-controls/sso/github-sso.mdx | 2 +- docs/pages/access-controls/sso/oidc.mdx | 2 +- docs/pages/access-controls/sso/okta.mdx | 2 +- .../join-token.mdx | 2 +- docs/pages/architecture/nodes.mdx | 2 +- docs/pages/architecture/session-recording.mdx | 2 +- docs/pages/connect-your-client/putty.mdx | 2 +- .../connect-your-client/teleport-connect.mdx | 2 +- docs/pages/connect-your-client/tsh.mdx | 24 +- docs/pages/core-concepts.mdx | 2 +- docs/pages/database-access/reference/aws.mdx | 4 +- docs/pages/faq.mdx | 2 +- .../manage-access/federation.mdx | 8 +- docs/pages/machine-id/reference.mdx | 2 +- docs/pages/management/admin/daemon.mdx | 7 +- docs/pages/management/admin/users.mdx | 4 +- docs/pages/management/dynamic-resources.mdx | 2 +- docs/pages/reference/audit.mdx | 6 +- docs/pages/reference/authentication.mdx | 7 +- docs/pages/reference/cli.mdx | 3153 +---------------- docs/pages/reference/cli/tbot.mdx | 239 ++ docs/pages/reference/cli/tctl.mdx | 1396 ++++++++ docs/pages/reference/cli/teleport.mdx | 114 + docs/pages/reference/cli/tsh.mdx | 1401 ++++++++ docs/pages/reference/config.mdx | 2 +- docs/pages/reference/predicate-language.mdx | 2 +- docs/pages/reference/resources.mdx | 2 +- docs/pages/server-access/getting-started.mdx | 2 +- 35 files changed, 3227 insertions(+), 3202 deletions(-) create mode 100644 docs/pages/reference/cli/tbot.mdx create mode 100644 docs/pages/reference/cli/tctl.mdx create mode 100644 docs/pages/reference/cli/teleport.mdx create mode 100644 docs/pages/reference/cli/tsh.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index 12a18a3ce7a..e14cda8f770 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3033,7 +3033,7 @@ This is a minor Teleport release with a focus on new features and bug fixes. * Alpha: Enhanced Session Recording lets you know what's really happening during a Teleport Session. [#2948](https://github.com/gravitational/teleport/issues/2948) * Alpha: Workflows API lets admins escalate RBAC roles in response to user requests. [Read the docs](./docs/pages/access-controls/access-requests.mdx). [#3006](https://github.com/gravitational/teleport/issues/3006) * Beta: Teleport provides HA Support using Firestore and Google Cloud Storage using Google Cloud Platform. [Read the docs](./docs/pages/deploy-a-cluster/deployments/gcp.mdx). [#2821](https://github.com/gravitational/teleport/pull/2821) -* Remote tctl execution is now possible. [Read the docs](./docs/pages/reference/cli.mdx#tctl). [#1525](https://github.com/gravitational/teleport/issues/1525) [#2991](https://github.com/gravitational/teleport/issues/2991) +* Remote tctl execution is now possible. [Read the docs](./docs/pages/reference/cli/tctl.mdx). [#1525](https://github.com/gravitational/teleport/issues/1525) [#2991](https://github.com/gravitational/teleport/issues/2991) ### Fixes diff --git a/docs/config.json b/docs/config.json index 5e2c9f15c46..1810f124ebe 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1367,7 +1367,25 @@ }, { "title": "Command Line", - "slug": "/reference/cli/" + "slug": "/reference/cli/", + "entries": [ + { + "title": "teleport", + "slug": "/reference/cli/teleport/" + }, + { + "title": "tsh", + "slug": "/reference/cli/tsh/" + }, + { + "title": "tctl", + "slug": "/reference/cli/tctl/" + }, + { + "title": "tbot", + "slug": "/reference/cli/tbot/" + } + ] }, { "title": "Metrics", diff --git a/docs/pages/access-controls/access-requests/resource-requests.mdx b/docs/pages/access-controls/access-requests/resource-requests.mdx index 74f5be34441..06ae8d2ded7 100644 --- a/docs/pages/access-controls/access-requests/resource-requests.mdx +++ b/docs/pages/access-controls/access-requests/resource-requests.mdx @@ -589,5 +589,5 @@ within your organization's existing messaging and project management solutions. `tsh request create` supports flags to control TTLs for the request and elevated access. See the [CLI -Reference](../../reference/cli.mdx#tsh-request-create) for more +Reference](../../reference/cli/tsh.mdx#tsh-request-create) for more details. diff --git a/docs/pages/access-controls/access-requests/role-requests.mdx b/docs/pages/access-controls/access-requests/role-requests.mdx index 036c6eef2b8..1bb32666115 100644 --- a/docs/pages/access-controls/access-requests/role-requests.mdx +++ b/docs/pages/access-controls/access-requests/role-requests.mdx @@ -216,5 +216,5 @@ spec: Users can also create Access Requests with the `tsh request create` command. `tsh request create` supports flags to control TTLs for the request and elevated access. See the [CLI -Reference](../../reference/cli.mdx#tsh-request-create) for more +Reference](../../reference/cli/tsh.mdx#tsh-request-create) for more details. diff --git a/docs/pages/access-controls/compliance-frameworks/soc2.mdx b/docs/pages/access-controls/compliance-frameworks/soc2.mdx index f2f487d8871..6573d1e91f7 100644 --- a/docs/pages/access-controls/compliance-frameworks/soc2.mdx +++ b/docs/pages/access-controls/compliance-frameworks/soc2.mdx @@ -58,7 +58,7 @@ Each principle has many "Points of Focus" which will apply differently to differ | CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../agents/join-services-to-your-cluster/join-token.mdx) | | CC6.1 - Uses Encryption to Protect Data | The entity uses encryption to supplement other measures used to protect data at rest, when such protections are deemed appropriate based on assessed risk. | Teleport Audit logs can use DynamoDB encryption at rest. | | CC6.1 - Protects Encryption Keys | Processes are in place to protect encryption keys during generation, storage, use, and destruction. | Teleport acts as a Certificate Authority to issue SSH and x509 user certificates that are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically | -| CC6.2 - Controls Access Credentials to Protected Assets | Information asset access credentials are created based on an authorization from the system's asset owner or authorized custodian. | [Request Approval from the command line](../../reference/cli.mdx#tctl-request-approve)

[Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx)

[Use Plugins to send approvals to tools like Slack or Jira](../../access-controls/access-requests.mdx) | +| CC6.2 - Controls Access Credentials to Protected Assets | Information asset access credentials are created based on an authorization from the system's asset owner or authorized custodian. | [Request Approval from the command line](../../reference/cli/tctl.mdx#tctl-request-approve)

[Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx)

[Use Plugins to send approvals to tools like Slack or Jira](../../access-controls/access-requests.mdx) | | CC6.2 - Removes Access to Protected Assets When Appropriate | Processes are in place to remove credential access when an individual no longer requires such access. | [Teleport issues temporary credentials based on an employees role and are revoked upon job change, termination or end of a maintenance window](../../access-controls/access-requests.mdx) | | CC6.2 - Reviews Appropriateness of Access Credentials | The appropriateness of access credentials is reviewed on a periodic basis for unnecessary and inappropriate individuals with credentials. | Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. | | CC6.3 - Creates or Modifies Access to Protected Information Assets | Processes are in place to create or modify access to protected information assets based on authorization from the asset’s owner. | [Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx) to get authorization from asset owners. | diff --git a/docs/pages/access-controls/guides/webauthn.mdx b/docs/pages/access-controls/guides/webauthn.mdx index f51437f1d2a..34e66881c93 100644 --- a/docs/pages/access-controls/guides/webauthn.mdx +++ b/docs/pages/access-controls/guides/webauthn.mdx @@ -172,7 +172,7 @@ fallback to a weaker second factor, like OTP, using `tsh mfa add --mfa-mode=otp`. See the possible `--mfa-mode` values in the [Teleport CLI -Reference](../../reference/cli.mdx#tsh-global-flags) page. +Reference](../../reference/cli/tsh.mdx#tsh-global-flags) page. ## Step 3/3. Log in using WebAuthn diff --git a/docs/pages/access-controls/login-rules/guide.mdx b/docs/pages/access-controls/login-rules/guide.mdx index 7c9350ec2aa..ae704a97c0e 100644 --- a/docs/pages/access-controls/login-rules/guide.mdx +++ b/docs/pages/access-controls/login-rules/guide.mdx @@ -159,7 +159,7 @@ $ tctl get --format json users/ | jq '{traits: first.spec. ## Troubleshooting -The [`tctl sso test`](../../reference/cli.mdx#tctl-sso-test) command can be used to +The [`tctl sso test`](../../reference/cli/tctl.mdx#tctl-sso-test) command can be used to debug SSO logins and see exactly which traits are being sent by your SSO provider and how they are being mapped by your Login Rules. @@ -177,7 +177,7 @@ To learn more about the Login Rule expression syntax, check out the [Login Rule Reference](./reference.mdx) page. Learn about the `tctl login_rule test` command by running the help command or -checking the [reference page](../../reference/cli.mdx#tctl-login_rule-test). +checking the [reference page](../../reference/cli/tctl.mdx#tctl-login_rule-test). ```code $ tctl help login_rule test ``` diff --git a/docs/pages/access-controls/sso/github-sso.mdx b/docs/pages/access-controls/sso/github-sso.mdx index b25d781cc6d..527a0636765 100644 --- a/docs/pages/access-controls/sso/github-sso.mdx +++ b/docs/pages/access-controls/sso/github-sso.mdx @@ -55,7 +55,7 @@ command with: Roles are defined in the **Repository roles** section of your organization's settings. -See [tctl sso configure github](../../reference/cli.mdx#tctl-sso-configure-github) +See [tctl sso configure github](../../reference/cli/tctl.mdx#tctl-sso-configure-github) for a full reference of flags for this command: ```code diff --git a/docs/pages/access-controls/sso/oidc.mdx b/docs/pages/access-controls/sso/oidc.mdx index b477d088729..545795fc00a 100644 --- a/docs/pages/access-controls/sso/oidc.mdx +++ b/docs/pages/access-controls/sso/oidc.mdx @@ -85,7 +85,7 @@ $ tctl sso configure oidc --name \ Teleport roles. For more information on these and all available flags, see the [tctl sso configure -oidc](../../reference/cli.mdx#tctl-sso-configure-oidc) section of the Teleport CLI +oidc](../../reference/cli/tctl.mdx#tctl-sso-configure-oidc) section of the Teleport CLI Reference page. The file created should look like the example below. This connector requests diff --git a/docs/pages/access-controls/sso/okta.mdx b/docs/pages/access-controls/sso/okta.mdx index 3520a6d6caa..97d30a9ac4c 100644 --- a/docs/pages/access-controls/sso/okta.mdx +++ b/docs/pages/access-controls/sso/okta.mdx @@ -144,7 +144,7 @@ You can also right click on the "View IdP metadata" link and select Define an Okta SAML connector using `tctl`. Update this example command with the path to your metadata file, and edit the `--attributes-to-roles` values for custom group assignment to roles. See [tctl sso configure -saml](../../reference/cli.mdx#tctl-sso-configure-saml) for a full reference of +saml](../../reference/cli/tctl.mdx#tctl-sso-configure-saml) for a full reference of flags for this command: ```code diff --git a/docs/pages/agents/join-services-to-your-cluster/join-token.mdx b/docs/pages/agents/join-services-to-your-cluster/join-token.mdx index 67ca62d13f1..026ab247dae 100644 --- a/docs/pages/agents/join-services-to-your-cluster/join-token.mdx +++ b/docs/pages/agents/join-services-to-your-cluster/join-token.mdx @@ -219,7 +219,7 @@ Copy the CA pin and assign it to the value of . The CA pin becomes invalid if a Teleport administrator performs the CA rotation -by executing [`tctl auth rotate`](../../reference/cli.mdx#tctl-auth-rotate). +by executing [`tctl auth rotate`](../../reference/cli/tctl.mdx#tctl-auth-rotate). diff --git a/docs/pages/architecture/nodes.mdx b/docs/pages/architecture/nodes.mdx index eb5b23a0dfa..113dd715dd3 100644 --- a/docs/pages/architecture/nodes.mdx +++ b/docs/pages/architecture/nodes.mdx @@ -18,7 +18,7 @@ Here is why we recommend Teleport Node service instead of OpenSSH: Just like with OpenSSH, the `node` service provides SSH access to every node with any clients supporting client SSH certificates: - [OpenSSH: `ssh`](../server-access/guides/openssh.mdx) -- [Teleport CLI client: `tsh ssh`](../reference/cli.mdx#tsh-ssh) +- [Teleport CLI client: `tsh ssh`](../reference/cli/tsh.mdx#tsh-ssh) - [Teleport Proxy UI](./proxy.mdx) accessed via a web browser. - Ansible and other SSH compatible clients. diff --git a/docs/pages/architecture/session-recording.mdx b/docs/pages/architecture/session-recording.mdx index c1f49e4d6b5..6de3e1f8e77 100644 --- a/docs/pages/architecture/session-recording.mdx +++ b/docs/pages/architecture/session-recording.mdx @@ -171,7 +171,7 @@ should be noted that they are not TAR archives and cannot be read using the `tar ## Playback SSH and Kubernetes sessions can be played in Teleport's Web UI or by using -the [`tsh play`](../reference/cli.mdx#tsh-play) command. Desktop session +the [`tsh play`](../reference/cli/tsh.mdx#tsh-play) command. Desktop session recordings can only be played back in the Web UI. In the Web UI, the session recordings page is populated by querying Teleport's diff --git a/docs/pages/connect-your-client/putty.mdx b/docs/pages/connect-your-client/putty.mdx index 00782cc0949..b04ada48e67 100644 --- a/docs/pages/connect-your-client/putty.mdx +++ b/docs/pages/connect-your-client/putty.mdx @@ -243,5 +243,5 @@ To remove `tsh` and associated user data see [Uninstalling Teleport](../management/admin/uninstall-teleport.mdx). ## Further reading -- [CLI Reference](../reference/cli.mdx#tsh-puttyconfig). +- [CLI Reference](../reference/cli/tsh.mdx#tsh-puttyconfig). diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx index e7125aa97a2..cf01e40e3b6 100644 --- a/docs/pages/connect-your-client/teleport-connect.mdx +++ b/docs/pages/connect-your-client/teleport-connect.mdx @@ -160,7 +160,7 @@ version of tsh for any actions performed within the app. Teleport Connect makes tsh available to use in your terminal of choice as well. Please note that at the moment tsh and Teleport Connect operate on different sets of profiles, as Teleport Connect sets a custom home location through [the `TELEPORT_HOME` environment -variable](../reference/cli.mdx#tsh-environment-variables). For example, logging in to a new cluster +variable](../reference/cli/tsh.mdx#tsh-environment-variables). For example, logging in to a new cluster through tsh will not make that cluster show up in Teleport Connect. diff --git a/docs/pages/connect-your-client/tsh.mdx b/docs/pages/connect-your-client/tsh.mdx index 38555623637..55e22fc4e98 100644 --- a/docs/pages/connect-your-client/tsh.mdx +++ b/docs/pages/connect-your-client/tsh.mdx @@ -21,7 +21,7 @@ terminal for the CLI reference. ## Introduction For the impatient, here's an example of how a user would typically use -[`tsh`](../reference/cli.mdx#tsh): +[`tsh`](../reference/cli/tsh.mdx): @@ -76,7 +76,7 @@ $ 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`](../reference/cli.mdx#tsh-login) in the beginning. +to call [`tsh login`](../reference/cli/tsh.mdx#tsh-login) in the beginning. ## Installing tsh @@ -132,7 +132,7 @@ $ tsh ssh --proxy=mytenant.teleport.sh --user=joe root@node -[CLI Docs - tsh ssh](../reference/cli.mdx#tsh-ssh) +[CLI Docs - tsh ssh](../reference/cli/tsh.mdx#tsh-ssh) ## Logging in @@ -163,7 +163,7 @@ $ tsh login --proxy=mytenant.teleport.sh -[CLI Docs - tsh login](../reference/cli.mdx#tsh-login) +[CLI Docs - tsh login](../reference/cli/tsh.mdx#tsh-login) | Port | Description | | - | - | @@ -178,7 +178,7 @@ This allows you to authenticate just once, maybe at the beginning of the day. Su type="tip" title="Tip" > - It is recommended to always use [`tsh login`](../reference/cli.mdx#tsh-login) before using any other `tsh` commands. This allows users to omit `--proxy` flag in subsequent tsh commands. For example `tsh ssh user@host` will work. + It is recommended to always use [`tsh login`](../reference/cli/tsh.mdx#tsh-login) before using any other `tsh` commands. This allows users to omit `--proxy` flag in subsequent tsh commands. For example `tsh ssh user@host` will work. A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via GitHub](../access-controls/sso/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use: @@ -231,7 +231,7 @@ $ tsh login --proxy=mytenant.teleport.sh --browser=none In this situation, a link will be printed on the screen. You can copy and paste this link into a browser of your choice to continue the login flow. -[CLI Docs - tsh login](../reference/cli.mdx#tsh-login) +[CLI Docs - tsh login](../reference/cli/tsh.mdx#tsh-login) ### Inspecting an SSH certificate @@ -271,7 +271,7 @@ $ tsh status -[CLI Docs - tsh status](../reference/cli.mdx#tsh-status) +[CLI Docs - tsh status](../reference/cli/tsh.mdx#tsh-status) ### SSH agent support @@ -292,7 +292,7 @@ variable to `false` in your shell profile to make this permanent. ### Identity files -[`tsh login`](../reference/cli.mdx#tsh-login) can also save the user certificate into a +[`tsh login`](../reference/cli/tsh.mdx#tsh-login) can also save the user certificate into a file: @@ -389,7 +389,7 @@ $ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem -[CLI Docs - tctl auth sign](../reference/cli.mdx#tctl-auth-sign) +[CLI Docs - tctl auth sign](../reference/cli/tctl.mdx#tctl-auth-sign) Now `jenkins.pem` can be copied to the Jenkins server and passed to the `-i` (identity file) flag of `tsh`. @@ -414,7 +414,7 @@ $ tsh ls # graviton 10.1.0.7:3022 os:osx ``` -[CLI Docs - tsh ls](../reference/cli.mdx#tsh-ls) +[CLI Docs - tsh ls](../reference/cli/tsh.mdx#tsh-ls) `tsh ls` can apply a filter based on the node labels. @@ -427,7 +427,7 @@ $ tsh ls os=osx # graviton 33333333-aaaa-1284 10.1.0.7:3022 os:osx ``` -[CLI Docs -tsh ls](../reference/cli.mdx#tsh-ls) +[CLI Docs -tsh ls](../reference/cli/tsh.mdx#tsh-ls)
@@ -698,7 +698,7 @@ $ tsh --proxy=mytenant.teleport.sh clusters -[CLI Docs - tsh clusters](../reference/cli.mdx#tsh-clusters) +[CLI Docs - tsh clusters](../reference/cli/tsh.mdx#tsh-clusters) Now you can use the `--cluster` flag with any `tsh` command. For example, to list SSH nodes that are members of the `production` cluster, simply run: diff --git a/docs/pages/core-concepts.mdx b/docs/pages/core-concepts.mdx index d60afa68940..0be02a56038 100644 --- a/docs/pages/core-concepts.mdx +++ b/docs/pages/core-concepts.mdx @@ -60,7 +60,7 @@ databases. A single running `teleport` process can run one or more **Teleport services**, depending on the user's configuration. Read about all subcommands of `teleport` -in our [CLI Reference](./reference/cli.mdx#teleport). +in our [CLI Reference](./reference/cli/teleport.mdx). ### Teleport Application Service diff --git a/docs/pages/database-access/reference/aws.mdx b/docs/pages/database-access/reference/aws.mdx index db259e77cb0..a4c12bbbb96 100644 --- a/docs/pages/database-access/reference/aws.mdx +++ b/docs/pages/database-access/reference/aws.mdx @@ -16,8 +16,8 @@ users and permission to manage the passwords in AWS Secrets Manager. You can generate and manage the permissions with the [`teleport db configure bootstrap`](../../database-access/reference/cli.mdx#teleport-db-configure-bootstrap) -command. For example, the following command would generate and print the -IAM policies: +command. For example, the following command would generate and print the IAM +policies: ```code $ teleport db configure bootstrap --manual diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index a8b70da1fab..63876bbc12a 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -135,7 +135,7 @@ you need its ID. You can get a listing of all alerts and their IDs with the `tctl alerts list` command. For detailed information on this family of commands, see the -[CLI Reference](./reference/cli.mdx#tctl-alerts-list). +[CLI Reference](./reference/cli/tctl.mdx#tctl-alerts-list). ## Does Teleport send any data back to the cloud? diff --git a/docs/pages/kubernetes-access/manage-access/federation.mdx b/docs/pages/kubernetes-access/manage-access/federation.mdx index 543020c8230..69d73207cbb 100644 --- a/docs/pages/kubernetes-access/manage-access/federation.mdx +++ b/docs/pages/kubernetes-access/manage-access/federation.mdx @@ -13,9 +13,9 @@ to federate trust across Kubernetes clusters. When multiple Trusted Clusters are present behind the Teleport Proxy Service, the -`kubeconfig` generated by [tsh login](../../reference/cli.mdx#tsh-login) will contain the +`kubeconfig` generated by [tsh login](../../reference/cli/tsh.mdx#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [tsh -login](../../reference/cli.mdx#tsh-login). +login](../../reference/cli/tsh.mdx#tsh-login). For example, consider the following setup: @@ -45,9 +45,9 @@ $ tsh --proxy=main.example.com login east When multiple Trusted Clusters are present behind the Teleport Proxy Service, the -`kubeconfig` generated by [tsh login](../../reference/cli.mdx#tsh-login) will contain the +`kubeconfig` generated by [tsh login](../../reference/cli/tsh.mdx#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [tsh -login](../../reference/cli.mdx#tsh-login). +login](../../reference/cli/tsh.mdx#tsh-login). For example, consider the following setup: diff --git a/docs/pages/machine-id/reference.mdx b/docs/pages/machine-id/reference.mdx index 08101589342..bbf4a58213c 100644 --- a/docs/pages/machine-id/reference.mdx +++ b/docs/pages/machine-id/reference.mdx @@ -6,6 +6,6 @@ description: Configuration and CLI reference for Teleport Machine ID. - [Configuration](./reference/configuration.mdx) - [GitHub Actions](./reference/github-actions.mdx) - [GitLab CI](./reference/gitlab.mdx) -- [CLI](../reference/cli.mdx#tbot) +- [CLI](../reference/cli/tbot.mdx) - [Telemetry](./reference/telemetry.mdx) - [V14 Upgrade Guide](./reference/v14-upgrade-guide.mdx) diff --git a/docs/pages/management/admin/daemon.mdx b/docs/pages/management/admin/daemon.mdx index 342e3ad93a6..21ebd260388 100644 --- a/docs/pages/management/admin/daemon.mdx +++ b/docs/pages/management/admin/daemon.mdx @@ -147,8 +147,9 @@ until existing clients disconnect. To upgrade a host to a newer version of Teleport, you must: -- Replace the Teleport binaries, usually [`teleport`](../../reference/cli.mdx#teleport) - and [`tctl`](../../reference/cli.mdx#tctl). +- Replace the Teleport binaries, usually + [`teleport`](../../reference/cli/teleport.mdx) and + [`tctl`](../../reference/cli/tctl.mdx). - Execute `systemctl reload teleport`. @@ -182,7 +183,7 @@ $ sudo teleport install systemd \ In this guide, we showed you how to run `teleport start` as a systemd service. To see all commands that you can run via the `teleport` binary, see the -[Teleport CLI Reference](../../reference/cli.mdx#teleport). +[Teleport CLI Reference](../../reference/cli/teleport.mdx). While we used a minimal configuration in this guide, for a production Teleport cluster, you should consult our diff --git a/docs/pages/management/admin/users.mdx b/docs/pages/management/admin/users.mdx index b47dbde42da..ef6188e4151 100644 --- a/docs/pages/management/admin/users.mdx +++ b/docs/pages/management/admin/users.mdx @@ -117,7 +117,7 @@ $ tctl users rm joe In addition to users, you can use `tctl` to manage roles and other dynamic resources. See our [Teleport Resources Reference](../../reference/resources.mdx). -For all available `tctl` commands and flags, see our [CLI Reference](../../reference/cli.mdx#tctl). +For all available `tctl` commands and flags, see our [CLI Reference](../../reference/cli/tctl.mdx). You can also configure Teleport so that users can log in using an SSO provider. For more information, see: @@ -131,7 +131,7 @@ In addition to users, you can use `tctl` to manage roles and other dynamic resources. See our [Teleport Resources Reference](../../reference/resources.mdx). For all available `tctl` commands and flags, see our -[CLI Reference](../../reference/cli.mdx#tctl). +[CLI Reference](../../reference/cli/tctl.mdx). You can also configure Teleport so that users can log in using GitHub. For more information, see [GitHub SSO](../../access-controls/sso/github-sso.mdx). diff --git a/docs/pages/management/dynamic-resources.mdx b/docs/pages/management/dynamic-resources.mdx index bb3cf9284fd..49691b661e4 100644 --- a/docs/pages/management/dynamic-resources.mdx +++ b/docs/pages/management/dynamic-resources.mdx @@ -103,7 +103,7 @@ spec: Since `tctl` works from the local filesystem, you can write commands that apply all configuration documents in a directory tree. See the [CLI -reference](../reference/cli.mdx#tctl) for more information on `tctl`. +reference](../reference/cli/tctl.mdx) for more information on `tctl`. ### Teleport Terraform provider diff --git a/docs/pages/reference/audit.mdx b/docs/pages/reference/audit.mdx index 2b1112fc88d..6538ed08e85 100644 --- a/docs/pages/reference/audit.mdx +++ b/docs/pages/reference/audit.mdx @@ -165,7 +165,7 @@ or in a local filesystem (including NFS). The recorded sessions are stored as raw bytes in the `sessions` directory under `log`. Each session is a protobuf-encoded stream of binary data. -You can replay recorded sessions using the [`tsh play`](./cli.mdx#tsh-play) +You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) command or the Web UI. For example, replay a session via CLI: @@ -186,8 +186,8 @@ $ tsh play 4c146ec8-eab6-11e6-b1b3-40167e68e931 --format=json Teleport Team and Teleport Enterprise Cloud automatically store recorded sessions. -You can replay recorded sessions using the [`tsh play`](./cli.mdx#tsh-play) command or the Web -UI. +You can replay recorded sessions using the [`tsh play`](./cli/tsh.mdx#tsh-play) +command or the Web UI. For example, replay a session via CLI: diff --git a/docs/pages/reference/authentication.mdx b/docs/pages/reference/authentication.mdx index 1acd2e20007..3a5e6f0d0d7 100644 --- a/docs/pages/reference/authentication.mdx +++ b/docs/pages/reference/authentication.mdx @@ -9,9 +9,10 @@ provider via **authentication connectors**. ## Local (no authentication connector) Local authentication is used to authenticate against a local Teleport user -database. This database is managed by the [`tctl users`](./cli.mdx#tctl-users-add) -command. Teleport also supports multi-factor authentication (MFA) for the local -connector. There are several possible values (types) of MFA: +database. This database is managed by the [`tctl +users`](./cli/tctl.mdx#tctl-users-add) command. Teleport also supports +multi-factor authentication (MFA) for the local connector. There are several +possible values (types) of MFA: - `otp` is the default. It implements the [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) standard. You can use [Google Authenticator](https://en.wikipedia.org/wiki/Google_Authenticator), [Authy](https://www.authy.com/) or any other TOTP client. diff --git a/docs/pages/reference/cli.mdx b/docs/pages/reference/cli.mdx index 815c8f638dd..5bd6a55daa6 100644 --- a/docs/pages/reference/cli.mdx +++ b/docs/pages/reference/cli.mdx @@ -5,10 +5,10 @@ description: Detailed guide and reference documentation for Teleport's command l Teleport is made up of four CLI tools. -- [teleport](#teleport): Supports the Teleport Access Platform by starting and configuring various Teleport services. -- [tsh](#tsh): Allows end users to authenticate to Teleport and access resources in a cluster. -- [tctl](#tctl): Used to configure the Teleport Auth Service. -- [tbot](#tbot): Supports Machine ID, which provides short lived credentials to service accounts (e.g, a CI/CD server). +- [teleport](./cli/teleport.mdx): Supports the Teleport Access Platform by starting and configuring various Teleport services. +- [tsh](./cli/tsh.mdx): Allows end users to authenticate to Teleport and access resources in a cluster. +- [tctl](./cli/tctl.mdx): Used to configure the Teleport Auth Service. +- [tbot](./cli/tbot.mdx): Supports Machine ID, which provides short lived credentials to service accounts (e.g, a CI/CD server). (!docs/pages/includes/permission-warning.mdx!) @@ -44,2915 +44,6 @@ Teleport is made up of four CLI tools. (!docs/pages/includes/backup-warning.mdx!) -## teleport - -The CLI tool that supports the Teleport Access Platform is called `teleport`, and allows Teleport services to be managed -over the command line: - -- [Auth](../architecture/authentication.mdx) -- [Node/SSH](../architecture/nodes.mdx) -- [Proxy](../architecture/proxy.mdx) -- [App](../application-access/introduction.mdx) -- [Database](../database-access/introduction.mdx) -- [Windows Desktop](../desktop-access/introduction.mdx) -- [Kubernetes](../kubernetes-access/introduction.mdx) - -The primary commands for the `teleport` CLI are as follows: - -| Command | Description | -| - | - | -| `teleport help` | Outputs guidance for using Teleport commands. | -| `teleport start` | Starts the `teleport` process in the foreground using the current shell session, including any services configured by the [configuration YAML file](config.mdx). | -| `teleport status` | Prints the status of the current active Teleport SSH session. | -| `teleport configure` | Generates and writes a [configuration YAML file](config.mdx) for the Teleport service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. | -| `teleport version` | Prints the current release version of the Teleport binary installed on your system. | -| `teleport app start` | Starts the Teleport Application Service. | -| `teleport db start` | Starts the Teleport Database Service. | -| `teleport db configure create` | Generates a configuration YAML file for the Database Service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. | -| `teleport db configure bootstrap` | Used to bootstrap a configuration to the Teleport Database Service by reading a provided configuration. | -| `teleport db configure aws print-iam` | Generates and outputs current IAM policies for a Teleport-managed database. | -| `teleport db configure aws create-iam` | Generates, creates, and attaches desired IAM policies to a Teleport-managed database. | -| `teleport install systemd` | Creates a systemd unit file, used to configure and install a `teleport` service daemon. | -| `teleport node configure` | Generates a configuration YAML file for a Teleport Node accessed via SSH. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing. | - - -For more information on subcommands when working with the `teleport` cli, use the `--help` option or `teleport --help`. - - -### teleport start - -The `teleport start` command includes a large number of optional configuration flags. - -While configuration flags for `teleport start` can be used to set parameters for Teleport's configuration, -we recommend using a [configuration file](./config.mdx) in production. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-d, --debug` | none | none | enable verbose logging to stderr | -| `--insecure-no-tls` | `false` | `true` or `false` | Tells proxy to not generate default self-signed TLS certificates. This is useful when running Teleport on kubernetes (behind reverse proxy) or behind things like AWS ELBs, GCP LBs or Azure Load Balancers where SSL termination is provided externally. | -| `-r, --roles` | `proxy`, `node`, `auth` | **string** comma-separated list of `proxy`, `node`, `auth`, `db`, or `app` | start listed services/roles. These roles are explained in the [Core Concepts](../core-concepts.mdx) document. | -| `--pid-file` | none | **string** filepath | create a PID file at the path | -| `--advertise-ip` | none | **string** IP | advertise IP to clients, often used behind NAT | -| `-l, --listen-ip` | `0.0.0.0` | [**net. IP**](https://golang.org/pkg/net/#IP) | binds services to IP | -| `--auth-server` | none | **string** IP | proxy attempts to connect to a specified auth server instead of local auth, disables `--roles=auth` if set | -| `--token` | none | **string** | set invitation token to register with an auth server on start, used once and ignored afterwards. Obtain it by running `tctl nodes add` on the auth server.*We recommend to use tools like `pwgen` to generate sufficiently random tokens of 32+ byte length.* | -| `--ca-pin` | none | **string** `sha256:` | set CA pin to validate the Auth Server. Generated by `tctl status` | -| `--nodename` | value returned by the `hostname` command on the machine | **string** | assigns an alternative name for the node which can be used by clients to log in. | -| `-c, --config` | `/etc/teleport.yaml` | **string** `.yaml` filepath | starts services with config specified in the YAML file, overrides CLI flags if set | -| `--apply-on-startup` | none | **string** `.yaml` filepath | On startup, always apply resources described in the file at the given path. Only supports the following types: `token`. | -| `--bootstrap` | none | **string** `.yaml` filepath | bootstrap configured YAML resources {/* TODO link how to configure this file */} | -| `--labels` | none | **string** comma-separated list | assigns a set of labels to a node, for example env=dev,app=web. See the explanation of labeling mechanism in the [Labeling Nodes](../management/admin/labels.mdx) section. | -| `--insecure` | none | none | disable certificate validation on Proxy Service, validation still occurs on Auth Service. | -| `--fips` | none | none | start Teleport in FedRAMP/FIPS 140-2 mode. | -| `--skip-version-check` | `false` | `true` or `false` | Skips version checks between the Auth Server this Teleport instance | -| `--diag-addr` | none | none | Enable diagnostic endpoints | -| `--permit-user-env` | none | none | flag reads in environment variables from `~/.tsh/environment` when creating a session. | -| `--app-name` | none | none | Name of the application to start | -| `--app-uri` | none | none | Internal address of the application to proxy | -| `--app-public-addr` | none | none | Public address fo the application to proxy | - -#### teleport start --roles - -The `--roles` flag when used with `teleport --start` instructs Teleport on which specific Teleport services to start. Below is a more cohesive table of roles and their associated services that `teleport start` supports: - -| Service | Role Name | Description | -| - | - | - | -| [Node](../architecture/nodes.mdx) | `node` | Allows SSH connections from authenticated clients. | -| [Auth](../architecture/authentication.mdx) | `auth` | Authenticates and authorizes hosts and users who want access to Teleport-managed resources or information about a cluster. | -| [Proxy](../architecture/proxy.mdx) | `proxy` | The gateway that clients use to connect to the Auth Service or resources managed by Teleport. | -| [App](../application-access/introduction.mdx) | `app` | Provides access to applications. | -| [Database](../database-access/reference.mdx) | `db` | Provides access to databases. | - - - -Teleport Cloud manages Teleport instances with the `auth` and `proxy` roles. Use -the remaining roles to manage access to specific resources and other Teleport -clusters. - - - -#### Examples - -``` -# By default without any configuration, teleport starts running as a single-node -# cluster. It's the equivalent of running with --roles=node,proxy,auth -sudo teleport start - -# Starts a node named 'db' running in strictly SSH mode role, joining the cluster -# serviced by the auth server running on 10.1.0.1 -sudo teleport start --roles=node --auth-server=10.1.0.1 --token=xyz --nodename=db - -# Same as the above, but the node runs with db=master label and can be connected -# to using that label in addition to its name. -sudo teleport start --roles=node --auth-server=10.1.0.1 --labels=db=master - -# Starts an app server that proxies the application "example-app" running at http://localhost:8080. -sudo teleport start --roles=app --token=xyz --auth-server=proxy.example.com:3080 \ - --app-name="example-app" \ - --app-uri="http://localhost:8080" \ - --labels=group=dev -``` - -## tsh - -`tsh` is a CLI client used by Teleport Users. It allows users to interact with -current and past sessions on the cluster, copy files to and from nodes, and list -information about the cluster. - -### tsh global flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-l, --login` | none | an identity name | The login identity that the Teleport user will use | -| `--proxy` | none | `host:https_port[,ssh_proxy_port]` | Teleport Proxy Service address | -| `--user` | `$USER` | none | The Teleport username | -| `--ttl` | `720` (12 hours) | integer | Number of minutes a certificate issued for the `tsh` user will be valid for | -| `-i, --identity` | none | **string** filepath | Identity file | -| `--cert-format` | `standard` | `standard` or `oldssh` | SSH certificate format. `oldssh` supports older versions of OpenSSH servers that do not allow for custom metadata, which is how Teleport encodes a user's roles in their SSH certificate. | -| `--insecure` | none | none | Do not verify the server's certificate and host name. Use only in test environments. | -| `--auth` | `local` | Any defined [authentication connector](./authentication.mdx), including `passwordless` and `local` (i.e., no authentication connector) | Specify the type of authentication connector to use. | -| `--mfa-mode` | auto | `auto`, `cross-platform`, `platform` or `otp` | Preferred mode for MFA and Passwordless assertions. | -| `--skip-version-check` | none | none | Skip version checking between server and client. | -| `-d, --debug` | none | none | Verbose logging to stdout | -| `-J, --jumphost` | none | A jump host | SSH jumphost | -| `--headless` | none | none | Use Headless WebAuthn for authentication | -| `--mlock` | `auto` | `auto`, `off`, `best_effort`, `strict` | Lock process memory to protect client secrets stored in memory from being swapped to disk. | - -### tsh help - -Prints help: - -```code -$ tsh help -``` - -### tsh version - -Prints the version of your `tsh` binary and the Teleport Proxy Service in the current `tsh` profile - -```code -$ tsh version [] -``` - -| Name | Default Value(s) | Allowed Value(s) | Description | -|----------------|------------------|------------------|----------------------------------------------------| -| `-f, --format` | `text` | text, json, yaml | Format for version output | -| `--client` | none | none | Show the client version only (no server required). | - -#### Examples - -```code -$ tsh version -Teleport v(=teleport.version=) git: go(=teleport.golang=) -Proxy version: (=teleport.version=) -Proxy: teleport.example.com:443 -``` - -Display in JSON format: - -```code -$ tsh version --format=json -``` - -```json -{ - "version": "(=teleport.version=)", - "gitref": "", - "runtime": "go(=teleport.golang=)", - "proxyVersion": "(=teleport.version=)", - "proxyPublicAddress": "teleport.example.com:443" -} -``` - -Only display the `tsh` binary version: - -```code -$ tsh version --client -Teleport v(=teleport.version=) git: go(=teleport.golang=) -``` - -### tsh ssh - -Run shell or execute a command on a remote SSH node: - -```code -$ tsh ssh [] <[user@]host> [...] -``` - -#### Arguments - -`<[user@]host> [...]` - -- `user` The login identity to use on the remote host. If `[user]` is not specified the user defaults to `$USER` or can be set with `--user`. If the flag `--user` and positional argument `[user]` are specified the arg `[user]` takes precedence. -- `host` The `nodename` of a cluster Node or a label specification like `env=aws` to run on all matching hosts. -- `command` The command to execute on a remote host. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-p, --port` | none | port | SSH port on a remote host | -| `-A, --forward-agent` | none | none | Forward agent to target node like `ssh -A` | -| `-L, --forward` | none | none | Forward localhost connections to remote server | -| `-D, --dynamic-forward` | none | none | Forward localhost connections to remote server using SOCKS5 | -| `-N, -no-remote-exec` | none | none | Don't execute remote command, useful for port forwarding | -| `--local` | none | | Execute command on localhost after connecting to SSH node | -| `-t, --tty` | `file` | | Allocate TTY | -| `--cluster` | none | | Specify the cluster to connect | -| `-o, --option` | `local` | | OpenSSH options in the format used in the configuration file | -| `--enable-escape-sequences` | | | Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences. | -| `--no-use-local-ssh-agent` | | | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) | -| `-X, --x11-untrusted` | none | none | Requests untrusted (secure) X11 forwarding for this session. | -| `-Y, --x11-trusted` | none | none | Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution. | -| `--x11-untrusted-timeout` | 10m | duration | Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server. | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -# Log in to node `grav-00` as OS User `root` with Teleport User `teleport` -$ tsh ssh --proxy proxy.example.com --user teleport -d root@grav-00 -# `tsh ssh` takes the same arguments as OpenSSH client: -$ tsh ssh -o ForwardAgent=yes root@grav-00 -$ tsh ssh -o AddKeysToAgent=yes root@grav-00 -# Run `hostname` on all nodes with the `env: aws` label -$ tsh ssh root@env=aws hostname -``` - -### tsh config - -Generates OpenSSH configuration to use currently logged in teleport -as a bastion host. - -```code -$ tsh config -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-l, --login` | none | Linux username | Default Linux username to use. Will translate to SSH config's `User` option. | -| `-p`, `--port` | 3022 | port | Default SSH port to use. Will translate to SSH config's `Port` option. | - - -#### Examples - -```code -# Print OpenSSH config file to console -$ tsh config - -# Append Teleport configuration to ssh config -$ tsh config >> ~/.ssh/config -``` - -### tsh puttyconfig - -Adds a PuTTY saved session to the Windows registry for the currently logged in Windows user. - -``` -$ tsh puttyconfig [--leaf ] [login@]hostname -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-l, --login` | none | Linux username | Default Linux username to use. Will translate to SSH config's `User` option. | -| `-p`, `--port` | 3022 | port | Default SSH port to use. Will translate to SSH config's `Port` option. | -| `--leaf` | none | Leaf cluster name | Leaf cluster name to add to the saved session. | - -#### Examples - -```code -# Add a saved PuTTY session on 'node' for the user 'ec2-user' -$ tsh puttyconfig ec2-user@node - -# Add a saved PuTTY session on leaf-node for the user 'ec2-user' on the leaf cluster 'example.teleport.sh' -$ tsh puttyconfig --leaf example.teleport.sh ec2-user@leaf-node -``` - -See [full docs on `tsh puttyconfig` here](../connect-your-client/putty.mdx). - -### tsh apps ls - -List all available applications: - -```code -$ tsh apps ls -``` - -### tsh gcloud - -Proxy `gcloud` CLI commands through the Teleport Application Service. `gcloud` -is a tool for interacting with Google Cloud. A user must already be -authenticated to a Google Cloud application in Teleport before they can execute -`tsh gcloud` commands. - -```code -$ tsh gcloud [--app] [] -``` - -#### Arguments - -`command`: A `gcloud` command to run, including arguments and flags. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--app` | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -$ tsh gcloud compute instances list -``` - -### tsh gsutil - -Proxy `gsutil` CLI commands through the Teleport Application Service. `gsutil` -is a tool for interacting with Google Cloud Storage. A user must already be -authenticated to a Google Cloud application in Teleport before they can execute -`tsh gsutil` commands. - -```code -$ tsh gsutil [--app] [] -``` - -#### Arguments - -`command`: A `gsutil` command to run, including arguments and flags. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--app` | Currently logged in Google Cloud application | The name of a Google Cloud application as listed via `tsh apps ls`. | The Google Cloud application to run the command against, if logged in to multiple Google Cloud applications. | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -$ tsh gsutil ls -``` - -### tsh join - -Joins an active session: - -```code -$ tsh join [] -``` - -#### Arguments - -`` - -- `session-id` The UUID of an active Teleport Session obtained by `teleport status` within - the session. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cluster` | none | a cluster_name | Specify the cluster to connect | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -# join session using teleport user joe as ec2-user -$ tsh --user=joe --login=ec2-user join -``` - -### tsh recordings ls - -List recorded sessions. - -```code -$ tsh recordings ls [] -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--from-utc` | 24 hours ago | date | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. | -| `--to-utc` | current | date | Start of time range in which recordings are listed. Format 2006-01-02. Defaults to 24 hours ago. | -| `--limit` | 50 | number | Maximum number of recordings to show. | -| `--last` | none | duration | Duration into the past from which session recordings should be listed. Format 5h30m40s | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -# get the recorded sessions from the last 24 hours -$ tsh --proxy proxy.example.com recordings ls -ID Type Participants Hostname Timestamp ------------------------------------- ---- ------------ -------- ------------------- -b0a04442-70dc-4be8-9308-7b7901d2d600 ssh jeff dev Nov 26 16:36:16 UTC -c0a02222-70dc-4be8-9308-7b7901d2d600 kube alice Nov 26 20:36:16 UTC -d0a04442-70dc-4be8-9308-7b7901d2d600 ssh navin test Nov 26 16:36:16 UTC - -# The session can be played with tsh play -$ tsh play c0a02222-70dc-4be8-9308-7b7901d2d60 - -# List recorded sessions that occurred between Nov 1, 2022 to Nov 3, 2022 -$ tsh recordings ls --from-utc=2022-11-01 --to-utc=2022-11-3 - -# Retrieve recorded sessions in the last 6 hours -$ tsh recordings ls --last=6h0m0s -``` - - - -Recorded sessions are linked from the audit events to session recordings files -in their [storage backend](../reference/backends.mdx). -The following error can occur if a session recording file is not available or -when employing multiple auth servers with directory storage backend for recorded -sessions. When using a directory storage backend for audit logs and recorded sessions, -only the auth server with that recorded session can retrieve it. - -```code -$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b -ERROR: Recording for session c8e1b2c5-322a-4095-89e3-391edfd2da9b not found. -``` - -Using a Security Information and Event Management (SIEM) service that combines -the audit logs will help consolidate the list of available recordings. - -Downloaded recorded session are directly playable as a file. - -```code -$ tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b.tar -``` - - - -### tsh recordings export - -Export recorded desktop sessions to video. - -```code -$ tsh recordings export [] -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--out` | `.avi` | a filename | Override the output file name. | - -#### Examples - -```code -$ tsh recordings export c8e1b2c5-322a-4095-89e3-391edfd2da9b --out=recording.avi -wrote recording to recording.avi -``` - -### tsh play - -Plays back a prior session: - -```code -$ tsh play [] -``` - -#### Arguments - -`` - -- `session-id` The UUID of a past Teleport Session obtained by `teleport status` within - the session or from the Web UI. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cluster` | none | a cluster_name | Specify the cluster to connect | -| `--format` | `pty` | json, pty | Format for playback | - -#### Global flags - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -$ tsh --proxy proxy.example.com play - -# Playing back a session using pty format using a downloaded session recording. -$ tsh play --format=pty 1fe153d1-ce8b-4ef4-9908-6539457ba4ad.tar - -# Playing back a session in json format using jq to filter on events -$ tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event -``` - -### tsh proxy db - -Start a local TLS proxy for database connections when using Teleport with TLS -Routing enabled. Clients can connect to a Teleport-registered database through -the local proxy. - -```code -$ tsh proxy db [] -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cert-file` | none | string | Path to the certificate file for configuring TLS on the local proxy.| -| `--cluster` | none | string | The name of the Teleport cluster to connect to. | -| `--key-file` | none | string | Path to the private key file for configuring TLS on the local proxy.| -| `--db-name` | none | string | Optional database name to log in to. | -| `--db-user` | none | string | Optional database user to log in as. | -| `--port` | none | string | Source port used by the local proxy.| -| `--tunnel` | none | Boolean | Open an authenticated tunnel using a database's client certificate so clients don't need to authenticate. | - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -#### Examples - -Proxy a DB connection to a named database -```code -$ tsh proxy db -``` - -Proxy a connection to mysql db on local port 10700: -```code -$ tsh proxy db --port 10700 mysql-db -# Started DB proxy on 127.0.0.1:10700 - -# Use following credentials to connect to the mysql-db proxy: -# ca_file=/Users/jeff/.tsh/keys/teleport.example.com/cas/teleport.example.com.pem -# cert_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff-db/tele1c/mysql-db-x509.pem -# key_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff -``` - -Proxy a connection to mysql db with no credentials required: -```code -$ tsh proxy db --tunnel mysql-db -Started authenticated tunnel for the MySQL database "mysql-db" in cluster "teleport.example.com" on 127.0.0.1:49415. - -Use the following command to connect to the database: - $ mysql --port 49415 --host localhost --protocol TCP -``` - -### tsh proxy ssh - -Start a local TLS proxy for `ssh` connections when using Teleport in TLS Routing mode. -This is typically used as part of the SSH client configuration to use `ssh` as a client -through Teleport. See the [OpenSSH Guide](../server-access/guides/openssh.mdx) guide -on configuring OpenSSH servers and clients. The `tsh config` output will include `tsh proxy ssh` -within a `ProxyCommand` directive. - -```code -$ tsh proxy ssh [] <[user@]host> -``` - -#### Arguments -- `<[user@]host>` Remote hostname and the login to use - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cluster` | none | Teleport Cluster | The name of the Teleport cluster to connect to.| - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -#### Examples - -Run the following command to generate an OpenSSH client configuration: - -```code -$ tsh config -``` - -This command produces the following configuration: - -``` -# Common flags for all example.com hosts -Host *.example.com example.com - UserKnownHostsFile "/Users/jeff/.tsh/known_hosts" - IdentityFile "/Users/jeff/.tsh/keys/enterprise.teleportdemo.com/jeff" - CertificateFile "/Users/jeff/.tsh/keys/example.com/jeff-ssh/example.com-cert.pub" - PubkeyAcceptedKeyTypes +ssh-rsa-cert-v01@openssh.com - HostKeyAlgorithms ssh-rsa-cert-v01@openssh.com - -# Flags for all example.com hosts except the proxy -Host *.example.com !example.com - Port 3022 - ProxyCommand "/usr/local/bin/tsh" proxy ssh --cluster=example.com --proxy=example.com %r@%h:%p -``` - -This output should be placed into the default SSH Config for environment, `~/.ssh/config` for Mac/Linux or -`.ssh\config` in the Windows User home directory. You can use this as a standalone SSH config file too. - -When you run an `ssh` command against a host with a subdomain of your Proxy -Service's domain, this SSH configuration will use the `ProxyCommand` to run `tsh -proxy ssh`: - -```code -$ ssh myuser@node1.example.com -``` - -### tsh proxy app - -Starts a local TLS proxy for Application Service connections. -You can use this proxy to connect to an application repeatedly after a single login to your Teleport cluster, -which is especially useful for interacting with an application via a CLI. - -```code -$ tsh proxy app [] -``` - -#### Arguments -`` - -- `app` The name of the application to start the local proxy for. To see a list of available applications, run `tsh apps ls`. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `-p, --port` | none | port number | Specify the source port for the local proxy | - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -#### Examples -```code -$ tsh proxy app - -# Proxy a connection to grafana on local port 10700 -$ tsh proxy --port 10700 app grafana & -# Proxying connections to grafana on 127.0.0.1:10700 -$ curl http://127.0.0.1:10700/api/users -``` - -### tsh proxy azure - -Starts a local proxy server that provides secure access to an Azure managed -service identity endpoint. This is useful for managing access to Azure from -custom client applications. The local proxy forwards traffic to the Teleport -Application Service, which uses an Azure managed identity to fetch an -authentication token from Azure. - -```code -$ tsh proxy azure [] -``` - -The command will print the address of the local proxy server along with `export` -commands for environment variables required to connect: - -```text -Started Azure proxy on http://127.0.0.1:54330. -To avoid port randomization, you can choose the listening port using the --port flag. - -Use the following credentials and HTTPS proxy setting to connect to the proxy: - - export AZURE_CONFIG_DIR=/Users/myuser/.tsh/azure/my.teleport.cluster/azure - export HTTPS_PROXY=http://127.0.0.1:54330 - export HTTP_PROXY=http://127.0.0.1:54330 - export MSI_ENDPOINT=https://azure-msi.teleport.dev/eedfd5b55257c0aaa58f - export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem -``` - - - -`tsh proxy azure` runs the local proxy in the foreground, so don't interrupt -the process or exit the terminal where you ran the command until you're ready -to close the local proxy. - - - -Copy the `export` commands and paste them into a second terminal. - -To run the local proxy server, one of the user's roles must include the -`spec.allow.azure_identities` field with one of the identities used by the -Application Service. To learn how to set up secure access to Azure via -Teleport, read [Protect the Azure CLI with Teleport Application -Access](../application-access/cloud-apis/azure.mdx). - -#### Arguments - -This command does not accept any arguments. - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--app` | none | string | Name of the Teleport application representing Azure (i.e., based on `tsh apps ls`). Use this flag if your Teleport user has access to multiple Azure applications. | -| `--port` | none | port number | The port on `localhost` where the local proxy will listen for connections. | -| `--format` | `powershell` if on Windows, `unix` otherwise | `text`, `unix`, `command-prompt`, or `powershell` | The format to use for listing environment variables for Azure client applications connecting to the local proxy. | - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -### tsh proxy aws - -Start a local proxy for AWS access. The user must already be logged in to at -least one AWS application via Teleport before the proxy can start. - -```code -$ tsh proxy aws [] -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--app` | Currently logged in AWS app | string | Optional name of the AWS application (as shown in `tsh apps ls`) to use if logged in to multiple | -| `-p`, `--port` | none | port number | Specify the source port for the local proxy | -| `-e`, `--endpoint-url` | HTTP Proxy | Endpoint URL | Run the local proxy to serve as an AWS endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. | -| `-f`, `--format` | unix | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the AWS proxy | - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -#### Examples - -```code -# Proxy a connection to AWS with the default settings -$ tsh apps login awsapp -$ tsh proxy aws -# Set env variables from output -$ aws s3 ls - -# Proxying connections to AWS on 127.0.0.1:10700 to app awsapp2 -$ tsh apps logins awsapp2 -$ tsh proxy aws --port=10700 --app=awsapp2 -# Set env variables from output -$ aws s3 ls -``` - -### tsh proxy gcloud - -Start a local proxy for Google Cloud API access. The user must already be logged -in to at least one Google Cloud application via Teleport before the proxy can -start. - -```code -$ tsh proxy gcloud [] -``` - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--app` | Currently logged in Google Cloud app | string | Optional name of the Google Cloud application (as shown in `tsh apps ls`) to use if logged in to multiple | -| `-p`, `--port` | none | port number | Specify the source port for the local proxy | -| `-e`, `--endpoint-url` | HTTP Proxy | Endpoint URL | Run the local proxy to serve as a Google Cloud endpoint URL. If not specified, the local proxy serves as an HTTPS proxy. | -| `-f`, `--format` | unix | `text`, `unix`, `command-prompt`, or `powershell` | Optional format for printing environment variables for the Google Cloud proxy | - -#### [Global Flags](#tsh-global-flags) - -These flags are available for all commands `--login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format`. -Run `tsh help ` or see the [Global Flags Section](#tsh-global-flags) - -#### Examples - -```code -$ tsh apps login google-cloud-app -$ tsh proxy gcloud -# Set env variables from output -$ gcloud compute instances list -$ gsutil ls -``` - -### tsh scp - -Copies files from source to dest: - -```code -$ tsh scp [] ... -``` - -{/* TODO Confirm which flags are supported and whether supports multiple sources */} - -#### Arguments - -- `` - filepath to copy -- `` - target destination - -#### Flags - -| Name | Default Value(s) | Allowed Value(s) | Description | -| - | - | - | - | -| `--cluster` | none | a cluster_name | Specify the cluster to connect | -| `-r, --recursive` | none | none | Recursive copy of subdirectories | -| `-P, --port` | none | port number | Port to connect to on the remote host | -| `-q, --quiet` | none | none | Quiet mode | - -#### Global flags - -These flags are available for all commands `--login`, `--proxy`, `--user`, `--ttl`, `--identity`, `--cert-format`, `--insecure`, `--auth`, `--skip-version-check`, `--debug`, `--jumphost`. -Run `tsh help ` or see the [Global Flags section](#tsh-global-flags). - -#### Examples - -```code -$ tsh --proxy=proxy.example.com scp example.txt user@host:/destination/dir -``` - - - `tsh scp` will not work from the CLI if the user requires session moderation. You can transfer files in a moderated session by joining the SSH session from the Web UI and requesting the file transfer there. Both the session initiator and moderators must be present in the Web UI in order to approve the file transfer request. - - -### tsh ls - -List cluster nodes: - -```code -$ tsh ls [] [