Using Fieldhand
Fleet commands
Run a command on many devices, in waves, with each device's result.
Commands in the dashboard header runs one command on a set of devices: restart a service on every kiosk at a site, upgrade packages across the fleet, collect a log line from each gateway. Each device reports its exit code, how long it took and the last 16 KB of its output.
What you can run
| Choice | What it does |
|---|---|
| Restart | Reboots each device after 3 seconds. Reports success before going down, then the device reconnects. |
| Upgrade packages | Runs apt, apk, dnf, zypper or pacman without questions, keeping your config files. Waits up to 5 minutes for another apt to finish. Can use a lot of mobile data. |
| Your own command | Anything sh -c accepts, run as the shell user. Save it to reuse it. |
Shutdown is not a ready action on purpose: a powered-off device in the field can't be turned back on from here.
Choosing devices
Pick devices that carry any of a set of tags, individual devices, or both. Before you confirm, you see how many devices match and how many are offline.
Waves and stopping on failure
| Setting | Meaning |
|---|---|
| Canaries first | Run on this many devices first. The rest wait until the canaries finish. |
| Devices at once | How many run at the same time after the canaries. |
| Stop if failures exceed | Share of finished devices that may fail before the rest are skipped. 0% stops at the first failure. |
| Timeout per device | The command and everything it started are killed after this (10 seconds to 6 hours). |
| Offline devices | Skip them, or run when they reconnect within 1 hour, 24 hours or 3 days. |
A non-zero exit code counts as a failure, and so do timeouts and runs with no result. Cancel a command to stop it: devices that haven't started skip it, and running ones are killed.
Scheduling
Under When, run a command once at a later time, every day or every week, in your time zone. Devices are chosen again at each run, so a device tagged after you scheduled it is included. Scheduled commands are listed at the top of Commands, where you can pause or delete them; each run shows up as a normal command with its results. A schedule stops if the admin who created it leaves the workspace.
When the connection drops
A command keeps running on the device if its link drops, and the device reports the result when it reconnects. If the agent itself restarts during a command (the device rebooted, or the command restarted Fieldhand), that run shows no result.
Safety
- Only admins and the owner can run commands across devices.
- Commands that can take devices down (reboot, shutdown, rm -r, mkfs, systemctl stop, and similar) ask you to type the number of devices before they start.
- Every command, who ran it and each device's result stay in the Commands list.
Something wrong or missing on this page? Tell us.