From fe47157a7caf32240daebcf4cad2cb97e3eb2f6d Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 3 Jul 2025 11:42:26 +0200 Subject: [PATCH 1/3] docs: fix wrong roles assignment syntax --- docs/site/guides/clanServices.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/site/guides/clanServices.md b/docs/site/guides/clanServices.md index 465098122..c2272ad76 100644 --- a/docs/site/guides/clanServices.md +++ b/docs/site/guides/clanServices.md @@ -17,8 +17,10 @@ For example: ```nix inventory.instances = { borgbackup = { - roles.client.machines = [ "laptop" "server1" ]; - roles.server.machines = [ "backup-box" ]; + roles.client.machines."laptop" = {}; + roles.client.machines."server1" = {}; + + roles.server.machines."backup-box" = {}; }; } ``` @@ -40,7 +42,8 @@ Example of instantiating a `borgbackup` service using `clan-core`: ```nix inventory.instances = { # Instance Name: Different name for this 'borgbackup' instance - borgbackup-example = { + borgbackup = { + # Since this is instances."borgbackup" the whole `module = { ... }` below is equivalent and optional. module = { name = "borgbackup"; # <-- Name of the module (optional) input = "clan-core"; # <-- The flake input where the service is defined (optional) From 62ada9e1c2a87ee3b91b995e54455c8f685dd8c8 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 3 Jul 2025 12:04:56 +0200 Subject: [PATCH 2/3] 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 From 0f6f0a6237750961c8038b90d1f7148cdb49b170 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Thu, 3 Jul 2025 16:25:10 +0200 Subject: [PATCH 3/3] docs: add zerotier debugging commands --- docs/site/guides/mesh-vpn.md | 71 +++++++++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/docs/site/guides/mesh-vpn.md b/docs/site/guides/mesh-vpn.md index 4dda7433b..038de1ce7 100644 --- a/docs/site/guides/mesh-vpn.md +++ b/docs/site/guides/mesh-vpn.md @@ -31,11 +31,7 @@ For the purpose of this guide we have two machines: ## Configure the Service -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. - -```nix {.nix title="flake.nix" hl_lines="13-15"} +```nix {.nix title="flake.nix" hl_lines="19-25"} { inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz"; inputs.nixpkgs.follows = "clan-core/nixpkgs"; @@ -73,12 +69,33 @@ will also be visible in the Zerotier app. ``` ## Apply the Configuration -Update the `controller` machine: + +Update the `controller` machine first: ```bash clan machines update controller ``` +Then update all other peers: + +```bash +clan machines update +``` + +### Verify Connection + +On the `new_machine` run: + +```bash +$ sudo zerotier-cli info +``` + +The status should be "ONLINE": + +```{.console, .no-copy} +200 info d2c71971db 1.12.1 ONLINE +``` + ## Further Currently you can only use **Zerotier** as networking technology because this is the first network stack we aim to support. @@ -87,3 +104,45 @@ In the future we plan to add additional network technologies like tinc, head/tai We chose zerotier because in our tests it was a straight forwards solution to bootstrap. It allows you to selfhost a controller and the controller doesn't need to be globally reachable. Which made it a good fit for starting the project. + +## Debugging + +### Retrieve the ZeroTier ID + +In the repo: + +```console +$ clan vars list +``` + +```{.console, .no-copy} +$ clan vars list controller +# ... elided +zerotier/zerotier-identity-secret: ******** +zerotier/zerotier-ip: fd0a:b849:2928:1234:c99:930a:a959:2928 +zerotier/zerotier-network-id: 0aa959282834000c +``` + +On the machine: + +```bash +$ sudo zerotier-cli info +``` + +#### Manually Authorize a Machine on the Controller + +=== "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. \ No newline at end of file