From b27ed51284e9056ecae6716710f1347f4506b112 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 3 Jul 2025 12:04:56 +0200 Subject: [PATCH] docs: update vpn setup instructions --- docs/site/guides/mesh-vpn.md | 171 ++++++++++------------------------- 1 file changed, 50 insertions(+), 121 deletions(-) diff --git a/docs/site/guides/mesh-vpn.md b/docs/site/guides/mesh-vpn.md index 46a25e1e7..4dda7433b 100644 --- a/docs/site/guides/mesh-vpn.md +++ b/docs/site/guides/mesh-vpn.md @@ -15,140 +15,69 @@ Clan Node B ``` -If you select multiple network technologies at the same time. e.g. (zerotier + yggdrassil) -You must choose one of them as primary network and the machines are always connected via the primary network. +This guide shows you how to configure `zerotier` through clan's `Inventory` System. -This guide shows you how to configure `zerotier` either through `NixOS Options` directly, or Clan's `Inventory` System. +## The Controller +The controller is the initial entrypoint for new machines into the vpn. +It will sign the id's of new machines. +Once id's are signed, the controller's continuous operation is not essential. +A good controller choice is nevertheless a machine that can always be reached for updates - so that new peers can be added to the network. -=== "**Inventory**" - ## 1. Choose the Controller +For the purpose of this guide we have two machines: - The controller is the initial entrypoint for new machines into the vpn. - It will sign the id's of new machines. - Once id's are signed, the controller's continuous operation is not essential. - A good controller choice is nevertheless a machine that can always be reached for updates - so that new peers can be added to the network. +- The `controller` machine, which will be the zerotier controller. +- The `new_machine` machine, which is the machine we want to add to the vpn network. - For the purpose of this guide we have two machines: +## Configure the Service - - The `controller` machine, which will be the zerotier controller. - - The `new_machine` machine, which is the machine we want to add to the vpn network. +Note: consider picking a more descriptive name for the VPN than "default". +It will be added as an altname for the Zerotier virtual ethernet interface, and +will also be visible in the Zerotier app. - ## 2. Configure the Inventory +```nix {.nix title="flake.nix" hl_lines="13-15"} +{ + inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; + inputs.nixpkgs.follows = "clan-core/nixpkgs"; - Note: consider picking a more descriptive name for the VPN than "default". - It will be added as an altname for the Zerotier virtual ethernet interface, and - will also be visible in the Zerotier app. + outputs = + { self, clan-core, ... }: + let + clan = clan-core.lib.clan { + inherit self; - ```nix - clan.inventory = { - services.zerotier.default = { - roles.controller.machines = [ - "controller" - ]; - roles.peer.machines = [ - "new_machine" - ]; + meta.name = "myclan"; + + inventory.machines = { + controller = {}; + new_machine = {}; + }; + + inventory.instances = { + zerotier = { + # Assign the controller machine to the role "controller" + roles.controller.machines."controller" = {}; + + # All clan machines are zerotier peers + roles.peer.tags."all" = {}; + }; + }; }; + in + { + inherit (clan) nixosConfigurations nixosModules clanInternals; + + # elided for brevity }; - ``` +} +``` - ## 3. Apply the Configuration - Update the `controller` machine: +## Apply the Configuration +Update the `controller` machine: - ```bash - clan machines update controller - ``` - - -=== "**NixOS Options**" - ## 1. Set-Up the VPN Controller - - The VPN controller is initially essential for providing configuration to new - peers. Once addresses are allocated, the controller's continuous operation is not essential. - - 1. **Designate a Machine**: Label a machine as the VPN controller in the clan, - referred to as `` henceforth in this guide. - 2. **Add Configuration**: Input the following configuration to the NixOS - configuration of the controller machine: - ```nix - clan.core.networking.zerotier.controller = { - enable = true; - public = true; - }; - ``` - 3. **Update the Controller Machine**: Execute the following: - ```bash - clan machines update - ``` - Your machine is now operational as the VPN controller. - - ## 2. Add Machines to the VPN - - To introduce a new machine to the VPN, adhere to the following steps: - - 1. **Update Configuration**: On the new machine, incorporate the following to its - configuration, substituting `` with the controller machine name: - ```nix - { config, ... }: { - clan.core.networking.zerotier.networkId = builtins.readFile ../../vars/per-machine//zerotier/zerotier-network-id/value; - } - ``` - 1. **Update the New Machine**: Execute: - ```bash - $ clan machines update - ``` - Replace `` with the designated new machine name. - - !!! Note "For Private Networks" - 1. **Retrieve Zerotier Metadata** - - === "From the repo" - **Retrieve the ZeroTier IP**: In the clan repo, execute: - ```console - $ clan facts list | jq -r '.["zerotier-ip"]' - ``` - - The returned address is the Zerotier IP address of the machine. - - === "On the new machine" - **Retrieve the ZeroTier ID**: On the `new_machine`, execute: - ```bash - $ sudo zerotier-cli info - ``` - Example Output: - ```{.console, .no-copy} - 200 info d2c71971db 1.12.1 OFFLINE - ``` - , where `d2c71971db` is the ZeroTier ID. - - - 2. **Authorize the New Machine on the Controller**: On the controller machine, - execute: - - === "with ZerotierIP" - ```bash - $ sudo zerotier-members allow --member-ip - ``` - Substitute `` with the ZeroTier IP obtained previously. - === "with ZerotierID" - ```bash - $ sudo zerotier-members allow - ``` - Substitute `` with the ZeroTier ID obtained previously. - - 2. **Verify Connection**: On the `new_machine`, re-execute: - ```bash - $ sudo zerotier-cli info - ``` - The status should now be "ONLINE": - ```{.console, .no-copy} - 200 info d2c71971db 1.12.1 ONLINE - ``` - -!!! success "Congratulations!" - The new machine is now part of the VPN, and the ZeroTier - configuration on NixOS within the Clan project is complete. +```bash +clan machines update controller +``` ## Further