# Fleet

Connect Fleet to Risotto so the support agent and the Assistant can look up a requestor's devices, get disk encryption keys, and lock, restart, or wipe devices

The Fleet integration lets Risotto read the devices that are mapped to a person in Fleet. The support agent and the Assistant use it to find a requestor's devices and their details while they work a ticket.

The connection also powers five Fleet tools: **Fleet Get Device Information**, **Fleet Get Disk Encryption Key**, **Fleet Lock Device**, **Fleet Restart Device**, and **Fleet Wipe Device**. Fleet-hosted and self-hosted Fleet servers both work.

## Prerequisites

- **Admin access to Fleet**, to create an API-only user
- A Fleet server that you can reach from the internet over HTTPS
- **Org Admin or Org Manager role in Risotto**
- **Fleet Premium**, only for the lock and wipe tools. A wipe of an Android device works without Premium.

## Setup

In Fleet:

1. Go to **Settings > Users** and click **Create user**.
2. Name the user "Risotto", select **API-only user**, and give it the **Maintainer** role. The lock, restart, and wipe tools need the **Maintainer** or **Admin** role for the team that the device is in.
3. Copy the user's **API token**. You can also create the user with `fleetctl user create --api-only`, which prints the token.
4. Copy the address you use to open Fleet, for example `https://fleet.example.com`.

In Risotto:

1. Go to **Settings > Integrations** and click the **Fleet** card.
2. On the **API-only user** card, click **Connect**.
3. Enter the **Server URL** and paste the **API Token**.
4. Click **Save**.

Risotto tests the connection before it saves. The server URL must be the public HTTPS address of your Fleet server. Risotto does not accept `localhost` or a private IP address.

## How device lookup works

Risotto searches Fleet for hosts by the requestor's email address. It keeps only the hosts that Fleet maps to exactly that email address, because the Fleet search also matches host names and serial numbers. A host that Fleet does not map to a person's email address does not show for that person.

## Fleet tools

To add a Fleet tool, select **Tools** in the sidebar, open the **Fleet** group, and click the tool. You can also open the **Tools** tab on **Settings > Integrations > Fleet**. Each tool uses the Fleet connection, so it has no credentials of its own.

Every Fleet tool has the option **Restrict to Requestor Only** (default: on). With the option on, the tool acts only on the devices of the ticket requestor. Turn it off to let your team act on other users' devices.

A new tool starts with **Requires Approval** on. Keep approval on for the lock and wipe tools, so that a person accepts each command before it runs.

The tools find a person's devices by the email address that Fleet maps to the device. If the person has more than one device, the agent asks which one, by name and model.

### Fleet Get Device Information

The tool lists the devices of a user, or returns the full details of one device. A new tool is named **Get Fleet Device Details**. The details include the device name, model, serial number, OS version, last check-in, platform, status, team, MDM status, and MDM server.

- **email_address** (optional): the user to look up. The default is the ticket requestor.
- **device_id** (optional): one device of that user.

The tool only reads. It does not change a device.

### Fleet Get Disk Encryption Key

The tool gets the disk encryption key that Fleet holds for a computer: the FileVault key of a Mac, the BitLocker key of a Windows PC, or the LUKS key of a Linux host. A new tool is named **Get Disk Encryption Key**. Phones, tablets, and Chromebooks have no key.

- **email_address** and **device_id** (optional): the same as in the device information tool.
- **Send via DM Only** (default: on): Risotto sends the key to the requestor in a direct message, not in the ticket thread. If Risotto cannot send the direct message, it does not post the key. The tool fails, and the agent escalates the ticket.

Fleet keeps a key only when its MDM for that platform is set up and disk encryption is on for the device's team. Fleet records each key read as an activity on the device.

### Fleet Lock Device

The tool locks a device of the requester. A new tool is named **Lock Device**. It needs Fleet Premium.

- **email_address** and **device_id** (optional): the same as in the device information tool.
- A Mac, iPhone, or iPad needs Fleet MDM on. A Windows or Linux host needs Fleet scripts on.
- Fleet queues the lock. The device locks the next time it checks in with Fleet. The agent tells the requester that the lock is queued, not that it is done.
- On a Mac, Fleet sets a 6-digit PIN to unlock it. Risotto does not get the PIN. An admin finds it in Fleet, on the host's page, under **Actions > Unlock**.
- A Linux host restarts about 10 seconds after it locks.

### Fleet Restart Device

The tool restarts a Mac, Windows PC, iPhone, or iPad of the requester. A new tool is named **Restart Device**. It does not need Fleet Premium.

- **email_address** and **device_id** (optional): the same as in the device information tool.
- Fleet restarts a device through its own MDM. The tool refuses a device that is not enrolled in Fleet MDM, for example a device that Microsoft Intune manages.
- The tool refuses Linux, Android, and ChromeOS devices.
- Fleet queues the restart. The device restarts the next time it checks in with Fleet. The requester loses unsaved work on the device.

### Fleet Wipe Device

The tool erases all data on a device and resets the device to factory settings. You cannot undo a wipe. A new tool is named **Wipe Device**. It needs Fleet Premium for every platform except Android.

- The tool works on Macs, iPhones, iPads, Windows PCs, Linux hosts, and Android devices. A Mac, iPhone, iPad, or Windows PC needs Fleet MDM on. A Linux host needs Fleet scripts on.
- On a Windows PC, the tool sends a full factory reset (`doWipe`), not the Fleet default (`doWipeProtected`), which can leave the PC unable to start.
- The agent first finds the device with the device information tool. Then it sends **device_id**, **device_name**, **model**, and **serial_number** (all required). The approver sees these values.
- After approval, Risotto compares the name, model, and serial number with the device in Fleet. If one value does not match, Risotto wipes nothing.
- **email_address** (optional): the same as in the device information tool.
- Fleet queues the wipe. The device erases its data the next time it checks in with Fleet.

### Tool errors

The agent gets a clear message when Fleet refuses a command, and the tool changes nothing:

| Fleet answer                      | What to do                                                                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| The command needs Fleet Premium   | Upgrade Fleet, or have the requester act on the device.                                                                                             |
| Fleet refused the command         | Give the API-only user the **Maintainer** or **Admin** role in Fleet, for the team that the device is in.                                           |
| Fleet no longer finds the device  | The host was deleted from Fleet.                                                                                                                    |
| Fleet could not act on the device | Turn on Fleet MDM (Mac, iPhone, iPad, Windows) or Fleet scripts (Windows, Linux) for the device. Another lock, unlock, or wipe can also be pending. |

## Runbook templates

On the **Runbooks** page, click **Browse templates** to start a runbook from one of these Fleet templates:

- **Fleet Disk Encryption Recovery Key Unlock**: sends the FileVault, BitLocker, or LUKS recovery key with **Fleet Get Disk Encryption Key**. It escalates the ticket when Fleet holds no key for the device, or when the user sees the normal sign-in screen.
- **Fleet Lost or Stolen Device**: finds the device and locks it. When the user confirms that the device was stolen or will not be recovered, it asks to wipe the device, and IT approves the wipe before it runs. The runbook always ends with an escalation to IT, so that IT can arrange a replacement.
- **Fleet Restart Device**: warns that unsaved work is lost, asks the user to confirm, and queues the restart. It escalates the ticket when Fleet cannot restart the device (Linux, Android, or no Fleet MDM), or when the device has not restarted after 15 minutes.

## More than one device management platform

You can connect Fleet together with Jamf Pro, Microsoft Intune, Iru (formerly Kandji), or Workspace ONE. The support agent and the Assistant look up a requester's devices in every connected platform, in this order: Jamf Pro, Microsoft Intune, Iru (formerly Kandji), Workspace ONE, then Fleet. They show the devices of all platforms together, each with the platform that reported it. If one platform does not respond, the agent still gets the devices from the others.

## Troubleshooting

### Saving fails: Fleet refused the API token

Fleet did not accept the token. Check that you copied the token of an
API-only user and that the user is still active in Fleet.

### Saving fails: Fleet could not be reached

Risotto could not connect to the server URL. Check the URL, and check that
the server is reachable from the internet over HTTPS.

### Saving fails: The server did not answer like a Fleet server

The server URL points to a server that is not Fleet. Use the address you use
to open Fleet in your browser.

### Saving fails: Fleet server URL must be the public HTTPS address of your Fleet server

The URL is `localhost`, a private IP address, or not HTTPS. Enter the public
HTTPS address of your Fleet server.

## Related

- [Jamf Pro](https://www.tryrisotto.com/docs/integrations/device-management/jamf-pro)
- [Microsoft Intune](https://www.tryrisotto.com/docs/integrations/device-management/microsoft-intune)
- [Workspace ONE](https://www.tryrisotto.com/docs/integrations/device-management/workspace-one)

Source: https://www.tryrisotto.com/docs/integrations/device-management/fleet
