Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Edit tctl instructions to clarify remote login
Browse files Browse the repository at this point in the history
Backports #12525

* Edit tctl instructions to clarify remote login

Closes #11464

- Ensure that all example tctl commands are accompanied either by
  instructions to log in to the cluster or the tctl.mdx partial.

- Edit the guides in the Architecture section to remove notes that
tctl can only be used locally to the Auth Service.

- Edit the user-client-rereqs partial to mention tctl for all
  editions, since you can log in to tctl remotely for all editions.

Not editing guides where:

- tctl is run via kubectl exec
- tctl is not mentioned in a code block, i.e., only in passing, and
  a reader isn't expected to run the command on their own while
  following the guide.
- The user is already expected to run tctl on the Auth Service. The
  docker-compose Getting Started guide is an example of this.

* Respond to PR feedback

- Provide more context on authenticating with tctl in the CLI reference
- Update the link to more information re: tctl in the architecture
  overview, and indicate that tctl users must authenticate.
- Minor tweaks.

* Respond to PR feedback

- Rephrase the authentication paragraph in the Architecture Overview.
ptgott committed Jun 1, 2022
1 parent ed20897 commit 08e2b7d
Showing 24 changed files with 314 additions and 78 deletions.
2 changes: 2 additions & 0 deletions docs/pages/access-controls/guides/per-session-mfa.mdx
Original file line number Diff line number Diff line change
@@ -41,6 +41,8 @@ their on-disk Teleport certificates.

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!docs/pages/includes/tctl.mdx!)

- [WebAuthn configured](webauthn.mdx) on this cluster
- Second factor hardware device, such as YubiKey or SoloKey
- A Web browser with [WebAuthn support](
19 changes: 18 additions & 1 deletion docs/pages/access-controls/reference.mdx
Original file line number Diff line number Diff line change
@@ -4,7 +4,8 @@ description: Access Controls reference documentation for role options and proper
h1: Teleport Access Controls Reference
---

This document describes Teleport Roles, Role Options, and Role-Based Access Control (RBAC) for Teleport Access Controls.
This guide shows you how to use Teleport roles to manage role-based access
controls (RBAC) in your Teleport cluster.

## Roles

@@ -33,10 +34,26 @@ To manage cluster roles, a Teleport administrator can use the Web UI or the
command line using [tctl resource commands](../setup/reference/resources.mdx).
To see the list of roles in a Teleport cluster, an administrator can execute:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your cluster with tsh so you can use tctl.
# You can also run tctl on your Auth Service host.
$ tsh login --user=myuser --proxy=teleport.example.com
$ tctl get roles
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your cluster with tsh so you can use tctl.
$ tsh login --user=myuser --proxy=mytenant.teleport.sh
$ tctl get roles
```

</ScopedBlock>

(!docs/pages/includes/backup-warning.mdx!)

A role definition looks like this:
5 changes: 4 additions & 1 deletion docs/pages/application-access/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -23,7 +23,10 @@ Let's connect to Grafana using Teleport Application Access in three steps:

## Prerequisites

- The Teleport Auth Service and Proxy Service, deployed on your own infrastructure or via Teleport Cloud.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!docs/pages/includes/tctl.mdx!)

- A Docker installation, which we will use to launch Grafana in a container. Alternatively, if you have another web application you'd like to protect with Application Access, you can use that instead.
- A host where you will run the Teleport Application Service.

17 changes: 17 additions & 0 deletions docs/pages/application-access/guides/dynamic-registration.mdx
Original file line number Diff line number Diff line change
@@ -82,10 +82,27 @@ version: v5

To create an application resource, run:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl create app.yaml
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
$ tctl create app.yaml
```

</ScopedBlock>


After the resource has been created, it will appear among the list of available
apps (in `tsh app ls` or UI) as long as at least one application agent picks it
up according to its label selectors.
25 changes: 25 additions & 0 deletions docs/pages/application-access/reference.mdx
Original file line number Diff line number Diff line change
@@ -94,6 +94,31 @@ spec:
period: 1m0s
```

You can create a new `app` resource by running the following commands, which
assume that you have created a YAML file called `app.yaml` with your configuration:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create the resource
$ tctl create -f app.yaml
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# Create the resource.
$ tctl create -f app.yaml
```

</ScopedBlock>

## CLI

This section shows CLI commands relevant for Application Access.
25 changes: 10 additions & 15 deletions docs/pages/architecture/overview.mdx
Original file line number Diff line number Diff line change
@@ -109,13 +109,6 @@ steps are explained in detail below the diagram.

![Teleport Everything](../../img/everything.svg)

<Admonition
type="note"
title="Caution"
>
The Teleport Admin tool, `tctl`, must be physically present on the same machine where Teleport Auth is running. Adding new nodes or inviting new users to the cluster is only possible using this tool.
</Admonition>

### 1: Initiate client connection

![Client offers certificate](../../img/client_initiate.svg)
@@ -215,7 +208,7 @@ Finally, the client is authorized to create an SSH connection to a node.
Teleport offers two command-line tools. `tsh` is a client tool used by the end
users, while `tctl` is used for cluster administration.

### TSH
### `tsh`

`tsh` is similar in nature to OpenSSH `ssh` or `scp`. It has
subcommands named after them so you can call:
@@ -234,16 +227,18 @@ valid for 12 hours by default, unless you specify another interval via the

You can learn more about `tsh` in the [User Manual](../server-access/guides/tsh.mdx).

### TCTL
### `tctl`

`tctl` is used to administer a Teleport cluster. It connects to the Auth
server listening on `127.0.0.1` and allows a cluster administrator to manage
nodes and users in the cluster.
`tctl` is used to administer a Teleport cluster. It connects to the Teleport
Auth Service and allows an administrator to manage Nodes, users, and other
resources in the cluster.

`tctl` is also a tool that can be used to modify the dynamic configuration of
the cluster, like creating new user roles or connecting trusted clusters.
You can run `tctl` commands either remotely or on the Teleport Auth Service
host. When run remotely, `tctl` requires that the user authenticate to the
cluster. When run on the Auth Service host, `tctl` uses the identity of the Auth
Service itself, and does not require additional authentication.

You can learn more about `tctl` in the [Admin Manual](../setup/admin.mdx).
You can learn more about `tctl` in the [CLI Reference](../setup/reference/cli.mdx#tctl).

## Next steps

8 changes: 0 additions & 8 deletions docs/pages/architecture/users.mdx
Original file line number Diff line number Diff line change
@@ -4,10 +4,6 @@ description: This chapter explains the concept of a Teleport User and how it's d
h1: Teleport Users
---

{
/* TODO: This doc is incomplete, pending addition of Enterprise topics */
}

## Types of users

Unlike traditional SSH, Teleport introduces the concept of a User Account. A User Account is not the same as SSH login. Instead, each Teleport User is associated with another account which is used to authenticate the user.
@@ -33,10 +29,6 @@ Let's look at this table:
| juliet | juliet | Teleport user `juliet` can log in into member nodes only as OS user `juliet`. |
| ross | | If no OS login is specified, it defaults to the same name as the Teleport user, here this is `ross`. |

To add a new user to Teleport, you have to use the `tctl` tool on the same node
where the auth server is running, i.e. `teleport` was started with
`--roles=auth` .

A cluster administrator must create account entries for every Teleport user with
[`tctl users add`](../setup/reference/cli.mdx). Every Teleport User must be associated with a list of one or more machine-level OS usernames it can authenticate as during a login. This list is called "user mappings".

18 changes: 5 additions & 13 deletions docs/pages/database-access/guides/gui-clients.mdx
Original file line number Diff line number Diff line change
@@ -18,11 +18,9 @@ Ensure that your environment includes the following:
- A running Teleport cluster. For details on how to set this up, see one of our
[Getting Started](/docs/getting-started) guides.

- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).
- The `tsh` client tool version >= (=teleport.version=).

```code
$ tctl version
# Teleport v(=teleport.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=teleport.version=) go(=teleport.golang=)
```
@@ -36,14 +34,11 @@ Ensure that your environment includes the following:
- A running Teleport cluster. For details on how to set this up, see our Enterprise
[Getting Started](/docs/enterprise/getting-started) guide.

- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
which you can download by visiting the
- The `tsh` client tool version >= (=teleport.version=), which you can download
by visiting the
[customer portal](https://dashboard.gravitational.com/web/login).

```code
$ tctl version
# Teleport v(=teleport.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=teleport.version=) go(=teleport.golang=)
```
@@ -55,13 +50,10 @@ Ensure that your environment includes the following:
- A Teleport Cloud account. If you do not have one, visit the
[sign up page](https://goteleport.com/signup/) to begin your free trial.

- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=).
To download these tools, visit the [Downloads](/docs/cloud/downloads) page.
- The `tsh` client tool version >= (=cloud.version=). To download these tools,
visit the [Downloads](/docs/cloud/downloads) page.

```code
$ tctl version
# Teleport v(=cloud.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=cloud.version=) go(=teleport.golang=)
```
11 changes: 10 additions & 1 deletion docs/pages/database-access/guides/redis-cluster.mdx
Original file line number Diff line number Diff line change
@@ -31,10 +31,19 @@ This guide will help you to:

## Prerequisites

- Teleport version `9.0` or newer.
- Redis version `6.0` or newer.

- `redis-cli` installed and added to your system's `PATH` environment variable.

- A host where you will run the Teleport Database Service. Teleport version 9.0
or newer must be installed.

See [Installation](../../installation.mdx) for details.

(!docs/pages/includes/user-client-prereqs.mdx!)

(!docs/pages/includes/tctl.mdx!)

<Admonition type="note" title="Note">
Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported.
</Admonition>
14 changes: 14 additions & 0 deletions docs/pages/database-access/reference/cli.mdx
Original file line number Diff line number Diff line change
@@ -3,6 +3,20 @@ title: Database Access CLI Reference
description: CLI reference for Teleport Database Access.
---

This reference shows you how to run common commands for managing Teleport
Database Access, including:

- The `teleport` daemon command, which is executed on the host where you
will run the Teleport Database Service.

- The `tctl` administration tool, which you use to manage `db` resources that
represent databases known to your Teleport cluster.

(!docs/pages/includes/tctl.mdx!)

- The `tsh` client tool, which end-users run in order to access databases in
your cluster.

## teleport db start

Starts Teleport Database Service agent.
25 changes: 25 additions & 0 deletions docs/pages/database-access/reference/configuration.mdx
Original file line number Diff line number Diff line change
@@ -164,3 +164,28 @@ spec:
command: ["hostname"]
period: 1m0s
```

You can create a new `db` resource by running the following commands, which
assume that you have created a YAML file called `db.yaml` with your configuration:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create the resource
$ tctl create -f db.yaml
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# Create the resource
$ tctl create -f db.yaml
```

</ScopedBlock>
4 changes: 4 additions & 0 deletions docs/pages/desktop-access/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -30,6 +30,10 @@ This guide requires you to have:

You can reuse an existing server running any other Teleport instance.

- The `tctl` administration tool version >= (=teleport.version=)

(!docs/pages/includes/tctl.mdx!)

## Step 1/7. Create a restrictive service account

Teleport requires a service account to connect to your Active Directory domain.
4 changes: 3 additions & 1 deletion docs/pages/desktop-access/reference/cli.mdx
Original file line number Diff line number Diff line change
@@ -3,7 +3,9 @@ title: Desktop Access CLI Reference
description: CLI reference for Teleport Desktop Access.
---

# Desktop Access CLI Reference
The following `tctl` commands are used to manage Teleport Desktop Access.

(!docs/pages/includes/tctl.mdx!)

Generate a join token for a Windows Desktop Service:

22 changes: 21 additions & 1 deletion docs/pages/desktop-access/troubleshooting.mdx
Original file line number Diff line number Diff line change
@@ -45,7 +45,27 @@ This means that the host does not trust the Teleport CA.
First, make sure that you [import the Teleport CA into Group
Policy](./getting-started.mdx#create-another-gpo-and-import-the-teleport-ca). Note that if the
Teleport CA was rotated since the last import, you will have to fetch the
new CA using `tctl auth export --type=windows >user-ca.cer`
new CA using the following command:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl auth export --type=windows >user-ca.cer
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
$ tctl auth export --type=windows >user-ca.cer
```

</ScopedBlock>

If that doesn't help, log into the target host directly, open PowerShell and
run `gpupdate.exe /force`. This forces a Group Policy sync and should pick up
6 changes: 6 additions & 0 deletions docs/pages/enterprise/hsm.mdx
Original file line number Diff line number Diff line change
@@ -9,7 +9,13 @@ This guide will show you how to set up the Teleport Auth Server to use a hardwar
## Prerequisites

- Teleport v(=teleport.version=) Enterprise (self-hosted).

- The `tctl` administration tool version >= (=teleport.version=).

(!docs/pages/includes/tctl.mdx!)

- An HSM reachable from your Teleport auth server.

- The PKCS#11 module for your HSM.

<Details scope={["cloud", "oss"]} opened={true} scopeOnly={true} title="Compabitility Warning">
18 changes: 17 additions & 1 deletion docs/pages/enterprise/sso/oidc.mdx
Original file line number Diff line number Diff line change
@@ -66,10 +66,26 @@ the `user` role depending on the value returned for `group` within the claims.

Create the connector:

```bsh
<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl create oidc-connector.yaml
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
$ tctl create oidc-connector.yaml
```

</ScopedBlock>

## Create Teleport Roles

The next step is to define Teleport roles. They are created using the same
1 change: 1 addition & 0 deletions docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx
Original file line number Diff line number Diff line change
@@ -34,6 +34,7 @@ This guide assumes that you have:

Teleport Cloud requires that plugins connect through the Proxy Service (`mytenant.teleport.sh:443`). Open Source and Enterprise installations can connect to the Auth Service (`auth.example.com:3025`) directly.

(!docs/pages/includes/tctl.mdx!)

### Setting up Mattermost to work with the bot

1 change: 1 addition & 0 deletions docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx
Original file line number Diff line number Diff line change
@@ -23,6 +23,7 @@ This guide assumes that you have:

Teleport Cloud requires that plugins connect through the Proxy Service (`mytenant.teleport.sh:443`). Open Source and Enterprise installations can connect to the Auth Service (`auth.example.com:3025`) directly.

(!docs/pages/includes/tctl.mdx!)

### Create a user and role for access

12 changes: 9 additions & 3 deletions docs/pages/includes/user-client-prereqs.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
<Tabs>
<TabItem scope={["oss"]} label="Open Source">

- The `tsh` client tool version >= (=teleport.version=).
- The `tctl` and `tsh` client tools version >= (=teleport.version=).

```code
$ tctl version
# Teleport v(=teleport.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=teleport.version=) go(=teleport.golang=)
```
@@ -18,11 +21,14 @@
<TabItem
scope={["enterprise"]} label="Enterprise">

- The `tsh` client tool version >= (=teleport.version=), which you can download
by visiting the
- The `tctl` and `tsh` client tools version >= (=teleport.version=), which you
can download by visiting the
[customer portal](https://dashboard.gravitational.com/web/login).

```code
$ tctl version
# Teleport v(=teleport.version=) go(=teleport.golang=)
$ tsh version
# Teleport v(=teleport.version=) go(=teleport.golang=)
```
16 changes: 16 additions & 0 deletions docs/pages/kubernetes-access/controls.mdx
Original file line number Diff line number Diff line change
@@ -120,10 +120,26 @@ spec:

Create or update this role using `tctl`:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl create -f member.yaml
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
$ tctl create -f member.yaml
```

</ScopedBlock>

Assign this role to a user in OIDC or SAML connector:

<Tabs>
23 changes: 22 additions & 1 deletion docs/pages/kubernetes-access/guides/cicd.mdx
Original file line number Diff line number Diff line change
@@ -40,14 +40,35 @@ spec:
Generate a `kubeconfig` using the `jenkins` user and its roles using [`tctl auth sign`](../../setup/reference/cli.mdx#tctl-auth-sign):

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
# Create a new local user for Jenkins
$ tctl users add jenkins --roles=robot
# Creates a token for 25hrs
$ tctl auth sign --user=jenkins --format=kubernetes --out=kubeconfig --ttl=25h
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
# Create a new local user for Jenkins
$ tctl users add jenkins --roles=robot
# Creates a token for 25hrs
$ tctl auth sign --user=jenkins --format=kubernetes --out=kubeconfig --ttl=25h
```

</ScopedBlock>

# The credentials have been written to kubeconfig
Verify that these credentials have been written to kubeconfig:

```code
$ cat kubeconfig
# apiVersion: v1
# clusters:
8 changes: 4 additions & 4 deletions docs/pages/machine-id/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -15,11 +15,11 @@ Here's an overview of what you will do:

## Prerequisites

Before using Machine ID, you will need an existing Teleport cluster or a
Teleport Cloud account.
- A host that you wish to assign an identity to using Machine ID.

If you have not set up a Teleport cluster before, follow the
[Getting started](https://goteleport.com/docs/getting-started) guide.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!/docs/pages/includes/tctl.mdx!)

<Admonition type="note" title="Machine ID and TLS Routing">
TLS Routing support will be added to Machine ID in [Teleport
16 changes: 16 additions & 0 deletions docs/pages/setup/guides/ssh-key-extensions.mdx
Original file line number Diff line number Diff line change
@@ -15,10 +15,26 @@ Teleport supports exporting user SSH certificates with configurable key extensio

In order to export the Teleport CA, execute the following command:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
# You can also run tctl on your Auth Service host.
$ tsh login --proxy=teleport.example.com --user=myuser
$ tctl auth export --type=user | sed 's/^cert-authority //g'
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your Teleport cluster so you can use tctl remotely.
$ tsh login --proxy=mytenant.teleport.sh --user=myuser
$ tctl auth export --type=user | sed 's/^cert-authority //g'
```

</ScopedBlock>

Next, follow the instructions in the guide below to import your Teleport CA into GitHub:

[Managing your organization's SSH certificate authorities](https://docs.github.com/en/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)
92 changes: 64 additions & 28 deletions docs/pages/setup/reference/cli.mdx
Original file line number Diff line number Diff line change
@@ -704,53 +704,89 @@ creating new user roles or connecting Trusted Clusters.
<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

By default, `tctl` connects to a local Auth Service, meaning that it will fail
if you attempt to run `tctl` on a non-`auth` host.
When running `tctl` commands, administrators must authenticate to a Teleport
cluster. This can be done in three ways:

`tctl` can also connect to a remote Auth Service if the `--identity` and
`--auth-server` flags are used. An identity file for use with `--identity`
can be exported with `tctl auth sign` or `tsh login --out=<output-path>`.
### On a remote host with an identity file

`tctl` can authenticate with a user-provided identity file. The Teleport Auth
Service signs an identity file when a user runs `tctl auth sign` or
`tsh login --out=<output-path>`, and the user can include the path to the
identity file in the `--identity` flag when running `tctl` commands.

When using the `--identity` flag, the user must provide the `--auth-server` flag
with the address of an Auth Service or Proxy Service so `tctl` knows which
cluster to authenticate to.

### On the same host as the Teleport Auth Service

If there is a Teleport configuration file on the host where `tctl` is run,
`tctl` attempts to authenticate to the Auth Service named in the configuration
file using an identity stored in its local backend.

`tctl` only authenticates using this method if an identity file is not provided.

<Admonition type="note">

Note that when a `tctl` command is run locally on an Auth Service, the audit
Note that when a `tctl` command is run locally on the Auth Service, the audit
logs will show that it was performed by the Auth Service itself.

To properly audit admin actions at scale, it is important to limit direct SSH
access to the Auth Service with
To provide an accurate audit trail, it is important to limit direct SSH access
to the Auth Service with
[Access Controls](../../access-controls/introduction.mdx) and ensure that
admins use `tctl` remotely with the `--identity` flag instead.
admins use `tctl` remotely instead.

</Admonition>

The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport
configuration file is.
### On a remote host after running `tsh login`

If `tctl` cannot find a local Teleport configuration file or a user-provided
identity file, it attempts to load the user's `tsh` profile to authenticate to
the cluster. The `tsh` profile is created when a user runs `tsh login`.

If you're connecting to a remote Teleport cluster through a `tsh` session and
have a file named `/etc/teleport.yaml` on your machine set the `TELEPORT_CONFIG_FILE`
to `""`. Otherwise `tctl` will attempt to connect to a Teleport cluster on the
machine, which could result in the error,
`tctl` reads the `TELEPORT_CONFIG_FILE` environment variable to determine if
a Teleport configuration file is present. If you are using your `tsh` profile to
authenticate `tctl`, you must ensure that one of these conditions is true:

- `TELEPORT_CONFIG_FILE` is blank
- No file exists at `/etc/teleport.yaml`

Otherwise `tctl` will attempt to connect to a Teleport cluster on the machine,
which could result in the error,
`ERROR: open /var/lib/teleport/host_uuid: permission denied`.

</TabItem>
<TabItem scope={["cloud"]} label="Teleport Cloud">

You will need to download the Enterprise version of Teleport from the
[customer portal](https://dashboard.gravitational.com/web/login) to run `tctl`
commands in Teleport Cloud.
When running `tctl` commands, administrators must authenticate to a Teleport
cluster. This can be done in two ways:

You must log in to your cluster before you can run `tctl` commands.
```code
$ tsh login --proxy=mytenant.teleport.sh
$ tctl status
```
### On a remote host with an identity file

`tctl` can authenticate with a user-provided identity file. The Teleport Auth
Service signs an identity file when a user runs `tctl auth sign` or
`tsh login --out=<output-path>`, and the user can include the path to the
identity file in the `--identity` flag when running `tctl` commands.

When using the `--identity` flag, the user must alo provide the `--auth-server`
flag with the address of an Auth Service or Proxy Service so `tctl` knows which
cluster to authenticate to.

### On a remote host after running `tsh login`

If `tctl` cannot find a local Teleport configuration file or a user-provided
identity file, it attempts to load the user's `tsh` profile to authenticate to
the cluster. The `tsh` profile is created when a user runs `tsh login`.

`tctl` reads the `TELEPORT_CONFIG_FILE` environment variable to determine if
a Teleport configuration file is present. If you are using your `tsh` profile to
authenticate `tctl`, you must ensure that one of these conditions is true:

The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport
configuration file is.
- `TELEPORT_CONFIG_FILE` is blank
- No file exists at `/etc/teleport.yaml`

If you have a file named `/etc/teleport.yaml` on your local machine, set the
`TELEPORT_CONFIG_FILE` to `""`. Otherwise `tctl` will attempt to connect to a
Teleport cluster on the machine, which could result in the error,
Otherwise `tctl` will attempt to connect to a Teleport cluster on the machine,
which could result in the error,
`ERROR: open /var/lib/teleport/host_uuid: permission denied`.

</TabItem>

0 comments on commit 08e2b7d

Please sign in to comment.