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) diff --git a/docs/site/guides/mesh-vpn.md b/docs/site/guides/mesh-vpn.md index 46a25e1e7..038de1ce7 100644 --- a/docs/site/guides/mesh-vpn.md +++ b/docs/site/guides/mesh-vpn.md @@ -15,140 +15,86 @@ 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. +```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"; - ## 2. Configure the Inventory + outputs = + { self, clan-core, ... }: + let + clan = clan-core.lib.clan { + inherit self; - 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. + meta.name = "myclan"; - ```nix - clan.inventory = { - services.zerotier.default = { - roles.controller.machines = [ - "controller" - ]; - roles.peer.machines = [ - "new_machine" - ]; + 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 - ```bash - clan machines update controller - ``` +Update the `controller` machine first: +```bash +clan machines update controller +``` -=== "**NixOS Options**" - ## 1. Set-Up the VPN Controller +Then update all other peers: - The VPN controller is initially essential for providing configuration to new - peers. Once addresses are allocated, the controller's continuous operation is not essential. +```bash +clan machines update +``` - 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. +### Verify Connection - ## 2. Add Machines to the VPN +On the `new_machine` run: - To introduce a new machine to the VPN, adhere to the following steps: +```bash +$ sudo zerotier-cli info +``` - 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. +The status should be "ONLINE": - !!! 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. +```{.console, .no-copy} +200 info d2c71971db 1.12.1 ONLINE +``` ## Further @@ -158,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