
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 andtsh
client tool version >= 12.1.1.tctl versionTeleport v12.1.1 go1.19
tsh versionTeleport 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 andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
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 statusCluster 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 statusCluster 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.
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.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd 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 teleportTip: 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.gzshasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleportsudo ./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.debSelecting 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.rpmwarning: 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.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleport-entsudo ./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.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
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=nodeThe invite token: abcd123-insecure-do-not-use-this
You can also list all generated non-expired tokens:
tctl tokens lsToken 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.yamluser "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 lsNode 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.