Orbit and osquery

Orbit and osquery enroll with the Orbit agent secret, then use a per-host node key. The server supports the Fleet route and response shapes used by both clients.

Configure Orbit

Create a host enrollment secret from Hosts > Enroll Hosts or the osquery overview. Orbit and direct osquery enrollment use the same secret.

Build the macOS package without embedding the server URL or enrollment secret:

fleetctl package --type=pkg --use-system-configuration --enable-scripts

Deploy the package with the fleetd configuration profile below. Replace the example URL and secret before deployment.

fleetd.mobileconfig

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>EnrollSecret</key>
      <string>REPLACE_WITH_SECRET</string>
      <key>FleetURL</key>
      <string>https://woodstar.example.com</string>
      <key>EnableScripts</key>
      <true/>
      <key>PayloadDisplayName</key>
      <string>fleetd</string>
      <key>PayloadIdentifier</key>
      <string>com.fleetdm.fleetd.config</string>
      <key>PayloadType</key>
      <string>com.fleetdm.fleetd.config</string>
      <key>PayloadUUID</key>
      <string>476F5334-D501-4768-9A31-1A18A4E1E807</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
    </dict>
  </array>
  <key>PayloadDescription</key>
  <string>Configures fleetd for device management.</string>
  <key>PayloadDisplayName</key>
  <string>Woodstar - fleetd</string>
  <key>PayloadIdentifier</key>
  <string>com.example.woodstar.fleetd</string>
  <key>PayloadOrganization</key>
  <string>Example Organization</string>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>0C6AFB45-01B6-4E19-944A-123CD16381C7</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

--enable-scripts makes script execution part of the package. EnableScripts also enables it through the macOS fleetd profile for stock Orbit versions that support dynamic script configuration. A host is eligible for policy remediation only after orbit_info reports scripts enabled and the host has an active Orbit enrollment.

Orbit allows one script execution timeout for all scripts received in a config response. Set WOODSTAR_ORBIT_SCRIPT_EXECUTION_TIMEOUT to a Go duration in whole-second increments, such as 30m or 1800s. It defaults to 5m and accepts values from 1s through 5h.

Optional end-user mapping

Replace $EMAIL with the user-email variable supported by your MDM. Orbit reads the inner com.fleetdm.fleet.mdm.apple.mdm preference domain exactly as shown.

fleetd-user.mobileconfig

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>EndUserEmail</key>
      <string>$EMAIL</string>
      <key>PayloadDisplayName</key>
      <string>fleetd user mapping</string>
      <key>PayloadIdentifier</key>
      <string>com.fleetdm.fleet.mdm.apple.mdm</string>
      <key>PayloadType</key>
      <string>com.fleetdm.fleet.mdm.apple.mdm</string>
      <key>PayloadUUID</key>
      <string>29713130-1602-4D27-90C9-B822A295E44E</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
    </dict>
  </array>
  <key>PayloadDescription</key>
  <string>Maps the assigned MDM user to a managed host.</string>
  <key>PayloadDisplayName</key>
  <string>Woodstar - fleetd user</string>
  <key>PayloadIdentifier</key>
  <string>com.example.woodstar.fleetd-user</string>
  <key>PayloadOrganization</key>
  <string>Example Organization</string>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>9A11B43D-395C-4377-8EDB-870551531B41</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

See Mutual TLS to include a client certificate and key in the fleetd package.

Orbit routes

Method	Path	Purpose
POST	/api/fleet/orbit/enroll	Enroll and return a node key
POST	/api/fleet/orbit/config	Return configuration and queued work
POST	/api/fleet/orbit/scripts/request	Claim one script execution
POST	/api/fleet/orbit/scripts/result	Report a script result
PUT	/api/fleet/orbit/device_mapping	Record the assigned user email
POST	/api/fleet/orbit/device_token	Rotate the device token
HEAD	/api/fleet/orbit/ping	Check the server
HEAD	/api/latest/fleet/device/{token}/ping	Validate a device token

osquery routes

Method	Path	Purpose
POST	/api/v1/osquery/enroll	Enroll and return a node key
POST	/api/v1/osquery/config	Return schedule and client options
POST	/api/v1/osquery/distributed/read	Return queued queries
POST	/api/v1/osquery/distributed/write	Receive distributed-query results
POST	/api/v1/osquery/log	Receive scheduled report results

An invalid node key tells osquery to enroll again. The server disables file carving and uses TLS-only osquery logging at error severity so scheduled report failures can replace stale results.

Distributed results update host details, software inventory, dynamic labels, policies, reports, and active live queries.