2024-04-12 13:22:20 +00:00
# Overlay Networks
2023-09-29 15:36:29 +00:00
This guide provides detailed instructions for configuring
[ZeroTier VPN ](https://zerotier.com ) within Clan. Follow the
outlined steps to set up a machine as a VPN controller (`< CONTROLLER > `) and to
include a new machine into the VPN.
## 1. Setting Up the VPN Controller
The VPN controller is initially essential for providing configuration to new
2024-04-14 10:43:09 +00:00
peers. Once addresses are allocated, the controller's continuous operation is not essential.
2023-09-29 15:36:29 +00:00
2024-04-17 16:26:37 +00:00
### Instructions
2023-09-29 15:36:29 +00:00
1. **Designate a Machine** : Label a machine as the VPN controller in the clan,
referred to as `<CONTROLLER>` henceforth in this guide.
2024-04-14 10:43:09 +00:00
1. **Add Configuration** : Input the following configuration to the NixOS
2023-09-29 15:36:29 +00:00
configuration of the controller machine:
```nix
clan.networking.zerotier.controller = {
enable = true;
public = true;
};
```
2024-04-14 10:43:09 +00:00
1. **Update the Controller Machine** : Execute the following:
2024-04-10 16:40:07 +00:00
```bash
2023-09-29 15:36:29 +00:00
$ clan machines update < CONTROLLER >
```
Your machine is now operational as the VPN controller.
## 2. Integrating a New Machine to the VPN
To introduce a new machine to the VPN, adhere to the following steps:
### Instructions:
2024-04-14 10:43:09 +00:00
1. **Update Configuration** : On the new machine, incorporate the following to its
2023-09-29 15:36:29 +00:00
configuration, substituting `<CONTROLLER>` with the controller machine name:
```nix
{ config, ... }: {
clan.networking.zerotier.networkId = builtins.readFile (config.clanCore.clanDir + "/machines/< CONTROLLER > /facts/zerotier-network-id");
}
```
2024-04-14 10:43:09 +00:00
1. **Update the New Machine** : Execute:
2024-04-10 16:40:07 +00:00
```bash
2023-09-29 15:36:29 +00:00
$ clan machines update < NEW_MACHINE >
```
Replace `<NEW_MACHINE>` with the designated new machine name.
2024-04-14 10:43:09 +00:00
1. **Retrieve the ZeroTier ID** : On the `new_machine` , execute:
2024-04-10 16:40:07 +00:00
```bash
2023-09-29 15:36:29 +00:00
$ sudo zerotier-cli info
```
2024-04-14 10:43:09 +00:00
Example Output:
```{.console, .no-copy}
200 info d2c71971db 1.12.1 OFFLINE
```
, where `d2c71971db` is the ZeroTier ID.
1. **Authorize the New Machine on the Controller** : On the controller machine,
2023-09-29 15:36:29 +00:00
execute:
2024-04-10 16:40:07 +00:00
```bash
2023-09-29 15:36:29 +00:00
$ sudo zerotier-members allow < ID >
```
Substitute `<ID>` with the ZeroTier ID obtained previously.
2024-04-14 10:43:09 +00:00
1. **Verify Connection** : On the `new_machine` , re-execute:
2024-04-10 16:40:07 +00:00
```bash
2023-09-29 15:36:29 +00:00
$ sudo zerotier-cli info
```
2024-04-14 10:43:09 +00:00
The status should now be "ONLINE":
```{.console, .no-copy}
200 info d2c71971db 1.12.1 ONLINE
```
2024-04-14 13:18:16 +00:00
!!! success "Congratulations!"
The new machine is now part of the VPN, and the ZeroTier
2024-04-14 10:43:09 +00:00
configuration on NixOS within the Clan project is complete.
2023-09-29 15:36:29 +00:00
2024-04-17 16:26:37 +00:00
## Decision
We chose zerotier because in our tests it was the easiest solution to bootstrap. You can selfhost a controller and the controller doesn't need to be globally reachable.
In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium.
## Specification
By default all machines within one clan are connected via the chosen network technology.
```
Clan
Node A
< - > (zerotier / mycelium / ...)
Node B
```
If you select multiple network technologies at the same time. e.g. (zerotier + yggdrassil)
One of them is the primary network and the above statement holds for the primary network.