update README with a more detailed setup guide

2025-09-30 21:16:36 +05:30
parent 01a77e65a6
commit 2f5f746492
1 changed files with 118 additions and 27 deletions
--- 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:<dcId>:34::{1,2,3,4}` where `<dcId>` 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