clan-core/docs/site/guides/mesh-vpn.md

This guide provides detailed instructions for configuring ZeroTier VPN 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.

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

{
  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:

clan machines update controller

Then update all other peers:

clan machines update

Verify Connection

On the new_machine run:

$ sudo zerotier-cli info

The status should be "ONLINE":

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:

$ clan vars list <machineName>

$ 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:

$ 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.