Custom DERP Servers

A custom DERP server is a designated DERP server set up and managed by an organization or individual other than Tailscale for specific networking needs. DERP servers play a supporting role in facilitating connectivity between devices in a Tailscale network (known as a tailnet), primarily serving as a fallback mechanism when direct connections aren't possible.

In most scenarios, Tailscale uses DERP servers to establish direct connections between devices, and data plane traffic flows directly between them. In this case, DERP servers function only as a low-bandwidth side channel to start the NAT traversal process. If a direct connection isn't possible, DERP servers are a fallback mechanism for connecting devices.

Reasons to run a custom DERP server

You might consider running a custom DERP server to:

• Reduce latency by hosting a DERP server in an additional geographic location.
• Restrict where encrypted traffic is routed to comply with a corporate policy.

Setting up a custom DERP server can give you more control over the DERP relay infrastructure, potentially providing benefits such as improved performance and increased security. However, custom DERP servers also have limitations and are almost never necessary.

Latency

One of the primary reasons to host a custom DERP is to add a DERP server in a geographic location where one is not already available to reduce latency for tailnet devices in that location.

Hosting a custom DERP server in such as scenario can reduce latency for those devices. However, problems like limited bandwidth typically indicate an underlying network configuration issue with your tailnet (or tailnet devices) that prevents direct connections. In this case, hosting a custom DERP server won't reduce latency. Instead, refer to the connectivity troubleshooting guide.

Policy compliance

Another common reason to host a custom DERP server is to ensure policy compliance. For example, you might have a strict policy requirement that prevents traffic from going through public servers, even if the traffic is encrypted.

DERP servers only forward encrypted traffic, and they have no access to plain text traffic. Additionally, Tailscale's DERP servers are shared resources across all Tailscale customers. You may have a strict routing policy, such as preventing encrypted traffic from traversing servers outside of your control.

To comply with such a policy, you can run one or more custom DERP servers and remove the default Tailscale DERP servers from the list of DERP servers your tailnet can use.

Limitations

In most cases, there's no need to run a custom DERP server. However, there are some rare cases in which it makes sense to run a custom DERP server. To do so, you must build, deploy, and update the cmd/derper binary.

Running custom DERP servers is an advanced operation that requires significant resources on your part to set up and maintain. Additionally, running a custom DERP servers have the following caveats:

• Custom DERP servers don't support device sharing or other cross-tailnet features.
• Custom DERP servers, just like normal DERP servers, have no visibility of the data exchanged between devices because they're encrypted. As a result, DERP servers aren't helpful for network-level debugging.
• Custom DERP servers won't benefit from some optimizations from the Tailscale control plane.
• Custom DERP servers won't work from behind a firewall or a load balancer.
• Mullvad exit nodes don't work with custom DERP servers.
• Custom DERP servers are not utilized for regional routing. Refer to issue #12993 for updates.

Requirements

Custom DERP servers must have direct access to the internet, allow ICMP traffic, and open ports for HTTP, HTTPS, and STUN.

Direct internet access

DERP servers require direct Internet connectivity and must not be behind NAT devices (such as firewalls) or load balancers. This direct connection requirement exists for two critical reasons: device identification and protocol compatibility.

Device identification

DERP servers identify tailnet devices by inspecting the source addresses of incoming traffic. This crucial functionality fails when traffic passes through NAT or load balancers, as they modify the original source addresses.

Protocol compatibility

Tailscale clients use the HTTP upgrade protocol to establish bidirectional data channels. Most cloud load balancer systems don't support this protocol, making them incompatible with DERP server operations.

Required ports

DERP servers must have the following ports open to 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 homes or coffee shops.

To use other port numbers for HTTPS and STUN, set DERPNode.DERPPort or DERPNode.STUNPort, respectively. You cannot use a custom port number for HTTP.

ICMP traffic

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

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.

Get started with a custom DERP server

To set up a custom DERP server, you'll need to:

1. Run a DERP server from source.
2. Add the DERP server to your tailnet.

The following additional steps are optional:

1. Restrict tailnet device access to your custom DERP server.
2. Remove Tailscale's default DERP servers from your tailnet.

Run a DERP server from source

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@latest

... 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=example.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.

Add the custom 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 to 999 are reserved for use as custom, user-specified regions and will not be used by Tailscale.

For example, the following configuration enables a custom DERP server with the hostname example.com. For more options, refer to the definitions of DERPRegion and DERPNode.

{
  // ... other parts of tailnet policy file
  "derpMap": {
    "Regions": {
      "900": {
        "RegionID": 900,
        "RegionCode": "myderp",
        "Nodes": [
          {
            "Name": "1",
            "RegionID": 900,
            "HostName": "example.com",
            // IPv4 and IPv6 are optional, but recommended, to reduce
            // potential DERP connectivity issues if DNS is unavailable
            // or having issues. Addresses must be publicly routable
            // and not in private IP ranges.
            "IPv4": "203.0.113.15",
            "IPv6": "2001:db8::1"
          }
        ]
      }
    }
  }
}

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) Remove Tailscale's DERP servers

For various reasons, such as compliance, you might not want to route traffic through a specific DERP region. You can remove DERP regions available to the devices in your tailnet by creating a the custom DERP map in the tailnet policy file. To exclude a region, set its value to null. When set to null, devices in your tailnet cannot connect to DERP servers in that region.

For example, the following DERP map configuration disables routing traffic through the New York Tailscale DERP region, which has the region ID 1:

{
  // ... other parts of tailnet policy file
  "derpMap": { "Regions": { "1": null } }
}

You can access Tailscale's default DERP map from https://controlplane.tailscale.com/derpmap/default:

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 custom DERP servers, remove all Tailscale's default DERP regions by setting the OmitDefaultRegions flag to true in the DERP map:

{
  // ... other parts of tailnet policy file
  "derpMap": {
    "OmitDefaultRegions": true,
    "Regions": {
      "900": {
        "RegionID": 900,
        "RegionCode": "myderp",
        "Nodes": [
          {
            "Name": "1",
            "RegionID": 900,
            "HostName": "example.com",
            // IPv4 and IPv6 are optional, but recommended, to reduce
            // potential DERP connectivity issues if DNS is unavailable
            // or having issues. Addresses must be publicly routable
            // and not in private IP ranges.
            "IPv4": "203.0.113.15",
            "IPv6": "2001:db8::1"
          }
        ]
      }
    }
  }
}

You can access the full set of options for DERP maps the source code's DERPMap definition.

(Optional) Verify client traffic to the custom DERP server

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

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

Monitoring custom DERP servers

Use the cmd/derpprobe binary to monitor your custom DERP servers 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.