Networking Vpn

Networking: Tailscale & Headscale

Secure, zero-config mesh VPN (SD-WAN) and its self-hosted coordination server.

Overview

This repository provides first-class support for private networking via the Tailscale protocol. We support both the official Tailscale managed service and a fully self-hosted Headscale implementation.

Key Concepts

  • MagicDNS: Automatically assigns a stable, human-readable DNS name (e.g., my-server.hs.alienzj.org) to every device in your private network. You can access services via these names instead of IP addresses.
  • DERP (Detoured Encrypted Routing Protocol): A relay system used as a fallback when two devices cannot establish a direct peer-to-peer (P2P) connection due to strict firewalls or NAT.
  • Node: Any device (server, laptop, phone) running the Tailscale client and connected to your mesh.

Tailscale (Official)

Enabled via the ts0 network profile.

  • Profile: modules/profiles/network/ts0.nix
  • Usage: Add "ts0" to the modules.profiles.networks list in your host configuration.
  • Authentication: Run sudo tailscale up on the device to authenticate with the Tailscale control plane.

Headscale (Self-Hosted)

For full sovereignty, we provide a Headscale implementation that replaces the Tailscale coordination server.

Server Setup

The server is managed via modules/services/net/headscale.nix. It is high-performance, using:

  • Database: PostgreSQL (managed via our declarative ensures system).
  • Reverse Proxy: Nginx with QUIC/HTTP3 and kTLS enabled.
  • Network: Uses the standard 100.64.0.0/10 (IPv4) and fd7a:115c:a1e0::/48 (IPv6) ranges for compatibility with official Tailscale clients.

Client Setup (hs0)

To connect a node to your own Headscale instance:

  1. Add "hs0" to the modules.profiles.networks list.
  2. The hs0 profile (modules/profiles/network/hs0.nix) pre-configures the --login-server flag.
  3. Authenticate by running: 
    sudo tailscale up --login-server https://hs.yourdomain.com

Custom DERP & DNS

By default, Headscale uses official Tailscale relay nodes by fetching the global DERP map. You can also declaratively define private DNS records and point to a custom DERP map:

modules.services.net.headscale = {
  enable = true;
  derpMapUrl = "https://hs.${baseDomain}/derpmap/default";
  dnsRecords = [
    { name = "git.internal"; type = "A"; value = "100.64.0.5"; }
  ];
};

Hosting a Custom DERP Map

If you host your own relay nodes (using the derper tool), you can serve the map via Nginx:

# Example Nginx config to serve a custom DERP map
services.nginx.virtualHosts."hs.${baseDomain}".locations."/derpmap/default" = {
  extraConfig = ''
    root /etc/derper;
    rewrite ^/derpmap/default$ /servers.json break;
    default_type application/json;
  '';
};

# Define the nodes in environment.etc
environment.etc."derper/servers.json".text = builtins.toJSON {
  Regions = {
    "1" = {
      RegionID = 1;
      RegionCode = "hel";
      RegionName = "Helsinki";
      Nodes = [{
        Name = "1a";
        RegionID = 1;
        HostName = "your-relay-host.com";
        IPv4 = "1.2.3.4";
        CanPort80 = true;
      }];
    };
  };
};

Advanced Routing

Our modules are optimized for “Relay Architecture”:

  1. VPS Ingress: A public VPS (like vps-pacman) acts as a gateway.
  2. Internal Forwarding: Nginx on the VPS proxies traffic over the Tailscale/Headscale IP to a backend homelab node.
  3. Real-IP Preservation: Every backend service automatically restores the original client IP from the X-Forwarded-For header provided by the VPS, ensuring accurate logging and security (Fail2Ban).