Teleport

Labels

OpenSource
Enterprise
Cloud

Teleport allows you to add arbitrary key-value pairs to applications, servers, databases, and other resources in your cluster. You can use these to filter resources when making queries via tctl and tsh as well as to limit the resources that Teleport roles can access.

This guide explains how to add labels to Teleport resources.

There are two kinds of labels:

Static labels

Static labels are hardcoded in a teleport daemon's configuration file and do not change over time while the teleport process is running. An example of a static label is a Node's environment, e.g., staging vs. production.

Dynamic labels

Dynamic labels, also known as label commands, allow you to generate labels at runtime. The teleport daemon will execute an external command on its host at a configurable frequency and the output of the command becomes the label's value.

This is especially useful for decoupling the label's value from your Teleport configuration. For example, if you start Teleport on an Amazon EC2 instance, you can set a region label based on a command that sends a request to the EC2 instance metadata API. This means that you can keep your configuration the same for each Node (and set the configuration within an Amazon Machine Image) while enabling users to search for Nodes by AWS region.

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 12.1.1.
```
tctl version
Teleport v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```
See Installation for details.

A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.
```
tctl version
Teleport Enterprise v12.1.1 go1.19
tsh version
Teleport v12.1.1 go1.19
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  12.1.1
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  12.1.1
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

A host where you will run a Teleport Node. In this guide, we will apply labels to this Node.

Resources you can label

You can label any resource managed by Teleport using the instructions in this guide. See the following guides for how to add resources to a Teleport cluster:

Guide	Notes on labeling
Applications
Databases	Teleport can discover some AWS-hosted databases automatically. In this case, labels will also be automatically applied.
Kubernetes clusters
Servers
Windows desktops	Dynamic labels are not supported for Windows desktops. See our Desktop Access documentation for how to label desktops.

Step 1/3. Prepare your Node

Install Teleport on your Node

On the host where you will run your Teleport Node, follow the instructions for your environment to install Teleport.

Use the appropriate commands for your environment to install your package.

Teleport Edition

Add the Teleport repository to your repository list:

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

Generate a token

On your local machine, use the tctl tool to generate an invite token that your Node will use to join the cluster. In the following example, a new token is created with a TTL of five minutes:

Generate a short-lived invitation token for a new node:
tctl nodes add --ttl=5m --roles=node
The invite token: abcd123-insecure-do-not-use-this
You can also list all generated non-expired tokens:
tctl tokens ls
Token                            Type            Expiry Time
------------------------         -----------     ---------------
abcd123-insecure-do-not-use-this         Node            25 Sep 18 00:21 UTC

Copy the token. On the remote host that you will add to your Teleport cluster as a Node, assign the token to an environment variable:

export INVITE_TOKEN=<token>

We will use this in the next step.

Step 2/3. Apply a static label to your Node

You can configure Node labels by editing Teleport's configuration file, then starting Teleport.

On the host where you will run your Node, paste the following content into /etc/teleport.yaml and adjust it for your environment:

version: v3
teleport:
  # The address of your Auth Service.
  auth_server: tele.example.com:3025
  # Or, you can also use a Proxy Service
  # address, e.g., tele.example.com:443, if your Auth Service is not
  # exposed to the internet.
  proxy_server: tele.example.com:443

auth_service:
  enabled: false

proxy_service:
  enabled: false

ssh_service:
  enabled: true
  # Static labels are simple key/value pairs:
  labels:
    environment: dev

Next, start Teleport with the invite token you created earlier:

sudo teleport start --token=${INVITE_TOKEN?}

Verify that you have added the label by running the following on your local machine. Your Teleport user must be authorized to access the Node.

tsh ls --query 'labels["environment"]=="dev"'
Node Name    Address    Labels
------------ ---------- ---------------
bdcb47b87ad6 ⟵ Tunnel environment=dev

First, check the logs for your Node to ensure the SSH Service is running. Your logs should resemble the following:

2022-04-27T14:44:23Z INFO [NODE:1]    Service is starting in tunnel mode. service/service.go:1993
2022-04-27T14:44:23Z INFO [PROC:1]    The new service has started successfully. Starting syncing rotation status with period 10m0s. service/connect.go:482
2022-04-27T14:44:23Z INFO             Service has started successfully. service/service.go:523
2022-04-27T14:44:24Z INFO [NODE:PROX] Connected. addr:172.17.0.2:40184 remote-addr:192.0.2.0:443 leaseID:1 target:teleport.example.com:443 reversetunnel/agent.go:409

Next, ensure that your Teleport user has a login that corresponds to a user on your Node.

Run the following command to get the current logins for your user:

tsh status
> Profile URL:        https://teleport.example.com:443
  Logged in as:       myuser
  Cluster:            teleport.example.com
  Roles:              access, editor
  Logins:             -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe
  Kubernetes:         enabled
  Valid until:        2022-04-27 22:26:50 -0400 EDT [valid for 11h40m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

In this example, -teleport-nologin-d4bc1dad-ce49-4bbe-925d-a67f8d2d6afe means that no logins have been assigned to the user.

To add logins, retrieve your user configuration as YAML:

Replace "myuser" with your Teleport username
tctl get user/myuser > user.yaml

Edit the logins field for your user. Each login must exist as a user on the host:

     db_users: null
     kubernetes_groups: null
     kubernetes_users: null
-    logins: null
+    logins:
+      - root
     windows_logins: null
 version: v2

Apply your changes:

tctl create -f user.yaml
user "myuser" has been updated

Log out of your cluster, then log in again. You should now see your Node when you run tsh ls.

If you wish to use labels for RBAC purposes but don't want to see the labels in the UI, you can put them in the hidden namespace by prefixing the label's key with teleport.hidden/, for example teleport.hidden/account-id.

Step 3/3. Apply dynamic labels via commands

Before following this step, stop Teleport on your Node.

As with static labels, you can apply dynamic labels by editing the Teleport configuration file.

Edit /etc/teleport.yaml to define a commands array as shown below:

version: v3
teleport:
  auth_server: tele.example.com:3025

auth_service:
  enabled: false

proxy_service:
  enabled: false

ssh_service:
  enabled: "yes"
  # Configure dynamic labels using the "commands" field:
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
  - name: arch
    command: [uname, -p]
    # This setting tells Teleport to execute the command above
    # once an hour. This value cannot be less than one minute.
    period: 1h0m0s

Notice that the command setting is an array where the first element is a valid executable and each subsequent element is an argument.

This is valid syntax:

command: ["/bin/uname", "-m"]

This is invalid syntax:

command: ["/bin/uname -m"]

If you want to pipe several bash commands together, here's how to do it. Notice how ' and " are interchangeable, so you can use them for nested quotations.

command: ["/bin/sh", "-c", "uname -a | egrep -o '[0-9]+\\.[0-9]+\\.[0-9]+'"]

When configuring a command to generate dynamic labels, the executable named within your command must be the path to a valid file. The executable permission bit must be set and shell scripts must have a shebang line.

Once you have configured your labels, start Teleport with the invite token you created earlier:

sudo teleport start --token=${INVITE_TOKEN?}

Verify that you have added the labels by running the following on your local machine. Your Teleport user must be authorized to access the Node.

tsh ls
Node Name         Address    Labels
----------------- ---------- ---------------
ip-192-0-2-0      ⟵ Tunnel arch=x86_64,hostname=ip-172-30-156-233

Try creating another invite token using the tctl nodes add command from earlier and starting your Node again.

If this doesn't work, delete the directory your Node uses to maintain its state, /var/lib/teleport, and try again.

Next steps: Using labels

Once you have labeled your resources, you can refer to your labels when running tsh and tctl commands to filter the resources that the commands will query. For more information, see Resource filtering.

You can also use labels to limit the access that different roles have to specific classes of resources. For more information, see Teleport Role Templates.

Have a suggestion or can’t find something?

IMPROVE THE DOCS