Welcome to the documentation for Fleet, the lightweight telemetry platform for servers and workstations.
Install osquery and Fleet
Get startedCan't find what you need?
SupportmacOS 12 (Monterey) and higher.
MDM features require Apple's Push Notification service (APNs) to control and secure Apple devices. This guide will walk you through how to generate and upload a valid APNs certificate to Fleet in order to use Fleet's MDM features.
Automated Device Enrollment allows Macs to automatically enroll to Fleet when they are first set up. This guide will also walk you through how to connect Apple Business Manager (ABM) to Fleet.
Note you are only required to connect Apple Business Manager (ABM) to Fleet if you are using Automated Device Enrollment AKA Device Enrollment Program (DEP) AKA "Zero-touch."
To use Fleet's MDM features you need to have:
Apple uses APNs to authenticate and manage interactions between Fleet and the host.
This section will show you how to:
For the MDM protocol to function, we need to generate the four following files:
The APNs certificates serve as authentication between Fleet and Apple, while the SCEP certificates serve as authentication between Fleet and hosts.
Use either of the following methods to generate the necessary files:
Run the following command to download three files and send an email to you with an attached CSR file.
fleetctl generate mdm-apple --email <email> --org <org>
Important Take note of the Apple ID you use to sign into Apple Push Certificates Portal. You'll need to use the same Apple ID when renewing your APNs certificate.
Restart the Fleet server with the contents of the APNs certificate, APNs private key, SCEP certificate, and SCEP private key in the following environment variables:
You do not need to provide the APNs CSR which was emailed to you.
Use either of the following methods to confirm that Fleet is set up. You should see information about the APNs certificate such as serial number and renewal date.
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
fleetctl get mdm-apple
Important Apple requires that APNs certificates are renewed anually.
- If your certificate expires, you will have to turn MDM off and back on for all macOS hosts.
- Be sure to use the same Apple ID from year-to-year. If you don't, you will have to turn MDM off and back on for all macOS hosts.
This section will guide you through how to:
Use either of the following methods to see your APNs certificate's renewal date and other important information:
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
fleetctl get mdm-apple
Run the following command in fleetctl
. This will download three files and send an email to you with an attached CSR file. You may ignore the SCEP certificate and SCEP key as you do not need these to renew APNs.
fleetctl generate mdm-apple --email <email> --org <org>
Restart the Fleet server with the contents of the APNs certificate and APNs private key in following environment variables:
You do not need to provide the APNs CSR which was emailed to you.
Use either of the following methods to confirm that Fleet is set up:
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
Follow the on-screen instructions in the Apple Push Certificates Portal section.
Run the following command. You should see information about the new APNs certificate such as serial number and renewal date.
fleetctl get mdm-apple
The SCEP certificates generated by Fleet and uploaded to the environment variables expire every 10 years. To renew them, regenerate the keys and update the relevant environment variables.
Available in Fleet Premium
By connecting Fleet to ABM, Macs purchased through Apple or an authorized reseller can automatically enroll to Fleet when they’re first unboxed and set up by your end user.
This section will guide you through how to:
User either of the following methods to generate a certificate and private key pair. This pair is how Fleet authenticates itself to ABM:
fleetctl generate mdm-apple-bm
Create an MDM server record in ABM which represents Fleet:
In the details page of the newly created server, click Download Token at the top. You should receive a .p7m
file.
With the three generated files, we now give them to the Fleet server so that it can authenticate itself to ABM.
Restart the Fleet server with the contents of the server token, certificate, and private key in following environment variables:
Use either of the following methods to confirm that Fleet is set up correctly. You should see information about the ABM server token such as organization name and renewal date.
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
Navigate to the Apple Business Manager section.
fleetctl get mdm-apple
Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized reseller:
All automatically-enrolled hosts will be assigned to a default team of your choosing after they are unboxed and set up. The host will receive the configurations and behaviors set for that team. If no default team is set, then the host will be placed in "No Teams".
A host can be transferred to a new (not default) team before it enrolls. Learn how here. Transferring a host will automatically enforce the new team's settings when it enrolls.
Use either of the following methods to change the default team:
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
In the Apple Business Manager section, select the Edit team button next to Default team.
Choose a team and select Save.
Create a config
YAML document if you don't have one already. Learn how here. This document is used to change settings in Fleet.
Set the mdm.apple_bm_default_team
configuration option to the desired team's name.
Run the fleetctl apply -f <your-YAML-file-here>
command.
Some time after you purchase a Mac through Apple or an authorized reseller, but before it has been set up, the Mac will appear in ABM as in transit. When the Mac appears in ABM, it will also appear in Fleet with MDM status set to "Pending." After the new host is set up, the MDM Status will change to "On" and the host will be assigned to the default team.
Apple expires ABM server tokens certificates once every year or whenever the account that downloaded the token has their password changed.
Use either of the following methods to see your ABM renewal date and other important information:
Navigate to the Settings > Integrations > Mobile device management (MDM) page.
Look at the Apple Business Manager section.
fleetctl get mdm-apple
If you have configured Fleet with an Apple Business Manager server token for mobile device management (a Fleet Premium feature), you will eventually need to renew that token. As documented in the Apple Business Manager User Guide, the token expires after a year or whenever the account that downloaded the token has their password changed.
To renew the token:
If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the Fleet repo.