Docs / Admin

Custom DERP Servers

Tailscale runs DERP relays 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 clients automatically select the nearest relay so it’s almost never necessary to run your own.

So why run a custom DERP server? 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.

Step 1: Starting your own DERP server

To run your own DERP server, you must to build the DERP server from source. Using the latest version of Go (currently Go 1.16), 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 the next section.

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

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 supply your own instance of DERP servers by specifying them in the policy JSON. These features will be added to the default set of DERP servers and will be available for Tailscale clients on the tailnet for the policy to connect to. Currently, we allow users to supply 100 different servers to connect through, in the range of 900-999.

For example this will enable a custom DERP server with hostname “your-hostname.com”. Additional options are available, such as specifying a TLS cert common name, or an IP address to use instead of a domain name.

{
  // ... other parts of ACL
  "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 policy JSON will disable routing traffic through DERP-1, NYC.

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

For a detailed DERP map which contains a list of regions, you can run:

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

Which will list all of Tailscale’s DERP servers and their region IDs.

If instead of removing one or a few regions, you’d like to remove all of Tailscale’s default DERPs, for example if you’d like to establish connection through your own servers, this can be done by setting the flag OmitDefaultRegions on the supplied DERP map, as shown below.

{
  // ... 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 documentation. The docs specify which fields are required, and the purpose of each field.

Last updated