Fork me on GitHub

Teleport

Labels

Improve

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 >= 11.1.0.

    tctl version

    Teleport v11.1.0 go1.19

    tsh version

    Teleport v11.1.0 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 tctl admin tool and tsh client tool version >= 11.1.0, which you can download by visiting the customer portal.

    tctl version

    Teleport v11.1.0 go1.19

    tsh version

    Teleport v11.1.0 go1.19

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 10.3.8. To download these tools, visit the Downloads page.

    tctl version

    Teleport v10.3.8 go1.19

    tsh version

    Teleport v10.3.8 go1.19

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 11.1.0

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 10.3.8

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:

GuideNotes on labeling
Applications
DatabasesTeleport can discover some AWS-hosted databases automatically. In this case, labels will also be automatically applied.
Kubernetes clusters
Servers
Windows desktopsDynamic 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.

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 v11. 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/v11" \ | 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 v11. 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/v11/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: Using DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v11.1.0-linux-amd64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v11.1.0-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v11.1.0-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v11.1.0-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v11.1.0-linux-arm-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v11.1.0-linux-arm-bin.tar.gz
shasum -a 256 teleport-v11.1.0-linux-arm-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v11.1.0-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v11.1.0-linux-arm64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v11.1.0-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v11.1.0-linux-arm64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v11.1.0-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Using this APT repo may result in breaking upgrades upon "apt upgrade" as all major versions will be

published under the same component. We recommend following the instructions in the

"Debian/Ubuntu (DEB)" tab instead.

Download Teleport's PGP public key

sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \ -o /usr/share/keyrings/teleport-archive-keyring.asc

Add the Teleport APT repository

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \ | sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport
sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport

Optional: Using DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

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.

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.