Devices
Devices
Devices is your fleet of machines. Each enrolled machine polls MaxSuite for work, runs the jobs it is able to run, and reports back. The module can also read machines managed by a FleetDM MDM, and run scripts on them through it.
In the sidebar under Servers & apps → Devices. Needs: GitHub.
Other parts of MaxSuite use the fleet too. Edge installs its terminator on an enrolled machine, and Workspaces run commands on one.
Devices tab
Machines that have enrolled themselves and are polling for work. A device appears here after its first heartbeat. At the top are totals for Devices, Online and Offline. Each row shows the Device, its Status, its Load, what it Can do (its capabilities, such as docker or git) and when it was Last seen. With none, the page says "No devices enrolled".
On each row you can:
- Run…: give a Label (what this is for) and the Commands, one per line. The job is aimed at that machine and no other, and appears under Jobs. It is tried once only. Once a machine has claimed it, it cannot be undone from here.
- Drain: stop the machine taking new work, letting what it holds finish. Resume lets it take work again.
- New token: confirm with Reissue?. The new token is shown once, with Copy. Only a hash is stored, so a lost token is reissued rather than recovered. If you try to close the box before copying, you are asked first. The machine must get the new token before its next heartbeat.
- Remove: confirm with Remove?. Its record goes, and any work queued for it or running on it is marked failed. The machine itself is not touched. If it is still running, it is refused at its next heartbeat. Enrolling it again is a fresh start.
Enrol a machine
Nothing is created from this screen. A machine registers itself with your MaxSuite address, then polls for jobs. This keeps a machine's identity its own. Enrolling needs Manage devices.
On the machine, the node agent runs every job as a separate, unprivileged job user. A job never sees the machine's device token.
Jobs tab
Work queued for devices to claim. Each row shows the Job, its Status, Detail, Tries (attempts made out of those allowed), and when it was Queued and Finished. A job that is claimed but never finished is put back on the queue as stale, if it has tries left. With none, the tab says "No jobs".
MDM machines
Connecting a FleetDM instance, reading its machines and software, and running scripts through it are done by agents or through the API. The page has no screen for them yet. An MDM is connected with the name of a secret you saved under Named secrets, never by typing the token.
Who can do what
| Permission | In plain words |
|---|---|
View devices (devices:read) | See devices, jobs, MDM instances, their machines, software and script results. |
Manage devices (devices:write) | Enrol machines, run commands, queue jobs, drain and resume, verify, reissue tokens, requeue stale jobs and remove devices. |
Connect and manage MDM instances (devices:manage) | Connect, rename, test and disconnect an MDM, and run scripts on its machines. |
See People, roles and permissions.
What happens on its own
| Job | When | What it does |
|---|---|---|
requeue-abandoned | Every 5 minutes | Finds jobs nothing is running any more, because a machine stopped reporting or its worker restarted. It puts them back on the queue if they have tries left. |
verify-capabilities | Every 6 hours, at 23 minutes past | Asks machines nobody has checked lately to prove what they can do, and corrects their capability list from the answer. A machine reimaged overnight, or one whose docker stopped working, is caught this way rather than by failing jobs. |
Needs
- GitHub switched on.
What agents can do
Reads run straight away. Everything else asks a person first unless a rule on Approvals allows it. Queueing a job, running commands and removing devices remove or overwrite things. Running an MDM script reaches outside. See Agents and approvals.
See the fleet (read-only):
devices.list: devices, what each can do, where it answers and when it was last heard from.devices.jobs: jobs, for one device or one status.
Run work (asks first):
devices.enqueuequeues work for any device that can run it.devices.runOnruns shell commands on one named device.devices.verifyasks a machine to prove its capabilities.
Look after the fleet (asks first):
devices.drainstops a device taking new work;devices.undrainputs it back to work.devices.requeueStalerecovers jobs nothing is running any more.devices.removetakes a device out of the fleet.
MDM, read (read-only):
devices.mdm: MDM instances and whether each answers.devices.mdmHosts: the machines an MDM knows about, read live.devices.mdmHost: everything one MDM machine reports.devices.mdmSoftware: what is installed on one MDM machine.devices.mdmScriptResult: what a queued script did.
MDM, change (asks first; needs Connect and manage MDM instances):
devices.mdmConnectconnects an MDM using the name of a saved secret.devices.mdmUpdaterenames a connection or changes its address. The stored token goes to the new address, so a person is always asked.devices.mdmTestchecks that an MDM answers.devices.mdmScriptruns a script on one of an MDM's machines.devices.mdmRemovedisconnects an MDM and deletes its stored token here. Nothing in the MDM changes.