Custom DERP Servers

Tailscale runs DERP relay servers to help connect your nodes. Generally, you don't need to customize Tailscale DERP servers. However, it is possible to do it.

Why run your own DERP server?

It's almost never necessary to run your own DERP server. There are two main reasons you might consider doing so:

• for lower latency
• for policy compliance

For lower latency

You may be located far from an existing DERP server and experiencing high latency connecting to Tailscale's existing DERP servers.

If you lived in Antarctica, for example, you may experience high latency reaching Tailscale's own DERP servers as no DERP servers are run within Antarctica at the moment. You could run your own to speed up connections that can't work peer-to-peer.

To restrict where encrypted traffic is routed

You may have a strict policy requirement that your traffic never goes through public or shared servers, even if it is encrypted.

Tailscale's DERP servers are shared across customers, but only used to forward your encrypted traffic. Tailscale can't see or intercept your traffic in plaintext.

If you want to restrict where your encrypted data plane traffic is routed, then you can run your own DERP servers, as well as remove Tailscale default DERP servers from the list your tailnet can use.

Provide a direct Internet connection with both IPv4 and IPv6

DERP servers should be directly connected to the Internet. Running DERP servers behind NAT or load balancers is not supported and will almost certainly not work. DERP servers provide Tailscale nodes with endpoint identification by inspecting the source addresses of incoming traffic, functions which are not possible when behind a NAT or load balancer. Additionally, most cloud load balancer systems do not support the HTTP upgrade protocol that Tailscale clients use to establish bidirectional data channels.

DERP servers should have both IPv4 and IPv6 connectivity. A DERP server will operate with only IPv4 or IPv6 connectivity, however a DERP server that only has an IPv4 address would not be usable by a Tailscale node that only has IPv6 connectivity.

Prerequisites

Required ports

Each DERP node must run an HTTP server, an HTTPS server, and a STUN server. The ports for those three services need to be open for traffic from the internet so users in your tailnet can access them from places such as their home or coffee shops.

You must use port TCP 80 for HTTP. By default, HTTPS runs on port 443, and STUN runs on 3478. To use other port numbers for HTTPS and STUN, set DERPNode.DERPPort or DERPNode.STUNPort, respectively.

Required ICMP ingress/egress

Each DERP node must allow inbound and outbound Internet Control Message Protocol (ICMP) traffic.

Step 1: Starting your own DERP server

To run your own DERP server, you must build the DERP server from source. Using the latest version of Go, run:

go install tailscale.com/cmd/derper@main

... to install the latest DERP server to $HOME/go/bin.

Before running the binary, you'll need a domain name pointing at your server. With both the domain name and the binary, to start the DERP server on your domain name run:

sudo derper --hostname=your-hostname.com

This will start the DERP server exposed on port 443, reachable at your domain. Then, you can add the DERP server to your tailnet as specified in Step 2.

Optional: Restricting client access to your DERP node

Anyone that knows the IP address of your DERP node could add it to their DERP map and route their tailnet traffic through your DERP node. To allow only your tailnet traffic through your DERP node, run tailscaled on the same machine as your DERP node, and start derper with the --verify-clients flag:

sudo derper --hostname=your-hostname.com --verify-clients

Step 2: Adding DERP servers to your tailnet

If you find that Tailscale does not provide a DERP server within your region, or you are otherwise unable to use the provided DERPs, you can augment or edit the set of DERP servers by specifying them in your tailnet's policy JSON by setting the derpMap key to a value of type DERPMap.

Each region has a unique region ID. The region ID values 900-999 are reserved for use as custom, user-specified regions and will not be used by Tailscale.

For example, the following config will enable a custom DERP server with hostname your-hostname.com. For more options, see the definitions of DERPRegion and DERPNode.

{
  // ... other parts of ACL/Policy JSON
  "derpMap": {
    "Regions": {
      "900": {
        "RegionID": 900,
        "RegionCode": "myderp",
        "Nodes": [
          {
            "Name": "1",
            "RegionID": 900,
            "HostName": "your-hostname.com"
          }
        ]
      }
    }
  }
}

There can be only one DERP server per region. If you want DERP redundancy, use multiple regions with only one DERP server in each region.

Optional: Removing Tailscale’s DERP Regions

For various reasons, such as compliance, you may not want to route traffic through a specific DERP region. In that case, it is possible to remove DERP regions available to the Tailscale client through the custom DERP map in the policy JSON. By setting a region to null, a specific region will be disabled so that clients will no longer connect to it.

For example, this DERP map config will disable routing traffic through Tailscale DERP region ID 1, New York:

{
  // ... other parts of ACL
  "derpMap": { "Regions": { "1": null } }
}

Tailscale's default DERP map is accessible via:

curl https://controlplane.tailscale.com/derpmap/default

If you have jq installed, use this to list Tailscale's default DERP regions and their IDs:

curl --silent https://controlplane.tailscale.com/derpmap/default | jq -r '.Regions[] | "\(.RegionID) \(.RegionName)"'

To guarantee that your traffic only flows through your own DERP nodes, you can remove all of Tailscale’s default DERP regions by setting the OmitDefaultRegions flag in the DERP map:

{
  // ... other parts of ACL
  "derpMap": {
    "OmitDefaultRegions": true,
    "Regions": {
      "900": {
        "RegionID": 900,
        "RegionCode": "myderp",
        "Nodes": [
          {
            "Name": "1",
            "RegionID": 900,
            "HostName": "your-hostname.com"
          }
        ]
      }
    }
  }
}

The full set of options for DERP maps can be found in the source code's DERPMap definition. The docs specify which fields are required, and the purpose of each field.

Monitoring custom DERPs

You can use the cmd/derpprobe binary to monitor your custom DERPs and to verify they are working correctly. You'll need to specify a --derp-map=file:// URL that is a JSON document with your DERP map to monitor.