Adding machines
Install the agent
Open Settings → Add a machine, choose a permission level and copy the command. Run it as root on the machine:
curl -fsSL https://fleetd.example.com/install.sh | sh -s -- --permission full
On OpenWrt without curl, use the wget version shown below it:
wget -qO- https://fleetd.example.com/install.sh | sh -s -- --permission full
The script:
- detects systemd or OpenWrt procd and installs a service that restarts the agent if it exits;
- downloads the newest signed agent for the machine's architecture from your server and checks that it runs;
- writes
/etc/fleetd/agent.yaml(mode 600) with your server's address and key, your release key, the permission level, and every signing key registered in the admin page; - prints the agent's fingerprint.
The same command works on any number of machines. Running it again on a machine that already has the agent only replaces the program and keeps the config, so it doubles as a manual upgrade.
Options
| Option | Meaning |
|---|---|
--permission monitor|allowlist|full | What signed commands may do here (default monitor) |
--server URL | Agent endpoint, e.g. ws://10.0.0.1:8480/agent/ws on a private network |
--signer KEY | Trust an extra signing key; repeatable. Registered keys are always included |
Approve or reject
The new machine appears under Machines → Waiting for approval with its hostname, source IP and fingerprint. Approve it only if the fingerprint matches what the installer printed (or what fleetd-agent fingerprint prints on the machine). Until then, nothing it sends is stored and it receives no commands.
After approval the agent reconnects within a minute and starts reporting.
Reject machines you do not recognise. Their key goes on a block list and further connections are refused at the handshake. Rejected machines are listed under Settings → Rejected machines, where you can unblock them.
Tips
Anyone who can reach your server can ask to be approved, so at most 50 machines can wait at once. Approval is what grants access, which is why checking the fingerprint matters.
Permission levels
Each agent's permission level is in its own /etc/fleetd/agent.yaml. The server cannot change it.
| Level | Allows |
|---|---|
monitor | Only metrics. Every command and terminal is refused |
allowlist | Only actions named in the agent's config, with fixed arguments |
full | Any command as root, and the web terminal. Still only when signed by a trusted key |
An allowlist looks like this:
permission: allowlist
allowlist:
restart-nginx: [systemctl, restart, nginx]
reload-wireguard: [systemctl, reload, wg-quick@wg0]
Restart the agent after editing its config: systemctl restart fleetd-agent, or /etc/init.d/fleetd-agent restart on OpenWrt.
Trusted signing keys
trusted_signers in the agent config lists the admin keys whose commands it accepts. The installer fills it from the keys registered in Settings → Signing keys. When you add a key later (a new browser, another admin), add it to machines installed earlier:
trusted_signers:
- <existing public key>
- <new public key>
To revoke a key, remove it from this list on every machine. Deleting it in the admin page only keeps it out of future installs.
Rename and delete
Click the pencil next to a machine's name to rename it. Delete machine removes its record and history. If the agent is still running, the machine shows up again as waiting for approval; uninstall the agent first, or reject it, to remove it for good.
Uninstall the agent
systemctl disable --now fleetd-agent
rm -f /etc/systemd/system/fleetd-agent.service /usr/local/bin/fleetd-agent*
rm -rf /etc/fleetd /var/lib/fleetd
/etc/init.d/fleetd-agent disable; /etc/init.d/fleetd-agent stop
rm -f /etc/init.d/fleetd-agent /usr/bin/fleetd-agent*
rm -rf /etc/fleetd
sed -i '\#^/etc/fleetd/$#d' /etc/sysupgrade.conf