Getting started

Prerequisites

On the Brain:

• The netbird client, version 0.28.8 or later, installed and its daemon running. The package declares it as a Pre-Depends, so apt will not even unpack muxen-eagle without it. The version floor is not cosmetic: muxen-eagle-init passes the setup key with --setup-key-file, which older clients do not accept.
• jq and bash 5.0 or later. Both are Depends. The service is a bash script that parses NetBird's JSON output.
• The muxen.target / muxen-deploy.target pair, which is what the unit hangs off. Both come from another MUXEN package; this one does not declare a dependency on it, so on a Brain that lacks the targets the unit installs and is simply never started.
• A working route to the internet, and a system clock that is roughly right. Enrolment is an HTTPS call to eagle.muxen.fr, and TLS certificate validation fails on a Brain whose clock has not been set.
• A host name other than bali-58-999. The unit carries ConditionHost=!bali-58-999 and is skipped on that one machine.

Nothing else. The service holds no state of its own, opens no listening port, and writes no file — the only file it touches, it deletes.

Install

sudo apt install muxen-eagle

The package is Architecture: all: one .deb for every Brain. It carries three things — the muxen-eagle-init script, the systemd unit, and the NetBird setup key at /etc/muxen/eagle.key, owned by root with mode 0600.

Installing it enrols nothing. The unit is installed with dh_installsystemd --no-start, so it is enabled but not started. Registering a Brain on the fleet network is not something an apt install should do behind your back.

When it actually runs

The unit is WantedBy=muxen-deploy.target. It runs when that target comes up: at boot, and whenever the MUXEN deployment is (re)started. On a Brain being commissioned for the first time, that means enrolment happens after the boat has been given its deployment, not before.

To run it now, on purpose:

sudo systemctl start muxen-eagle

Verify

Three checks, in this order.

1. The unit.

systemctl status muxen-eagle

● muxen-eagle.service - Muxen Eagle Init
     Loaded: loaded (/usr/lib/systemd/system/muxen-eagle.service; enabled)
     Active: active (exited)

active (exited) is the healthy end state — the unit is Type=oneshot with RemainAfterExit=yes, so it stays there after the script has finished. activating (start) between attempts, or failed, means something is wrong; go to Troubleshooting.

2. What it said. The script is deliberately laconic: one line, and that line tells you which of its four outcomes you got.

journalctl -u muxen-eagle -n 20

Line	Meaning
Already connected to eagle	the boat was already enrolled and online. Nothing to do
Already connected using default profile (legacy install)	enrolled by an older release, on the default profile
Enrolled with eagle but not connected yet; leaving it to netbird	credentials are on the boat, the link is not up. Normal when offline
(no message, exit 0)	it enrolled the boat during this run

3. NetBird itself. This is the answer that matters, and it comes from the client rather than from this service:

netbird status --json | jq '{url: .management.url, connected: .management.connected}'

{
  "url": "https://eagle.muxen.fr:443",
  "connected": true
}

Those are exactly the two fields muxen-eagle-init reads to decide whether it has anything to do. url pointing at eagle.muxen.fr:443 means the boat is enrolled; connected: true means the link to the management server is up right now.

The other proof: the key is gone

sudo ls -l /etc/muxen/eagle.key

On an enrolled boat this file does not exist. Every path that ends in "this boat is on the network" deletes it, including the two already-connected short-circuits. A key still sitting there means enrolment has not completed yet.

This catches people out, so it is worth saying plainly: an empty /etc/muxen is what success looks like. See The setup key.

Running it by hand

The script takes no options and no arguments; everything it needs comes from constants inside it and from the state of the local NetBird client. It is safe to run repeatedly.

sudo systemctl stop muxen-eagle
sudo /usr/bin/muxen-eagle-init ; echo "exit $?"

Its exit status is the whole diagnosis:

Exit	Meaning
0	enrolled, or already was
1	the netbird daemon did not answer — retryable, try again shortly
78	no usable setup key and not enrolled. Permanent; see The setup key
other	a netbird, jq or systemctl command failed; its own status is passed through

To point it at a key somewhere else — useful on a bench, never in production — set MUXEN_EAGLE_KEY_FILE:

sudo MUXEN_EAGLE_KEY_FILE=/tmp/test.key /usr/bin/muxen-eagle-init

Where to go next

• What the script decides, and in what order — Enrolment
• Where the setup key comes from and why it disappears — The setup key
• When something does not work — Troubleshooting
• The exhaustive lookup surface — Reference