teleport/docs/pages/management/admin/adding-nodes.mdx

---
title: Adding Nodes to your Cluster
description: How to add Nodes to your Teleport cluster
---

This guide explains how to add Teleport Nodes to your cluster.

## Prerequisites

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

- A Linux server that you will use to host your Teleport Node.

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

## Step 1/3. Install Teleport on your Node

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

(!docs/pages/includes/install-linux.mdx!)

## Step 2/3. Join your Node to the cluster

In this section, we will join your Node to the Teleport cluster by:

- Obtaining information stored on the Auth Service
- Starting Teleport on your Node with the information we obtained

### Obtain a CA pin

In a zero-trust environment, you must assume that an attacker can hijack the IP
address of the Auth Service.

To prevent this from happening, you need to supply every new Node with
information about the Auth Service. This technique is called **CA pinning**. It
works by asking the Auth Service to produce a CA pin, a hash value of the SPKI
header in a certificate. This way, an attacker cannot easily forge a matching
private key.

If a CA pin is not provided, the Teleport Node will join a cluster but it will
print a warning message.

<Notice type="warning">

The CA pin becomes invalid if a Teleport administrator performs the CA rotation
by executing [`tctl auth rotate`](../../reference/cli.mdx#tctl-auth-rotate).
    
</Notice>

On you local machine, retrieve the CA pin of the Auth Service <ScopedBlock
scope="cloud"> by running the following command on your local
machine</ScopedBlock>:

```code
$ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}')
```

### Generate a token

Teleport only allows access to Nodes that have joined the cluster.

Once a Node joins, it receives a host certificate signed by the cluster's
Auth Service. To receive a host certificate upon joining a cluster, a new
Teleport host must present an **invite token**.

An invite token also defines which role a new host can assume within a cluster:

- `proxy`
- `node`
- `auth`
- `app`
- `db`
- `kube`
- `windowsdesktop`

Administrators can generate tokens as they are needed. A token can be used
multiple times until its time to live (TTL) expires.

On your local machine, use the `tctl` tool to generate a new token. In the
following example, a new token is created with a TTL of five minutes:

```code
# Generate a short-lived invite token for a new node:
$ export INVITE_TOKEN=$(tctl nodes add --ttl=5m --roles=node | grep "invite token:" | grep -Eo "[0-9a-z]{32}")
$ echo $INVITE_TOKEN
# (=presets.tokens.first=)

# You can also list all generated non-expired tokens:
$ tctl tokens ls
# Token                            Type            Expiry Time
# ------------------------         -----------     ---------------
# (=presets.tokens.first=)         Node            25 Sep 18 00:21 UTC
```

<Details title="Provide your own token value">

Rather than automatically generating a token, you can create one with a known
value by using the `--token` flag:

```code
$ tctl nodes add --ttl=5m --roles=node,proxy --token=secret-value
# The invite token: secret-value
```

The value of `--token` should be cryptographically secure. For example, you can
create an SHA256 hash to reduce the risk that a malicious actor will produce
a token with the same value as yours:

```code
$ head -n 1 /dev/random | sha256sum
```

</Details>

<Details scope={["oss","enterprise"]} title="An insecure alternative: static tokens" scopeOnly={false} opened>
<Admonition type="warning">
Use short-lived tokens instead of long-lived static tokens.
Static tokens are easier to steal, guess, and leak.
</Admonition>

Static tokens are defined ahead of time by an administrator and stored in the
auth server's config file:

```yaml
# Config section in `/etc/teleport.yaml` file for the auth server
auth_service:
    enabled: true
    tokens:
    # This static token allows new hosts to join the cluster as "proxy" or "node"
    - "proxy,node:secret-token-value"
    # A token can also be stored in a file. In this example the token for adding
    # new auth servers are stored in /path/to/tokenfile
    - "auth:/path/to/tokenfile"
```
</Details>

### Start your Node with the invite token and CA pin

Execute the following commands on the host where you will run your Node so you
can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport.

```code
$ export CA_PIN=<Var name="ca-pin" />
$ export INVITE_TOKEN=<Var name="invite-token" />
```

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

Still on the host where you will run your Node, assign the address of your Auth
Service to an environment variable, including the domain name (or IP address)
and port:

```code
$ export ADDR=teleport.example.com:3025
```

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

Still on the host where you will run your Node, assign the address of your
Teleport Cloud tenant to an environment variable, including the domain name (or
IP address) and port `443`:

```code
$ export ADDR=mytenant.teleport.sh:443
```

</ScopedBlock>

<Details title="Alternative: Connect to the Proxy Service via Teleport Node Tunneling" scope={["oss", "enterprise"]} scopeOnly opened={false}>

If you plan to use Teleport Node Tunneling, which we will explain below, set
`ADDR` to the domain name (or IP address) and `web_listen_addr` port of your
Teleport Proxy Service.

Teleport Node Tunneling lets you add a remote Node to an existing Teleport
Cluster through a reverse tunnel. This is useful when the Auth Service is
inaccessible from the network where the Node is running, e.g., for IoT
applications.

<Notice type="note">

We recommend setting up a [Trusted Cluster](../admin/trustedclusters.mdx) if you
have workloads split across different networks or clouds.

</Notice>

Using the ports in Teleport's default configuration, the Node needs to be able
to talk to ports `3080` and `3024` on the Proxy Service. Port `3080` is used to
initially fetch the credentials (SSH and TLS certificates) and for discovering
the reverse tunnel. Port `3024 `is used to establish a connection to the Auth
Service through the Proxy.

For those using ACME, port `443` is also required. 

To enable multiplexing so only one port is used, simply set the
`tunnel_listen_addr` to the same value as `web_listen_addr` within the
`proxy_service` section of your configuration file. Teleport will automatically
recognize that the Proxy Service is using the same port for both addresses and
enable multiplexing.

If your log setting is set to DEBUG, you will see multiplexing enabled in the
server log.

```txt
DEBU [PROC:1]    Setup Proxy: Reverse tunnel proxy and web proxy listen on the same port, multiplexing is on. service/service.go:1944
```

<Admonition
  type="tip"
  title="Load Balancers"
>

  The setup above also works even if the cluster uses multiple Proxy Service
  instances behind a load balancer (LB) or a DNS entry with multiple values. In
  this case, the Node establishes a tunnel to every proxy.
  
  This requires that an LB
  uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity") with Teleport Proxy Service instances.
</Admonition>

</Details>

Execute the following command on your Node to add it to a cluster:

```code
$ sudo teleport start \
   --roles=node \
   --token=${INVITE_TOKEN?} \
   --ca-pin=${CA_PIN?} \
   --auth-server=${ADDR?}
```

As new Nodes come online, they start sending ping requests every few seconds to
the Auth Service. This allows users to explore cluster membership and size.

Run the following command on your local machine to see all of the Teleport Nodes
in your cluster:

```code
$ tctl nodes ls

Node Name     Node ID                                  Address            Labels
---------     -------                                  -------            ------
turing        d52527f9-b260-41d0-bb5a-e23b0cfe0f8f     10.1.0.5:3022      distro:ubuntu
dijkstra      c9s93fd9-3333-91d3-9999-c9s93fd98f43     10.1.0.6:3022      distro:debian
```

## Step 3/3. Revoke an invitation

Tokens used for joining Nodes to a cluster can be revoked before they are used.

Run the following command on your local machine to create a token for a new
Proxy Service:

```code
$ tctl nodes add --ttl=5m --roles=proxy 
# The invite token: (=presets.tokens.first=).
# This token will expire in 5 minutes.
# 
# Run this on the new node to join the cluster:
# 
# > teleport start \
#    --roles=proxy \
#    --token=(=presets.tokens.first=) \
#    --ca-pin=(=presets.ca_pin=) \
#    --auth-server=123.123.123.123:3025
# 
# Please note:
# 
#   - This invitation token will expire in 5 minutes
#   - 123.123.123.123 must be reachable from the new node
```

Next, run the following command to see a list of outstanding tokens:

```
$ tctl tokens ls

# Token                                Role       Expiry Time (UTC)
# -----                                ----       -----------------
# (=presets.tokens.first=)     Proxy      never
# (=presets.tokens.second=)     Node       17 May 16 03:51 UTC
# (=presets.tokens.third=)     Signup     17 May 16 04:24 UTC
```

<Admonition type="tip" title="Signup tokens">

The output of `tctl tokens ls` includes tokens used for adding users alongside
tokens used for adding Nodes to your cluster.

</Admonition>

In this example, the first token has a `never` expiry date because it is a
static token configured via a config file.

The token with the `Node` role was generated to invite a new Node to this
cluster. And the third token was generated to invite a new user to sign up.

Tokens created via `tctl` can be deleted (revoked) via the `tctl tokens del`
command. Run the following command to delete a token:

```code
$ tctl tokens del (=presets.tokens.first=)
# Token (=presets.tokens.first=) has been deleted
```