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

ChoiceWhat it does
RestartReboots each device after 3 seconds. Reports success before going down, then the device reconnects.
Upgrade packagesRuns 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 commandAnything 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

SettingMeaning
Canaries firstRun on this many devices first. The rest wait until the canaries finish.
Devices at onceHow many run at the same time after the canaries.
Stop if failures exceedShare of finished devices that may fail before the rest are skipped. 0% stops at the first failure.
Timeout per deviceThe command and everything it started are killed after this (10 seconds to 6 hours).
Offline devicesSkip 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.