Docs / Admin

Custom DERP Servers

Tailscale runs DERP relay servers to help connect your nodes. In addition to or instead of using the Tailscale DERP servers, you can also run your own.

Custom DERP servers is currently in alpha.

What are DERP servers?

Tailscale runs DERP relay servers distributed around the world to link your Tailscale nodes peer-to-peer as a side channel during NAT traversal, and as a fallback in case NAT traversal fails and a direct connection cannot be established.

Tailscale runs DERP servers in many locations. As of January 2022, this list includes the US (San Francisco, Seattle, Dallas, Chicago, and New York City), UK (London), Germany (Frankfurt), India (Bangalore), Japan (Tokyo), Singapore (Singapore), Australia (Sydney), and Brazil (São Paulo).

Tailscale clients automatically selects the nearest relay for low latency. Tailscale is continually expanding and adding more DERP servers as needed in order to provide low-latency connections.

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.

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/[email protected]

… 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.

To stay compatible with Tailscale client updates, you may need to update DERP servers periodically by rebuilding from source with go install github.com/tailscale/cmd/[email protected].

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, and each region can have one or more nodes within it. 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"
      }]
    }}
  }
}

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 available 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.

Required ports

Each DERP node runs an HTTPS server and a STUN server. The ports for those two services need to be open for traffic from the internet so users in your tailnet can access them from home, coffee shops, etc.

By default, those services run on port TCP 443 (https) and UDP 3478 (STUN). To use other port numbers, set DERPNode.DERPPort or DERPNode.STUNPort, respectively.

Last updated

WireGuard is a registered
trademark of Jason A. Donenfeld.

© 2022 Tailscale Inc.

Privacy & Terms