conflux: one command to put a machine on a VeilNet overlay

The enrolment model is a taint, not an account

conflux puts one machine on a VeilNet overlay with a single command. It bundles anchord and anchorctl, enrols against the public network with no account and no key to manage, and comes back at the same overlay address after a reboot. The authorisation model is the taint. When the first machine comes up it asks for an IPv4 address and mints a taint for the network, a string of grouped characters that the README calls as private as it is hard to guess. The credential for that machine is issued in the taint, for the life of its identity, and any other machine that runs up with the same taint is issued a credential in it too, joining that network and nothing else. Because anybody may ask for any name, the README's advice is to keep the taint to the machines meant to join. Once a machine holds a credential its taints are fixed, and a later --taint may only repeat them.

Installing the binary, and the fact that it enrols nothing on its own

The install is a shell script on Unix and a PowerShell one on Windows.

$ curl -fsSL https://raw.githubusercontent.com/veil-net/conflux/HEAD/install.sh | sh

irm https://raw.githubusercontent.com/veil-net/conflux/HEAD/install.ps1 | iex

The script takes the machine's build from the latest release, checks it against the release's SHA256SUMS, and installs it as /usr/local/bin/conflux, or on Windows as a program files path on the PATH. The README is explicit that it starts nothing and enrols nothing, that being the next step and yours to run. You can pin a version, install somewhere else, or download by hand, and the install document carries the platform notes. The build from source is make anchor-bins and make build. The boot service runs a copy of the binary that conflux places in its own state directory, which only root can change, and the up, proxy, install, start and update commands keep that copy current.

Bringing up the first machine, and what it prints back

The first machine asks for an address and then reports the state of the whole setup.

$ sudo conflux up
An IPv4 lets the other machines on this network reach this one by a v4 address.
A private address is advertised to them; give each machine that should be
reachable on its own a different one. The IPv6 address is derived from this
machine's identity and needs no answer.

  IPv4 [e.g. 10.128.0.7/24, blank for none]: 10.128.0.1/24

After the answer the tool prints the mint, the taint, the overlay address, the interface name, the credential and its expiry, and the service state, so you have a record of what was created. The overlay address is derived from the machine's identity and needs no answer, while the IPv4 address is the one thing you choose. The credential line includes an expiry timestamp, and the service line shows the systemd unit name and that it is enabled at boot. A reboot then needs nothing typed, because the service is registered, the credential renews itself, and the machine comes back at the same overlay address.

Joining other machines, from a prompt or from a script

Every other machine gets the taint from the first and its own address.

$ sudo conflux up --taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf --ipv4 10.128.0.2/24

Passing --taint and --ipv4 on the command line answers the interactive prompt in advance, which is what makes it safe to run from a provisioning script. To check the result, the README suggests pinging the address and then running two status commands. The conflux status command prints conflux's own state, which is mode, taint, address, credential expiry and service, with anchorctl status beneath it. The peers command is not conflux's at all, it is one of the commands handed straight through to anchorctl, and that pass-through is the general rule: anything conflux does not recognise is forwarded unchanged.

Proxy mode for hosts where you cannot get the capabilities

Some hosts will not give you CAP_NET_ADMIN, a container, a locked-down machine or a CI runner. For those, conflux has a proxy mode that skips the interface entirely and publishes ports instead.

$ sudo conflux proxy 8080=127.0.0.1:3000 53/udp=127.0.0.1:53

The semantics are that a peer connecting to the machine's overlay port 8080 gets a fresh connection to the local address and port, and the spec format is OVERLAYPORT with an optional network, equals BACKEND, with the network defaulting to tcp. A backend address in brackets is an IPv6 address, and the backend is dialled fresh per connection rather than resolved up front, so a name that does not resolve yet is not a problem. Enrolment, the taint and the boot service all behave as they do in the up command, and nothing appears on the host. The anchor itself needs no privilege at all in this mode, and sudo is only there so the boot service can be registered. To add or remove a proxy on a running anchor without a restart, you use anchorctl's own proxy command, which is a different thing from the conflux proxy command that decides the mode the machine boots into.

The self-hosted guardian flips the model, and the uplink replaces the socket

The second deployment shape is the opposite of the public network one. Against a self-hosted guardian, where an operator runs their own control plane and their own subtree of the network tree, machines are commissioned in advance and there is no enrolment route at all, so a manifest and an API URL install the credential and the up command starts from it. Renewal then authenticates, and revocation exists, because there is somebody keeping a record. The credentials document covers the detail. There is a third mode, a generic uplink, for joining over a cable. An anchor normally binds a UDP socket and needs a host IP network underneath it, and an uplink replaces that, so a file descriptor becomes the medium instead and no socket is bound at all. Point each end of a cable at its device and the two machines share a network with no IP network between them, which is why the uplink example passes --no-ipv4 alongside the device path and the taint.

A Go project that keeps its version in a file rather than a tag

The repository is a Go module named for conflux with a small dependency list, the only direct requirement being golang.org/x/sys, and the source is split into an anchor directory, a cmd directory, an internal directory, scripts and a test directory. The Makefile is where the interesting decisions are. Its comment says VERSION is the file, not the tag, because a tag is a claim about a commit while the file is a claim about the tree, and the release workflow tags the release with that same file so the number in the binary and the number on the release cannot disagree. The linker flags stamp both the version and the commit into the binary. There is also a stamp target that computes the SHA-256 of the embedded anchor binaries for a given target, so a released conflux does not have to read forty megabytes at run time to learn which pair it carries, and the stamp is computed from the same paths that are embedded so it cannot describe other bytes. The default branch is version3, the licence is one GitHub cannot classify, and the first release is 1.0.0 with a 1.0.0-pre before it.

Editorial conclusion

conflux fits someone who needs a small private overlay between machines and does not want to run an account system to join them, and who can accept that a taint is the whole of the authorisation. It does not fit a deployment that needs per-machine identity records, unless you run your own guardian, and it does not fit a host where you cannot get network capabilities and do not want the proxy mode. Verify first which mode you are in, since the self-hosted guardian has no enrolment route at all, keep the taint to the machines meant to join, and check the credential expiry the tool prints on first bring-up.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. veil-net/conflux on GitHub