Skip to content

zerotier 🔹

Configures Zerotier VPN secure and efficient networking within a Clan..

Categories

Network
System

Overview

This guide explains how to set up and manage a ZeroTier VPN for a clan network. Each VPN requires a single controller and can support multiple peers and optional moons for better connectivity.

Roles

1. Controller

The Controller manages network membership and is responsible for admitting new peers. When a new node is added to the clan, the controller must be updated to ensure it has the latest member list.

  • Key Points:
  • Must be online to admit new machines to the VPN.
  • Existing nodes can continue to communicate even when the controller is offline.

2. Moons

Moons act as relay nodes, providing direct connectivity to peers via their public IP addresses. They enable devices that are not publicly reachable to join the VPN by routing through these nodes.

  • Configuration Notes:
  • Each moon must define its public IP address.
  • Ensures connectivity for devices behind NAT or restrictive firewalls.

3. Peers

Peers are standard nodes in the VPN. They connect to other peers, moons, and the controller as needed.

  • Purpose:
  • General role for all machines that are neither controllers nor moons.
  • Ideal for most clan members' devices.

Usage via Inventory

Roles

This module can be used via predefined roles

- `peer`
- `controller`
- `moon`

Every role has its own configuration options. Which are each listed below.

For more information, see the inventory guide.

Example

For example the admin module adds the following options globally to all machines where it is used.

clan.admin.allowedkeys

This means there are two equivalent ways to set the allowedkeys option. Either via a nixos module or via the inventory interface. But it is recommended to keep together imports and config to preserve locality of the module configuration.

clan-core.lib.buildClan {
    inventory.services = {
        admin.me = {
            roles.default.machines = [ "jon" ];
            config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
        };
    };
};

clan-core.lib.buildClan {
    machines = {
        jon = {
            clan.admin.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ];
            imports = [ clanModules.admin ];
        };
    };
};

Options of peer role

The following options are available when using the peer role.

clan.zerotier.excludeHosts

Hosts that should be excluded

Type: list of string

Default:

[
  "nixos"
]

shared.nix

clan.zerotier.networkIds

Extra zerotier network Ids that should be accepted

Type: list of string

Default:

[ ]

shared.nix

clan.zerotier.networkIps

Extra zerotier network Ips that should be accepted

Type: list of string

Default:

[ ]

shared.nix

Options of controller role

The following options are available when using the controller role.

clan.zerotier.excludeHosts

Hosts that should be excluded

Type: list of string

Default:

[
  "nixos"
]

shared.nix

clan.zerotier.networkIds

Extra zerotier network Ids that should be accepted

Type: list of string

Default:

[ ]

shared.nix

clan.zerotier.networkIps

Extra zerotier network Ips that should be accepted

Type: list of string

Default:

[ ]

shared.nix

Options of moon role

The following options are available when using the moon role.

clan.zerotier.excludeHosts

Hosts that should be excluded

Type: list of string

Default:

[
  "nixos"
]

shared.nix

clan.zerotier.moon.stableEndpoints

Make this machine a moon. Other machines can join this moon by adding this moon in their config. It will be reachable under the given stable endpoints.

Type: list of string

moon.nix

clan.zerotier.networkIds

Extra zerotier network Ids that should be accepted

Type: list of string

Default:

[ ]

shared.nix

clan.zerotier.networkIps

Extra zerotier network Ips that should be accepted

Type: list of string

Default:

[ ]

shared.nix

Usage via Nix

This module cannot be imported directly in your nixos configuration.