Headscale VPN System Documentation

Overview

This document outlines the configuration, management, and troubleshooting procedures for the internal VPN infrastructure. The system utilizes Headscale as the open-source alternative to Tailscale’s coordination server, providing a “Sub-NAT” solution to bypass complex firewall/NAT configurations.

System Architecture

The system is composed of the following components:

• Headscale: The core coordination server.
• Headplane: The web-based UI for managing the tailnet (accessible via Headscale).
• Traefik: The reverse proxy handling SSL certificates and routing traffic to Headscale and Headplane.

Access Points

Infrastructure Configuration

2. Docker Infrastructure

The deployment uses Docker Compose with the following services:

• headscale: Runs on port 8080 (internally).
• headplane: Runs on port 3000 (internally).
• traefik: Manages ingress traffic and Let’s Encrypt SSL certificates.

Operations

Adding a New User

To add a new user via the CLI (within the headscale container):

docker exec headscale headscale users create default

(Note: Replace “default” with the desired username if necessary).

Registering a Client Device

To connect a new device to the tailnet:

1. On the Client Machine:

   sudo tailscale up --login-server=https://vpn.solidservice.link

2. On the Server (Headscale Console): Upon running the command above, the client will output a registration link/key. Use this key to register the device on the server:

   headscale nodes register --user <USERNAME> --key <KEY>

   (Example: headscale nodes register --user default --key RPDBX2J5w_csWA2uuP0Y6evb)

Policy & Routing

To ensure the client can see the full subnet:

sudo tailscale set --accept-routes=true

Troubleshooting

Connectivity Checks

• Verify Docker Containers:

  docker ps | grep headscale

• Check Tailnet Status: On a client machine, check the status of other peers and their internal IPs:

  tailscale status

Common Issues

• No Internet on Clients: Verify the MASQUERADE rules in iptables and ensure the enp2s0 gateway is reachable.
• Cannot Reach Management UI: Check Traefik logs and ensure the vpn.solidservice.link certificate is valid via Let’s Encrypt.
• Subnet Routes not working: Ensure tailscale set --accept-routes=true was executed on the client.

Last Updated: 2026-09-01