Guides
Remote shell for Yocto and Buildroot devices
A static agent with no libc, BusyBox init and read-only root filesystems.
The agent is one static Go binary: no libc, no Python, no package manager, Linux 3.2 or newer. That makes it easy to drop into a Yocto or Buildroot image without a recipe for its dependencies.
core-image-minimal and core-image-full-cmdline, qemuarm64) under emulation, not yet on a real board. Buildroot and the read-only layout below follow from the same code but haven't been run. If you try either, tell us at support@fieldhand.dev. See compatibility.On a writable image: the installer
With a writable root filesystem, the normal install command works. Without curl, use the No curl? Use wget command in the dashboard. The installer registers a systemd service if there is one, and otherwise adds a respawn line to /etc/inittab, which both BusyBox init and sysvinit restart when the agent exits. The log goes to /var/log/fieldhand.log.
wget doesn't check HTTPS certificates. Install from a network you trust, or add curl to the image. Updates after install are checked against our release signature.In the image: binary and first-boot enrollment
To ship the agent inside the image, download the binary for your CPU (amd64, arm64, armv7, armv6 or 386) at build time:
https://api.fieldhand.dev/dl/fieldhand-linux-arm64
Put it in your rootfs overlay (Buildroot BR2_ROOTFS_OVERLAY) or install it from a recipe (Yocto). Then enroll on first boot with a fleet token, and never bake an already enrolled agent.json: every clone would share one device key.
# /etc/inittab (BusyBox init) ::sysinit:/bin/sh -c '[ -f /etc/fieldhand/agent.json ] || /usr/local/bin/fieldhand enroll --token fhe_…' ::respawn:/bin/sh -c 'exec /usr/local/bin/fieldhand run >>/var/log/fieldhand.log 2>&1'
A sysinit line runs before the network is up on many images. If enrollment fails there, run it from your network script instead, after the interface has an address.
Read-only root filesystem
The agent writes two things: its key at enrollment, and a new binary when it updates itself. Point both at a writable partition. Both enroll and run take --config, and the updater follows a symlink to the real binary, so it swaps the file on the writable side:
# in the image ln -s /data/fieldhand/fieldhand /usr/local/bin/fieldhand # on first boot: copy the shipped binary to /data/fieldhand/fieldhand, then fieldhand enroll --config /data/fieldhand/agent.json --token fhe_… # the service fieldhand run --config /data/fieldhand/agent.json
If you'd rather update the agent with your own image updates (Mender, RAUC, SWUpdate), pause automatic updates for the workspace. See pausing updates.
Something wrong or missing on this page? Tell us.