From f6d8bcc7320bf5c6113067ae3fb76924e4efd56f Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Thu, 7 Dec 2023 14:08:04 -0500 Subject: [PATCH] Docs for Windows MDM commands (#15371) - Update "Commands" doc page to cover Windows MDM commands - Remove more doc content than added --- docs/Using Fleet/MDM-commands.md | 94 ++++++++++++-------------------- 1 file changed, 36 insertions(+), 58 deletions(-) diff --git a/docs/Using Fleet/MDM-commands.md b/docs/Using Fleet/MDM-commands.md index 73e96323c1..8cf7928748 100644 --- a/docs/Using Fleet/MDM-commands.md +++ b/docs/Using Fleet/MDM-commands.md @@ -1,28 +1,27 @@ # Commands -In Fleet you can run MDM commands to take some action on your macOS hosts, like restart the host, remotely. - -If a host is offline when you run a command, the host will run the command the next time it comes online. +In Fleet you can run MDM commands to take action on your macOS and Windows hosts, like restarting the host, remotely. ## Custom commands You can run custom commands and view a specific command's results using the `fleetctl` command-line interface. To run a custom command, we will do the following steps: + 1. Create a `.xml` with the request payload 2. Choose a target host 3. Run the command using `fleetctl` 4. View our command's results using `fleetctl` -### Step 1: create a `.xml` file +### Step 1: Create an XML file -You can run any command supported by Apple's MDM protocol as a custom command in Fleet. To see the list of possible commands, head to [Apple's Commands and Queries documentation](https://developer.apple.com/documentation/devicemanagement/commands_and_queries). +You can run any command supported by [Apple's MDM protocol](https://developer.apple.com/documentation/devicemanagement/commands_and_queries) or [Microsoft's MDM protocol](https://learn.microsoft.com/en-us/windows/client-management/mdm/). -> The "Erase a device" and "Lock a device" commands are only available in Fleet Premium +> The lock and wipe commands are only available in Fleet Premium -Each command has example request payloads in XML format. For example, if we want to restart a host, we'll use the "Restart a Device" request payload documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/restart_a_device#3384428). +For example, to restart a macOS host, we'll use the "Restart a Device" command documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/restart_a_device#3384428). -To run the "Restart a device" command, we'll need to create a `restart-device.xml` file locally and copy and paste the request payload into this `.xml` file: +First, we'll need to create a `restart-device.xml` file locally with this payload: ```xml @@ -34,90 +33,69 @@ To run the "Restart a device" command, we'll need to create a `restart-device.xm RequestType RestartDevice - CommandUUID - 0001_RestartDevice ``` -### Step 2: choose a target host +To restart a Windows host, we'll use the "Reboot" command documented by Microsoft [here](https://learn.microsoft.com/en-us/windows/client-management/mdm/reboot-csp). -To run a command, we need to specify a target host by hostname. Commands can only be run on a single host in Fleet. +The `restart-device.xml` file will have this payload instead: -To find a host's hostname, choose the "Fleet UI" or "fleetctl" method and follow the steps below. +```xml + + + + ./Device/Vendor/MSFT/Reboot/RebootNow + + + null + text/plain + + + + +``` -Fleet UI: +### Step 2: Choose a target host -1. Head to the **Hosts** page in Fleet and find your target host. -2. Make sure the **Hostname** column is visible (select **Edit columns** if not) and find your host's hostname. You'll need this hostname to run the command. - -> A host must be enrolled to Fleet and have MDM turned on to run a command against it. - -`fleetctl` CLI: +To run a command, we need to specify a target host by hostname. 1. Run the `fleetctl get hosts --mdm` command to get a list of hosts that are enrolled to Fleet and have MDM turned on. -2. Find your host's hostname. You'll need this hostname to run the command. +2. Find your target host's hostname. You'll need this hostname to run the command. -### Step 3: run the command +### Step 3: Run the command 1. Run the `fleetctl mdm run-command --payload=restart-device.xml --host=hostname ` command. -> Replace the --payload and --host flags with your `.xml` file and hostname respectively. -2. Look at the on-screen information. In the output you'll see the command required to see results. Be sure to copy this command. If you don't, it will be difficult to view command results later. +> Replace the --payload and --host flags with your XML file and hostname respectively. + +2. Look at the on-screen information. In the output you'll see the command to see results. ### Step 4: View the command's results 1. Run the `fleetctl get mdm-command-results --id=` - 2. Look at the on-screen information. -Example output: - -```sh -$ fleetctl get mdm-command-results -id 333af7f8-b9a4-4f62-bfb2-f7488fbade21 -+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+ -| ID | TIME | TYPE | STATUS | HOSTNAME | RESULTS | -+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+ -| 333af7f8-b9a4-4f62-bfb2-f7488fbade21 | 2023-04-04T21:29:29Z | RestartDevice | Acknowledged | xyz-macbook-air.lan | | -| | | | | | CommandUUID | -| | | | | | 333af7f8-b9a4-4f62-bfb2-f7488fbade21 | -| | | | | | Status | -| | | | | | Acknowledged UDID | -| | | | | | 3A529CD6-2154-55EA-9AB7-EB13A43D9F5E | -| | | | | | | -+--------------------------------------+----------------------+----------------+--------------+---------------------+---------------------------------------------------------+ -``` - ## List recent commands -You can view the list of the 1,000 latest commands using "fleetctl": +You can view a list of the 1,000 latest commands: 1. Run `fleetctl get mdm-commands` 2. View the list of latest commands, most recent first, along with the timestamp, targeted hostname, command type, execution status and command ID. -Example output: +The command ID can be used to view command results as documented in [step 4 of the previous section](#step-4-view-the-commands-results). -```sh -$ fleetctl get mdm-commands -+--------------------------------------+----------------------+--------------------------+--------------+------------------------+ -| ID | TIME | TYPE | STATUS | HOSTNAME | -+--------------------------------------+----------------------+--------------------------+--------------+------------------------+ -| 024fb3b9-cd8a-40a6-8dd7-6c155f488fd1 | 2023-04-12T18:19:10Z | RestartDevice | Acknowledged | iMac-Pro.local | -+--------------------------------------+----------------------+--------------------------+--------------+------------------------+ -| 87dc6325-8bc0-4fc8-9a2f-3901c535456e | 2023-04-12T18:15:01Z | DeviceLock | Acknowledged | iMac-Pro.local | -+--------------------------------------+----------------------+--------------------------+--------------+------------------------+ -``` +The possible statuses for macOS hosts are the following: -The command ID can be used to view command results as documented in [step 4 of the previous section](#step-4-view-the-commands-results). The possible status values are: * Pending: the command has yet to run on the host. The host will run the command the next time it comes online. * NotNow: the host responded with "NotNow" status via the MDM protocol: the host received the command, but couldn’t execute it. The host will try to run the command the next time it comes online. * Acknowledged: the host responded with "Acknowledged" status via the MDM protocol: the host processed the command successfully. * Error: the host responded with "Error" status via the MDM protocol: an error occurred. Run the `fleetctl get mdm-command-results --id= - +