Tailscale Peer Relays

Tailscale Peer Relays are currently in beta.

Tailscale Peer Relays lets you use devices in your Tailscale network (known as a tailnet) as high-throughput relay servers when direct connections aren't possible due to network conditions such as a strict NAT environment.

Normally, Tailscale relies on its globally distributed DERP servers to relay traffic when Tailscale can't establish direct connections between devices. While DERP servers are effective at relaying traffic, they can introduce additional latency, especially for high-throughput applications. When you configure a device as a peer relay, other devices in the same tailnet can use it to relay traffic for client-to-client connections when a direct connection isn't possible. Tailscale first attempts to use any available peer relays in the tailnet before falling back to DERP servers.

Use cases

Peer relays are particularly useful in scenarios where you can't establish direct connections between devices due to network restrictions and you require lower latency and higher throughput than what DERP servers can provide. Common use cases include:

Access restricted infrastructure: Accessing devices behind strict NATs or firewalls where direct connections are not possible, such as in certain corporate or cloud environments.
File transfers: When transferring large files between devices, peer relays can offer higher throughput, speeding up the transfer process.
Media streaming: For streaming high-definition video or audio between devices, peer relays can help maintain a smooth streaming experience with less buffering.

Peer relays are not intended to replace DERP servers. They complement DERP by providing an additional option for relaying traffic within a tailnet, particularly when you require lower latency and higher throughput. DERP servers still play a crucial role in negotiating connections and providing fallback relay options when peer relays are unavailable.

How it works

When you configure a device as a peer relay, it listens for incoming relay traffic on a specified UDP port. Other devices in the tailnet can then use this device to relay traffic for client-to-client connections when direct connections aren't possible.

When a device attempts to connect to another device in the tailnet, it first checks if a direct connection is possible. If not, it looks for available peer relays in the tailnet. If a peer relay is available and accessible, the device establishes a connection through the peer relay. If no peer relays are available, the device falls back to using DERP servers to relay the traffic.

Prerequisites

Before you can use the peer relay feature, ensure you meet the minimum requirements for your Tailscale account and the devices you want to configure as peer relays:

Account requirements

To use the peer relay feature, you must have:

A Tailscale account with access to the tailnet where you want to set up peer relays.
At least one device in the tailnet that meets the peer relay device requirements.
An account with Owner, Admin, or Network admin permissions.

Peer relay device requirements

A device must meet the following requirements to function as a peer relay:

A device running a supported operating system. You can use any operating system other than iOS, Apple TV, or Android.
Tailscale version 1.86 or later.
Sufficient network bandwidth and low latency to effectively relay traffic for other devices.
At least one configurable UDP port you can use for peer relay traffic. This port must be accessible from other devices in the tailnet. Refer to security and access control for more information about configuring network settings.

Other tailnet devices requirements

Devices in the tailnet that use peer relays must meet the following requirements:

Access to the peer relay devices (through applicable access control policies).
Tailscale version 1.86 or later.
Access to the UDP port configured for peer relay traffic on the peer relay devices.

There are no operating system restrictions for devices that use peer relays; they can run any supported Tailscale operating system, including iOS and Apple TV.

Get started

Setting up peer relay functionality in a tailnet involves two primary steps. First, you need to configure a device to act as a peer relay. Then, you need to create a grant policy to permit other devices in the tailnet to use the peer relay

Step 1: Configure a device as a peer relay

To use the peer relay feature for faster relayed connections, you must configure at least one device in the tailnet to function as a peer relay. Only devices that meet the peer relay requirements and that you explicitly designate can act as peer relays.

To set up a device as a peer relay:

On the device you want to configure as a peer relay, start the Tailscale client and authenticate it to your tailnet.
Open a terminal or command prompt on the device.
Use the tailscale set command with the --relay-server-port option to specify the UDP port for peer relay traffic. For example, to configure the device to use UDP port 40000 for peer relay traffic, run the following command:
```
tailscale set --relay-server-port=40000
```

Step 2: Create a peer relay policy

Before devices in the tailnet can use devices you designate as peer relays, you need to create a grant policy that lets them do so. The grant policy uses the tailscale.com/cap/relay application capability to specify which devices can use the peer relay functionality. You can create the grant policy using the admin console's JSON editor, the visual policy editor, or the Tailscale API.

To create a grant that enables peer relay capabilities using the JSON editor:

Open the Access controls page of the admin console.
Select the JSON editor tab to update the tailnet policy file using JSON.
Locate the grants section of the policy file.
Add an policy to the grants section of the policy file that specifies, the src (the device behind a restrictive NAT), the dst (the peer relay device), and the peer-relay application capability. For example, the following example lets all devices with the tag tag:us-east-vpc use peer relays tagged with tag:peer-relay.

{
  "grants": [
    {
      "src": ["tag:us-east-vpc"], // Devices that can be accessed through the peer relay
      "dst": ["tag:us-east-relays"], // Devices functioning as peer relays for the src devices
      "app": {
        "tailscale.com/cap/relay": [] // The relay capability doesn't require any parameters
      }
    }
  ]
}

You can reference peer relay devices using tags, hostname, IP set, or Tailscale IP addresses in the dst field of the access rule. The app field must include the tailscale.com/cap/relay capability to enable peer relay functionality for the specified devices. It does not require any additional parameters.

After you create the peer relay grant policy, devices in the tailnet can start using the peer relay for client-to-client connections when direct connections aren't possible. When a device can't connect directly to another device, it first checks for available peer relays in the tailnet. If no peer relays are available, the device falls back to using DERP servers.

Avoid using overly permissive targets for the src field of the grant policy (such as *). For example, using * would make all devices in the tailnet attempt to use the peer relay devices in the dst, potentially leading to unintended traffic routing and high latency. Instead, specify precise device tags, hostnames, or IP sets to limit which devices can use the peer relay.

As a rule of thumb, the src devices in the grant policy should typically be devices in a stable physical location behind a strict NAT or firewall that prevents direct connections. This typically includes devices in corporate networks or cloud environments. It usually does not include mobile devices or laptops that frequently change locations and network conditions.

Step 3: Observe peer relay traffic

Generate traffic to test the peer relay configuration. Then, use the tailscale status command to monitor the device's status and verify that it is functioning as a peer relay. When a tailnet device uses a peer relay, the connection type of that device changes to peer-relay.

Run the tailscale status command and filter the output for peer-relay entries:

tailscale status | grep peer-relay

When a device is using a peer relay, it returns the device's connection type as peer-relay (instead of direct or relay). For example:

<tailscale-ip-address> <hostname> <user> <os> active; peer-relay <ip-address>:<udp-port>:vni:<vni-id>, tx <bytes-sent> rx <bytes-received>

You can also use the tailscale ping command to test connectivity between devices and observe whether the connection uses a peer relay.

Disable Peer Relay

To disable peer relay for a device use the tailscale set command with the --relay-server-port flag set to an empty string:

tailscale set --relay-server-port=""

Examples

Example scenarios in which you would use Tailscale Peer Relays include:

Accessing devices in a specific geographic region using peer relays located in that region to reduce latency.
Using peer relays to connect to devices behind strict NATs or firewalls where direct connections are not possible.
Setting up dedicated peer relay devices to handle high-throughput traffic for specific applications or services.

The following peer relay policy examples illustrate what the grant policy looks like in different scenarios.

Use tagged peer relay devices

The following example lets all devices with the tag tag:us-east-vpc use peer relay devices tagged with tag:us-east-relays as underlay network relays when communicating with other devices on the tailnet. That means that other devices in the tailnet can use a device tagged with tag:us-east-relays as an underlay network relay when communicating with devices tagged with tag:us-east-vpc.

{
  "grants": [
    {
      "src": ["tag:us-east-vpc"], // Devices behind a restrictive NAT that need to be accessed through the peer relay
      "dst": ["tag:us-east-relays"], // The devices functioning as peer relays for the src devices
      "app": {
        "tailscale.com/cap/relay": []
      }
    }
  ]
}

For this to work, you must also configure the peer relay devices using the tailscale set command and create a grant access control policy that permits overlay network access to devices with the tag:us-east-vpc tag.

For example, this grant policy lets all members of the tailnet access devices with the tag:us-east-vpc tag on TCP ports 80 and 443.

{
  "grants": [
    {
      "src": ["autogroup:member"],
      "dst": ["tag:us-east-vpc"],
      "ip": ["tcp:80","tcp:443"]
    }
  ]
}

Use self as peer relay

It's possible for devices to use themselves as a peer relay. The following example lets the device with the hostname us-west-1 use itself as a peer relay. You might use this configuration in a scenario where you need to block all incoming ports to a device except for the UDP port used for peer relay traffic.

{
  "grants": [
    {
      "src": ["us-west-1"],
      "dst": ["us-west-1"],
      "app": {
          "tailscale.com/cap/relay": []
      }
    }
  ]
}

For this to work, you must also configure the device as a peer relay using the tailscale set with the UDP port for peer relay traffic.

Security and access control

Peer relays can only relay traffic for devices in the same tailnet and are subject to access control policies. This means that a device can't use a peer relay to establish connections if it doesn't have permission to access the device functioning as a peer relay.

The UDP port you configure for peer relay traffic must be open and accessible from other devices in the tailnet. For example, if you configure a peer relay to use UDP port 40000, ensure that any firewalls or network security settings allow incoming traffic on that port.