docs: init new structure

docs/site/guides/networking/mesh-vpn.md

@@ -0,0 +1,149 @@
+
+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.
+
+## Concept
+
+By default all machines within one clan are connected via a chosen network technology.
+
+```{.no-copy}
+Clan
+    Node A
+    <-> (zerotier / mycelium / ...)
+    Node B
+```
+
+This guide shows you how to configure `zerotier` through 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.
+
+For the purpose of this guide we have two machines:
+
+- 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.
+
+## Configure the Service
+
+```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";
+
+  outputs =
+    { self, clan-core, ... }:
+    let
+      # Sometimes this attribute set is defined in clan.nix
+      clan = clan-core.lib.clan {
+        inherit self;
+
+        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
+    };
+}
+```
+
+## Apply the Configuration
+
+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.
+In the future we plan to add additional network technologies like tinc, head/tailscale, yggdrassil and mycelium.
+
+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 <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.