One Go Agent on Linux and OpenWrt: Fleetd Deployment Choices

Installing an agent on a cloud server and a home router may appear to be the same task at first glance. However, when it comes to long-term operation, there are several factors to consider. For instance, who should start the agent after a reboot? How will the agent handle a situation where the network is not yet ready? Where should the logs be stored?

Will the device identity and command records be preserved in case of a restart? Fleetd takes care of Linux servers as well as OpenWrt and iStoreOS routers. In this article, we will focus on making the agent a persistent and troubleshootable system service. The implementation being discussed is v0.3.0 of Fleetd. This version supports amd64 and arm64 architectures, with both systemd and OpenWrt's procd as installers. This does not mean that every Linux-based device is supported.

One key aspect of Fleetd is that it is built using a single codebase with architecture-specific binaries. This means that both Linux-based servers and routers can use the same agent, which is created for Linux and produces executables for both 64-bit amd64 and arm64 architectures. It is important to note that an amd64 executable cannot run on arm64, and vice versa.

The installer will only support certain architectures, such as x86_64, amd64, amd64, and arm64. OpenWrt supports additional devices, including MIPS and 32-bit ARM, but these are not covered by this installation path.

The main benefit of using a single executable is that it reduces the runtime preparation required for the agent to run. The agent is built with CGO\_ENABLED=0, which reduces its dependence on the target system's dynamically linked C environment. This means that the agent does not require a Go compiler, Node.js, or Python runtime to start running on the target machine.

However, it is important to note that the agent still needs a network connection, a working HTTPS certificate trust environment, writable configuration storage, and the required kernel facilities.

During installation, the installer follows a specific sequence of steps. First, it requires root access and identifies the CPU architecture. Next, it detects whether the system is running systemd or an OpenWrt procd environment. After that, it downloads the appropriate agent from the Fleetd server and checks its version to ensure that the executable can start.

The installer then creates or preserves the configuration file, installs the binary, and registers and starts the service. Finally, it prints the device fingerprint for verification and approval in the dashboard.

It is worth noting that downloading only proves that a file has arrived, and running the version command checks only that the executable can start. Neither of these steps can guarantee that long-lived connections, collection, permissions, boot startup, or firmware-upgrade recovery work correctly. The installer prefers to use curl but will fall back to wget if necessary. On a minimal system, it is important to check that the installed tool supports the required HTTPS requests.

Once the agent is installed, the existing service manager (systemd on Linux servers and OpenWrt procd) takes care of the process lifecycle. The agent is typically installed in /usr/local/bin/fleetd-agent on Linux servers and /usr/bin/fleetd-agent on OpenWrt. The configuration file is located in /etc/fleetd/agent.yaml on both operating systems. The systemd unit file on Linux servers and the init file on OpenWrt define the agent's startup settings, including the service's restart behavior and startup order.

By using a single executable and having the service manager handle process lifecycle, Fleetd simplifies the deployment and maintenance of the agent on both Linux servers and OpenWrt routers. This approach helps ensure that the agent can run persistently and be easily troubleshooted in case of issues.