Install VIGIL-MESH on Linux (desktop and server)

Prerequisites

The Linux agent covers two uses: a user's desktop workstation, and the server (or site machine) with no graphical interface. In both cases, the installation creates a TUN interface and a service managed by systemd. It requires root rights, for the duration of the installation only.

• A Debian- or Ubuntu-based Linux distribution (.deb package), on amd64 or arm64 architecture.
• Root rights (sudo) to install the package, create the TUN interface and enable the service.
• TUN interface support in the kernel (standard on common distributions).
• For a screenless server: a pre-authorized key provided by an administrator, to enroll the machine without interaction. For a desktop: an invitation, a key, or the approval queue.
• Outbound Internet access: no inbound firewall rule or port forwarding to prepare.

Download

The Linux agent ships as a .deb package, for the amd64 and arm64 architectures. The general guide is on /download; per-platform builds are listed on /download/client, from a signed manifest that publishes the version number and the SHA-256 fingerprint of each file.

1. 1
   Pick the right packageOn /download/client, select the .deb package matching your architecture: amd64 for an x86-64 server or workstation, arm64 for a 64-bit ARM (for example a mini server or an embedded board).
2. 2
   Get the .deb and its fingerprintDownload the .deb file along with the SHA-256 fingerprint published next to it, in the signed manifest.
3. 3
   Verify integrityCompute the fingerprint of the downloaded package with sha256sum, then compare it to the one in the manifest. If the two SHA-256 values differ, do not install the package and download it again.

Install and start the service

1. 1
   Install the packageInstall the verified .deb with the package manager (for example sudo apt install ./vigil-mesh_<version>_<arch>.deb). The installation creates the TUN interface and registers the service.
2. 2
   Enable and start the serviceEnable then start the service at boot with systemd (for example sudo systemctl enable --now vigil-mesh). On a server, the agent thus runs in the background, with no graphical session.
3. 3
   Check the statusVerify that the service is active (for example systemctl status vigil-mesh) and consult its logs if needed. The agent stays connected and recovers automatically after a reboot.

Enroll

Once the service is running, the machine must be enrolled to join the workspace. On a desktop, you can go through an invitation, a pre-authorized key or the approval queue. On a screenless server, the pre-authorized key is the recommended path: it enrolls the machine with no interaction at all.

1. 1
   Get a pre-authorized keyAsk an administrator for a pre-authorized key for the workspace. It allows the machine to enroll without manual validation.
2. 2
   Enroll the agent with the keyProvide the key to the agent on the command line (for example via the client's enrollment command, or an environment variable of the service). The machine enrolls and opens its session to the mesh.
3. 3
   Confirm the membershipCheck that the machine does appear in the workspace and that its session is established. It is now a member of the network.

Verify

After enrollment, check that the agent is a proper member of the mesh. A few checks are enough, on desktop as on server.

• Stable address: the TUN interface received an IPv4 address in the 100.64.0.0/10 space and an IPv6 ULA address, which do not change from one session to the next.
• Name resolution: MagicDNS resolves the names of the other devices locally, without any query leaving the machine.
• Reachability: a simple test (ping to the mesh address of another node, then access to a shared service) confirms the path is open.

For a complete verification procedure and diagnosis of edge cases, follow the page dedicated to verification after enrollment.