wireguard

Wireguard-based VPN mesh network with automatic IPv6 address allocation

<div style="background-color: #77DD77; color: white; padding: 10px; border-radius: 20px; text-align: center;">
    Network
</div>

This service provides a WireGuard-based VPN mesh network with automatic IPv6 address allocation and routing between clan machines.

Overview🔗

The WireGuard service creates a secure mesh network between clan machines using two roles:

• Controllers: Machines with public endpoints that act as connection points and routers
• Peers: Machines that connect through controllers to access the network

Requirements🔗

• Controllers must have a publicly accessible endpoint (domain name or static IP)
• Peers must be in networks where UDP traffic is not blocked (uses port 51820 by default, configurable)

Features🔗

• Automatic IPv6 address allocation using ULA (Unique Local Address) prefixes
• Full mesh connectivity between all machines
• Automatic key generation and distribution
• IPv6 forwarding on controllers for inter-peer communication
• Support for multiple controllers for redundancy

Network Architecture🔗

IPv6 Address Allocation🔗

• Base network: /40 ULA prefix (deterministically generated from instance name)
• Controllers: Each gets a /56 subnet from the base /40
• Peers: Each gets a unique 64-bit host suffix that is used in ALL controller subnets

Addressing Design🔗

• Each peer generates a unique host suffix (e.g., :8750:a09b:0:1)
• This suffix is appended to each controller's /56 prefix to create unique addresses
• Example: peer1 with suffix :8750:a09b:0:1 gets:
  • fd51:19c1:3b:f700:8750:a09b:0:1 in controller1's subnet
  • fd51:19c1:c1:aa00:8750:a09b:0:1 in controller2's subnet
• Controllers allow each peer's /96 subnet for routing flexibility

Connectivity🔗

• Peers use a single WireGuard interface with multiple IPs (one per controller subnet)
• Controllers connect to ALL other controllers and ALL peers on a single interface
• Controllers have IPv6 forwarding enabled to route traffic between peers
• All traffic between peers flows through controllers
• Symmetric routing is maintained as each peer has consistent IPs across all controllers

Example Network Topology🔗

Configuration🔗

Basic Setup with Single Controller🔗

# In your clan.nix
{
  instances = {
    wireguard = {
      module.name = "wireguard";
      module.input = "clan-core";
      roles.controller = {
        machines.server1 = {};
        settings = {
          # Public endpoint where this controller can be reached
          endpoint = "vpn.example.com";
          # Optional: Change the UDP port (default: 51820)
          port = 51820;
        };
      };
      roles.peer = {
        # No configuration needed if only one controller exists
        machines.laptop1 = {};
      };
    };
  }
}

Multiple Controllers Setup🔗

{
  instances = {
    wireguard = {
      module.name = "wireguard";
      module.input = "clan-core";
      roles.controller.machines = {
        server1.settings.endpoint = "vpn1.example.com";
        server2.settings.endpoint = "vpn2.example.com";
        server3.settings.endpoint = "vpn3.example.com";
      };
      roles.peer.machines.laptop1 = {
        # Must specify which controller subnet is exposed as the default in /etc/hosts, when multiple controllers exist
        settings.controller = "server1";
      };
    };
  }
}

Advanced Options🔗

Automatic Hostname Resolution🔗

The WireGuard service automatically adds entries to /etc/hosts for all machines in the network. Each machine is accessible via its hostname in the format <machine-name>.<instance-name>.

For example, with an instance named vpn:

• server1.vpn - resolves to server1's IPv6 address
• laptop1.vpn - resolves to laptop1's IPv6 address

This allows machines to communicate using hostnames instead of IPv6 addresses:

# Ping another machine by hostname
ping6 server1.vpn

# SSH to another machine
ssh user@laptop1.vpn

Troubleshooting🔗

Check WireGuard Status🔗

sudo wg show

Verify IP Addresses🔗

ip addr show dev <instance-name>

Check Routing🔗

ip -6 route show dev <instance-name>

Interface Fails to Start: "Address already in use"🔗

If you see this error in your logs:

wireguard: Could not bring up interface, ignoring: Address already in use

This means the configured port (default: 51820) is already in use by another service or WireGuard instance. Solutions:

1. Check for conflicting WireGuard instances:

   sudo wg show
   sudo ss -ulnp | grep 51820

2. Use a different port:

   services.wireguard.myinstance = {
     roles.controller = {
       endpoint = "vpn.example.com";
       port = 51821;  # Use a different port
     };
   };

3. Ensure unique ports across multiple instances: If you have multiple WireGuard instances on the same machine, each must use a different port.

Key Management🔗

Keys are automatically generated and stored in the clan vars system. To regenerate keys:

# Regenerate keys for a specific machine and instance
clan vars generate --service wireguard-keys-<instance-name> --regenerate --machine <machine-name>

# Apply the new keys
clan machines update <machine-name>

Security Considerations🔗

• All traffic is encrypted using WireGuard's modern cryptography
• Private keys never leave the machines they're generated on
• Public keys are distributed through the clan vars system
• Controllers must have publicly accessible endpoints
• Firewall rules are automatically configured for the WireGuard ports

Roles🔗

The wireguard service has the following roles:

• controller
• peer

Options for the controller role🔗

domain🔗

Domain suffix to use for hostnames in /etc/hosts. Defaults to the instance name.

Type: null or string

Default:

instanceName

Declared in: clanServices/wireguard/default.nix

endpoint🔗

Endpoint where the controller can be reached

Type: string

"vpn.clan.lol"

Declared in: clanServices/wireguard/default.nix

port🔗

Port for the wireguard interface

Type: signed integer

Default:

51820

51820

Declared in: clanServices/wireguard/default.nix

Options for the peer role🔗

controller🔗

Machinename of the controller to attach to

Type: string

"controller1"

Declared in: clanServices/wireguard/default.nix

domain🔗

Domain suffix to use for hostnames in /etc/hosts. Defaults to the instance name.

Type: null or string

Default:

instanceName

Declared in: clanServices/wireguard/default.nix

port🔗

Port for the wireguard interface

Type: signed integer

Default:

51820

51820

Declared in: clanServices/wireguard/default.nix