From 2f5f746492d4e8fd2848fede4b3eaf58854bad37 Mon Sep 17 00:00:00 2001 From: Konarak Date: Tue, 30 Sep 2025 21:16:36 +0530 Subject: [PATCH] update README with a more detailed setup guide --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 118 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 04b22a5..ec08da9 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,125 @@ # sixnix -My ISP provides me a single `/64` and it's dynamically assigned. I cannot have multiple networks with functional autoconfiguration. One solution to this is use one of 4to6 [tunnel brokers](https://tunnelbroker.services/) like the one offered by [Hurricane Electric](https://tunnelbroker.net/). Since my ISP uses CGNAT this setup is tricky if not impossible. +NixOS module for IPv6 networking with WireGuard tunnels and optional BGP failover. -Fortunately Linode provides free `/56` to customers and the cheapest VPS costs just $5/month. You get 256 `/64` subnets. The following table provides an example where you can have 15 delegations of `/60` and use the 16th `/60` for the wireguard peer addressing. +## Motivation -| Client subnet | WireGuard subnet | | -|--------------------|---------------------|----| -| 2001:db8::/60 | 2001:db8:0:f0::/64 | 1 | -| 2001:db8:0:10::/60 | 2001:db8:0:f1::/64 | 2 | -| 2001:db8:0:20::/60 | 2001:db8:0:f2::/64 | 3 | -| 2001:db8:0:30::/60 | 2001:db8:0:f3::/64 | 4 | -| 2001:db8:0:40::/60 | 2001:db8:0:f4::/64 | 5 | -| 2001:db8:0:50::/60 | 2001:db8:0:f5::/64 | 6 | -| 2001:db8:0:60::/60 | 2001:db8:0:f6::/64 | 7 | -| 2001:db8:0:70::/60 | 2001:db8:0:f7::/64 | 8 | -| 2001:db8:0:80::/60 | 2001:db8:0:f8::/64 | 9 | -| 2001:db8:0:90::/60 | 2001:db8:0:f9::/64 | 10 | -| 2001:db8:0:a0::/60 | 2001:db8:0:fa::/64 | 11 | -| 2001:db8:0:b0::/60 | 2001:db8:0:fb::/64 | 12 | -| 2001:db8:0:c0::/60 | 2001:db8:0:fc::/64 | 13 | -| 2001:db8:0:d0::/60 | 2001:db8:0:fd::/64 | 14 | -| 2001:db8:0:e0::/60 | 2001:db8:0:fe::/64 | 15 | +My ISP gives me a single `/64` and it's dynamically assigned. Can't have multiple networks with functional autoconfiguration. Tunnel brokers like [Hurricane Electric](https://tunnelbroker.net/) would work but my ISP uses CGNAT which makes that setup tricky if not impossible. They also do not have any exit nodes in the region I want. -| Host | Subnet | -|-----------------------|-----------------------------| -| wireguard.example.com | 2001:0db8:0:ff::/64 | +Linode provides a routed `/56` for free with their cheapest $5/month VPS. That's 256 `/64` subnets. You get 1TB traffic at 1Gbit (40Gbit input but that's kind of irrelevant for our use case). Good enough. -You can follow the linode's [nixos installation guide](https://www.linode.com/docs/guides/install-nixos-on-linode/) and/or use this repo as a reference to set up your wireguard tunnels. +## Solution 1: Simple WireGuard setup -- set up sops using the [docs here](https://github.com/Mic92/sops-nix) -- add root password, wireguard server private keys and peer public keys -- add ssh public keys and configure any additional user accounts in `modules/access.nix` -- configure egress, firewall, wireguard tunnels etc in `modules/network.nix` +Just a plain WireGuard tunnel to route the `/56` to your home network. + +With a `/56` you can carve out a `/60` for WireGuard endpoints and you're left with 15 `/60` subnets. Share it with friends! + +| Client subnet | WireGuard subnet | | +|--------------------|----------------------|----| +| 2001:db8::/60 | 2001:db8:0:f0::a/127 | 1 | +| 2001:db8:0:10::/60 | 2001:db8:0:f1::a/127 | 2 | +| 2001:db8:0:20::/60 | 2001:db8:0:f2::a/127 | 3 | +| 2001:db8:0:30::/60 | 2001:db8:0:f3::a/127 | 4 | +| 2001:db8:0:40::/60 | 2001:db8:0:f4::a/127 | 5 | +| 2001:db8:0:50::/60 | 2001:db8:0:f5::a/127 | 6 | +| 2001:db8:0:60::/60 | 2001:db8:0:f6::a/127 | 7 | +| 2001:db8:0:70::/60 | 2001:db8:0:f7::a/127 | 8 | +| 2001:db8:0:80::/60 | 2001:db8:0:f8::a/127 | 9 | +| 2001:db8:0:90::/60 | 2001:db8:0:f9::a/127 | 10 | +| 2001:db8:0:a0::/60 | 2001:db8:0:fa::a/127 | 11 | +| 2001:db8:0:b0::/60 | 2001:db8:0:fb::a/127 | 12 | +| 2001:db8:0:c0::/60 | 2001:db8:0:fc::a/127 | 13 | +| 2001:db8:0:d0::/60 | 2001:db8:0:fd::a/127 | 14 | +| 2001:db8:0:e0::/60 | 2001:db8:0:fe::a/127 | 15 | + +### Basic configuration + +```nix +{ + inputs.sixnix.url = "git+https://code.planet-express.in/konarak/sixnix.git"; + + outputs = { nixpkgs, sixnix, ... }: { + nixosConfigurations.tunnel-server = nixpkgs.lib.nixosSystem { + modules = [ + sixnix.nixosModules.default + { + sixnix = { + enable = true; + hostname = "tunnel-server"; + domain = "example.com"; + }; + + wireguard.interfaces = [{ + interface = "wg0"; + serverPort = 51820; + serverAddress = "2001:db8:a7c4:0:f0::a/127"; + clientAddress = "2001:db8:a7c4:0:f0::b/127"; + clientSubnet = "2001:db8:a7c4::/60"; + serverPrivateKeyFile = "/run/secrets/wg0-server-private"; + clientPublicKeyFile = "/run/secrets/wg0-client-public"; + }]; + } + ]; + }; + }; +} +``` + +How it works: +- Your router uses the ISP-provided IPv6 to connect to the WireGuard server +- Interfaces get `/64`s from the delegated `/60` with router advertisement enabled +- All traffic from clients goes out to the internet via Linode + +## Solution 2: BGP failover (ultra advanced) + +Want redundancy? Run two Linodes in the same datacenter and use BGP to share a single `/56` between them. If one server goes down, BGP automatically fails over to the other. + +Cost: $10/month + tax for two Linodes with pooled 2TB bandwidth quota. + +### BGP configuration + +```nix +{ + sixnix = { + enable = true; + hostname = "tunnel-primary"; + domain = "example.com"; + + bgp = { + enable = true; + peers = [ + "2001:db8:9f2b::1" # BGP peer addresses (e.g., Linode route servers) + "2001:db8:9f2b::2" + "2001:db8:9f2b::3" + "2001:db8:9f2b::4" + ]; + advertisedSubnets = [ "2001:db8:a7c4::/56" ]; + routeMap = "primary"; # or "secondary" for the backup server + }; + }; + + wireguard.interfaces = [{ + interface = "wg0"; + serverPort = 51820; + serverAddress = "2001:db8:a7c4:0:f0::a/127"; + clientAddress = "2001:db8:a7c4:0:f0::b/127"; + clientSubnet = "2001:db8:a7c4::/60"; + serverPrivateKeyFile = "/run/secrets/wg0-server-private"; + clientPublicKeyFile = "/run/secrets/wg0-client-public"; + }]; +} +``` + +The BGP setup creates: +- A shared dummy interface with a VIP that both servers announce +- Route servers configured automatically based on datacenter ID +- Blackhole routes for the advertised subnet +- Primary/secondary route maps for failover priority + +## Notes + +- BGP peers and advertised subnets are fully configurable +- The FRR configuration template may need adjustments for providers other than Linode (AS numbers, communities, etc.) +- For Linode: use route servers `2600:3c0f::34::{1,2,3,4}` where `` is your datacenter ID (e.g., 25 for in-maa) +- See Linode's [BGP documentation](https://techdocs.akamai.com/cloud-computing/docs/configuring-ip-failover-over-bgp-using-frr-advanced) for more details +- See [`modules/network.nix`](modules/network.nix) and [`modules/wireguard.nix`](modules/wireguard.nix) for all available options \ No newline at end of file