yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request 'docs: update vpn setup instructions' (#4192) from docs into main

Browse Source 
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4192
This commit is contained in:
hsjobeki
2025-07-03 14:32:13 +00:00
parent 0d771ffd10 0f6f0a6237
commit d5a1aba480
2 changed files with 107 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/site/guides/clanServices.md
View File

@@ -17,8 +17,10 @@ For example:
```nix ```nix
inventory.instances = { inventory.instances = {
borgbackup = { borgbackup = {
roles.client.machines = [ "laptop" "server1" ]; roles.client.machines."laptop" = {};
roles.server.machines = [ "backup-box" ]; roles.client.machines."server1" = {};
roles.server.machines."backup-box" = {};
}; };
} }
``` ```
@@ -40,7 +42,8 @@ Example of instantiating a `borgbackup` service using `clan-core`:
```nix ```nix
inventory.instances = { inventory.instances = {
# Instance Name: Different name for this 'borgbackup' instance # 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 = { module = {
name = "borgbackup"; # <-- Name of the module (optional) name = "borgbackup"; # <-- Name of the module (optional)
input = "clan-core"; # <-- The flake input where the service is defined (optional) input = "clan-core"; # <-- The flake input where the service is defined (optional)

214
docs/site/guides/mesh-vpn.md
View File

@@ -15,140 +15,86 @@ Clan
Node B Node B
``` ```
If you select multiple network technologies at the same time. e.g. (zerotier + yggdrassil) This guide shows you how to configure `zerotier` through clan's `Inventory` System.
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` 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**" For the purpose of this guide we have two machines:
## 1. Choose the Controller
The controller is the initial entrypoint for new machines into the vpn. - The `controller` machine, which will be the zerotier controller.
It will sign the id's of new machines. - The `new_machine` machine, which is the machine we want to add to the vpn network.
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.
For the purpose of this guide we have two machines: ## Configure the Service
- The `controller` machine, which will be the zerotier controller. ```nix {.nix title="flake.nix" hl_lines="19-25"}
- The `new_machine` machine, which is the machine we want to add to the vpn network. {
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". meta.name = "myclan";
It will be added as an altname for the Zerotier virtual ethernet interface, and
will also be visible in the Zerotier app.
```nix inventory.machines = {
clan.inventory = { controller = {};
services.zerotier.default = { new_machine = {};
roles.controller.machines = [ };
"controller"
]; inventory.instances = {
roles.peer.machines = [ zerotier = {
"new_machine" # 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 ## Apply the Configuration
Update the `controller` machine:
```bash Update the `controller` machine first:
clan machines update controller
```
```bash
clan machines update controller
```
=== "**NixOS Options**" Then update all other peers:
## 1. Set-Up the VPN Controller
The VPN controller is initially essential for providing configuration to new ```bash
peers. Once addresses are allocated, the controller's continuous operation is not essential. clan machines update
```
1. **Designate a Machine**: Label a machine as the VPN controller in the clan, ### Verify Connection
referred to as `<CONTROLLER>` 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 <CONTROLLER>
```
Your machine is now operational as the VPN controller.
## 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 The status should be "ONLINE":
configuration, substituting `<CONTROLLER>` with the controller machine name:
```nix
{ config, ... }: {
clan.core.networking.zerotier.networkId = builtins.readFile ../../vars/per-machine/<CONTROLLER>/zerotier/zerotier-network-id/value;
}
```
1. **Update the New Machine**: Execute:
```bash
$ clan machines update <NEW_MACHINE>
```
Replace `<NEW_MACHINE>` with the designated new machine name.
!!! Note "For Private Networks" ```{.console, .no-copy}
1. **Retrieve Zerotier Metadata** 200 info d2c71971db 1.12.1 ONLINE
```
=== "From the repo"
**Retrieve the ZeroTier IP**: In the clan repo, execute:
```console
$ clan facts list <NEW_MACHINE> | 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 <IP>
```
Substitute `<IP>` with the ZeroTier IP obtained previously.
=== "with ZerotierID"
```bash
$ sudo zerotier-members allow <ID>
```
Substitute `<ID>` 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.
## Further ## 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. 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. 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. Which made it a good fit for starting the project.
## Debugging
### Retrieve the ZeroTier ID
In the repo:
```console
$ clan vars list <machineName>
```
```{.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 <IP>
```
Substitute `<IP>` with the ZeroTier IP obtained previously.
=== "with ZerotierID"
```bash
$ sudo zerotier-members allow <ID>
```
Substitute `<ID>` with the ZeroTier ID obtained previously.