Documentation
Reference: CLI and configuration files
This page describes, without inventing subcommands, how the two VIGIL-MESH services are configured and started. A vigie reads a minimal configuration file and registers with the controller using the register command, which consumes a one-shot token. The controller — the web server — starts from its own configuration. Everything else in a vigie's state (keys, fleet certificate, allocations) comes down from the controller; it is never written by hand.
A vigie's configuration file
A vigie is configured through a minimal file, for example /etc/vigil/vigie.toml. It contains only what bootstraps the enrollment: the controller then provides everything else. It typically holds four pieces of information.
| Field | Role |
|---|---|
| Token | One-shot fleet token, generated on the controller side; it bootstraps the enrollment and is consumed by the first register. |
| Controller fingerprint | Fingerprint (pin) of the controller, so the vigie can verify it is talking to the right server. |
| IP | Public IP address at which the vigie is reachable from the outside. |
| Capabilities | Capabilities advertised by the vigie (what it declares it can serve). |
Registering a vigie
On first startup, the register command consumes the one-shot token declared in the file. In return, the vigie receives from the controller its verification keys, its fleet certificate, the list of its sibling vigies and its first allocations.
- The token is one-shot: once consumed by register, it cannot be replayed.
- Enrollment brings the vigie's state down from the controller — there is nothing else to write locally.
- A simple outbound connection is not enough: after register, the controller qualifies the three inbound listeners (udp/443, udp/4433, tcp/443) from the outside before allocating any traffic.
Starting the server (controller)
The controller — the web server that coordinates the workspace, publishes the signed network maps and distributes the allocations — starts from its own configuration, for example passed through a web configuration option (e.g. --web-config). This service is what issues the tokens, qualifies the vigies and signs the netmaps.
- The controller is the source of truth: it issues the tokens, validates the enrollments and publishes the signed netmaps.
- Vigies and nodes derive their state from this server; they never contradict it.
Best practices
- Treat the token as a secret: it authorizes an enrollment. Generate it just before use and let it be consumed quickly.
- Restrict the permissions on the vigie's configuration file (read access limited to the service account) and avoid committing it to a repository.
- Check the controller fingerprint in the file: it is what prevents a vigie from registering with an impostor.
- Decommission rather than reuse: changing a vigie's scope or owner requires removing it and generating a new token — there is no in-place reconfiguration.