muxen-eagle — Overview

muxen-eagle puts the boat's Brain on MUXEN's remote-support network. Once it has run successfully, MUXEN can reach that Brain over the internet — from the workshop, from another country, with the boat lying at anchor — to look at a log, diagnose a fault or apply a fix, without anyone travelling to the marina.

It is not something that runs while the boat is under way, and it has no screen page. It is a one-shot bootstrap: at start-up it asks the NetBird client already installed on the Brain whether this boat is already on the network, registers it if it is not, and then stops. The connection itself is held open afterwards by the netbird daemon, which is a separate package.

For the crew, the whole thing is invisible and there is nothing to configure. For an installer it is one service to check at commissioning: either the boat is enrolled, or it is not.

The problem it solves

A Brain is delivered, installed on a boat, and then sails away. It sits behind whatever internet connection the boat has that week — a 4G router, a marina Wi-Fi, a satellite link — almost always behind NAT, with no fixed address and no inbound port anybody controls.

NetBird solves the connectivity part: peers register with a management server and then reach each other directly through a peer-to-peer VPN. What it does not solve is the first step. Somebody has to tell this particular Brain which management server to use and prove that it is allowed to join, exactly once, at a moment when nobody is standing next to it.

muxen-eagle is that step. It ships a NetBird setup key inside the package, hands it to the local NetBird client at the right moment, and deletes it from the boat the instant enrolment succeeds. From then on the NetBird daemon holds its own peer credentials and the key is never needed again.

Where it sits

muxen-deploy.target ──► muxen-eagle-init ──► netbird daemon ──► eagle.muxen.fr
   (boot, deploy)          (oneshot,           (persistent,       (management
                            exits)              other package)     server)

The management server is eagle.muxen.fr, over HTTPS on port 443. That name is where the project's own name comes from; the boat's peer identity, its address on the overlay and every routing decision live on that server, not on the Brain.

It reads	From	Purpose
/etc/muxen/eagle.key	disk, shipped in the package	the NetBird setup key
netbird status --json	the local netbird daemon	is this boat already enrolled, and is it connected?
/var/lib/netbird/default.json	disk	detect a legacy install whose default profile already points at eagle
/var/lib/netbird/active_profile.json	disk	which of several eagle profiles is the active one
netbird profile list	the local netbird daemon	the profiles that exist
systemctl show netbird	systemd	whether NetBird's SSH-config management is already disabled

It writes	To	Purpose
netbird profile add / select / remove	the local netbird daemon	make eagle the active profile, and drop duplicates
netbird up --management-url …	the local netbird daemon	register the boat and bring the tunnel up
netbird service reconfigure	the local netbird daemon	set NB_DISABLE_SSH_CONFIG=true
deletion of /etc/muxen/eagle.key	disk	the key has done its job and must not survive on the boat

It touches nothing else. No CAN bus, no MQTT, no configuration file of its own, no state directory, no port of its own.

When it runs

The unit is WantedBy=muxen-deploy.target, and the package is installed with dh_installsystemd --no-start — so installing the package starts nothing. The first run happens when the MUXEN deploy target comes up, which on a fresh Brain is after the boat has been commissioned. That ordering is deliberate: a Brain that has not yet been given its identity has no business joining the fleet network.

The unit is Type=oneshot with RemainAfterExit=yes, so after a successful run it sits at active (exited) and does not run again until something restarts it.

Failure is treated as a fact of life at sea. A boat can be offline for hours or days before it can enrol, so the unit retries forever, every five minutes, with the systemd start rate limiter switched off. There is exactly one failure it refuses to retry — no setup key and not enrolled — because no amount of waiting fixes that.

Enrolment walks the decision order in full.

Success looks like an empty hand

The single most confusing thing about this service, for anyone meeting it for the first time, is that a healthy enrolled boat has no setup key on it. The file /etc/muxen/eagle.key is deleted on every path that ends in "this boat is on the network". Its absence is the normal steady state, not a fault, and the service is written so that it checks "am I already connected?" before it ever looks at the key.

The setup key covers where the key comes from, why it is not a Debian conffile, and what an empty one means.

Document map

Document	Content
Getting started	install, when it runs, how to tell that the boat is enrolled
Enrolment	the decision order, the retry policy, what re-runs it
The setup key	the setup key: origin, permissions, lifetime, deletion
Troubleshooting	symptom → cause → check → fix, plus FAQ and tips
Reference	messages, exit codes, files, netbird commands, unit, packaging