[API design] Install software and run setup script when Macs boot

articles/automatic-software-install-in-fleet.md

@@ -21,7 +21,7 @@ Fleet allows its users to upload trusted software installation files to be insta
 Current supported software deployment formats:
 - macOS: .pkg
 - Windows: .msi, .exe
-- Linux: .deb
+- Linux: .deb, .rpm
 
 Coming soon:
 - VPP for iOS and iPadOS

articles/deploy-software-packages.md

@@ -46,7 +46,7 @@ To access and manage software in Fleet:
 
 * Click the “Add Software” button in the top right corner, and a dialog will appear.
 
-* Choose a file to upload. `.pkg`, `.msi`, `.exe`, and `.deb` files are supported.
+* Choose a file to upload. `.pkg`, `.msi`, `.exe`, `.rpm`, and `.deb` files are supported.
 
 > Software installer uploads will fail if Fleet is unable to extract information from the installer package such bundle ID and version number.
 

docs/Configuration/yaml-files.md

@@ -84,6 +84,8 @@ policies:
   platform: darwin
   critical: false
   calendar_event_enabled: false
+  run_script:
+    path: "../lib/disable-guest-account.sh"
 - name: Firefox on Linux installed and up to date
   platform: linux
   description: "This policy checks that Firefox is installed and up to date."
@@ -93,7 +95,7 @@ policies:
     package_path: "../lib/linux-firefox.deb.package.yml"
 ```
 
-`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`
+`default.yml` (for policies that neither install software nor run scripts), `teams/team-name.yml`, or `teams/no-team.yml`
 
 ```yaml
 policies:
@@ -319,7 +321,7 @@ The `software` section allows you to configure packages and Apple App Store apps
 Software for hosts that belong to "No team" have to be defined in `teams/no-team.yml`.
 Software can also be specified in separate files in your `lib/` folder.
 
-- `packages` is a list of software packages (.pkg, .msi, .exe, or .deb) and software specific options.
+- `packages` is a list of software packages (.pkg, .msi, .exe, .rpm, or .deb) and software specific options.
 - `app_store_apps` is a list of Apple App Store apps.
 
 #### Example

docs/Contributing/API-for-contributors.md

@@ -6,6 +6,7 @@
 - [Live query](#live-query)
 - [Trigger cron schedule](#trigger-cron-schedule)
 - [Device-authenticated routes](#device-authenticated-routes)
+- [Orbit-authenticated routes](#orbit-authenticated-routes)
 - [Downloadable installers](#downloadable-installers)
 - [Setup](#setup)
 - [Scripts](#scripts)
@@ -1507,13 +1508,23 @@ NOTE: when updating a policy, team and platform will be ignored.
       "description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
       "resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
       "platform": "darwin",
-      "critical": true
-    }
+      "critical": true,
+      "script_id": 123
+    },
+    {
+      "name": "Is Adobe Acrobat installed and up to date?",
+      "query": "SELECT 1 FROM apps WHERE name = 'Adobe Acrobat Reader.app' AND version_compare(bundle_short_version, '23.001.20687') >= 0;",
+      "team": "Workstations",
+      "description": "Checks to make sure that Adobe Acrobat is installed and up to date.",
+      "platform": "darwin",
+      "critical": false,
+      "software_title_id": 12
+    },
   ]
 }
 ```
 
-The field `critical` is available in Fleet Premium.
+The fields `critical`, `script_id`, and `software_title_id` are available in Fleet Premium.
 
 ##### Default response
 
@@ -1825,7 +1836,7 @@ If the `name` is not already associated with an existing team, this API route cr
         }
       },
       "scripts": ["path/to/script.sh"],
-      "software": { 
+      "software": {
         "packages": [
           {
             "url": "https://cdn.zoom.us/prod/5.16.10.26186/x64/ZoomInstallerFull.msi",
@@ -1839,7 +1850,7 @@ If the `name` is not already associated with an existing team, this API route cr
             "app_store_id": "12464567",
           }
         ]
-      }  
+      }
     }
   ]
 }
@@ -3176,6 +3187,83 @@ Notifies the server about an agent error, resulting in two outcomes:
 
 ---
 
+## Orbit-authenticated routes
+
+- [Get the status of a device in the setup experience](#get-the-status-of-a-device-in-the-setup-experience)
+
+
+### Get the status of a device in the setup experience
+
+`POST /api/fleet/orbit/setup_experience/status`
+
+##### Parameters
+
+| Name  | Type   | In   | Description                        |
+| ----- | ------ | ---- | ---------------------------------- |
+| orbit_node_key | string | body | The Orbit's node key for authentication. |
+| force_release | boolean | body | Force a host release from ADE flow, in case the setup is taking too long. |
+
+
+##### Example
+
+`POST /api/v1/fleet/device/8b49859b-1ffa-483d-ad27-85b30aa3c55f/setup_experience/status`
+
+##### Request body
+
+```json
+{
+  "orbit_node_key":"FbvSsWfTRwXEecUlCBTLmBcjGFAdzqd/",
+  "force_release":false
+}
+```
+
+##### Default response
+
+`Status: 200`
+
+```json
+{
+    "setup_experience_results": {
+        "script": {
+            "name": "setup_script.sh",
+            "status": "success",
+            "execution_id": "b16fdd31-71cc-4258-ab27-744490809ebd"
+        },
+        "software": [
+            {
+                "name": "Zoom Workplace",
+                "status": "success",
+                "software_title_id": 957
+            },
+            {
+                "name": "Bear: Markdown Notes",
+                "status": "success",
+                "software_title_id": 287
+            },
+            {
+                "name": "Evernote",
+                "status": "success",
+                "software_title_id": 1313
+            }
+        ],
+        "configuration_profiles": [
+            {
+                "profile_uuid": "ae6a9efd5-9166-11ef-83af-0242ac12000b",
+                "name": "Fleetd configuration",
+                "status": "verified"
+            },
+            {
+                "profile_uuid": "ae6aa8108-9166-11ef-83af-0242ac12000b",
+                "name": "Fleet root certificate authority (CA)",
+                "status": "verified"
+            }
+        ],
+        "org_logo_url": ""
+    }
+}
+
+```
+
 
 ## Downloadable installers
 
@@ -3336,7 +3424,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re
 
 ##### Default response
 
-`Status: 204`
+`Status: 200`
+
+```json
+{
+  "scripts": [
+    {
+      "team_id": 3,
+      "id": 6690,
+      "name": "Ensure shields are up"
+    },
+    {
+      "team_id": 3,
+      "id": 10412,
+      "name": "Ensure flux capacitor is charged"
+    }
+  ]
+}
+```
 
 ### Run live script
 

docs/Contributing/research/mdm/software-version-extract.md

@@ -15,6 +15,7 @@
 | `.pkg` | Low        | High     | -                                           |
 | `.exe` | Low        | High     | -                                           |
 | `.deb` | Low        | High     | -                                           |
+| `.rpm` | Low        | High     | -                                           |
 
 More details:
 

docs/Get started/FAQ.md

@@ -80,7 +80,7 @@ Fleet supports the following operating system versions on hosts.
 | Linux   | CentOS 7.1+,  Ubuntu 20.04+, Fedora 38+ |
 | ChromeOS | 112.0.5615.134+                        |
 
-While Fleet may still function partially or fully with OS versions older than those above, Fleet does not actively test against unsupported versions and does not pursue bugs on them. 
+While Fleet may still function partially or fully with OS versions older than those above, Fleet does not actively test against unsupported versions and does not pursue bugs on them.
 
 ## Some notes on compatibility
 
@@ -91,10 +91,12 @@ If a table is not available for your host, Fleet will generally handle things be
 
 ### Linux
 
-Fleet Desktop is supported on Ubuntu and Fedora. 
+Fleet Desktop is supported on Ubuntu and Fedora.
 
 Fedora requires a [gnome extension](https://extensions.gnome.org/extension/615/appindicator-support/) and Google Chrome for Fleet Desktop.
 
+Fleet's default (un)install scripts use `apt-get` for Debian-based distributions, and `dnf` for Red Hat-based distributions. To install packages on CentOS versions prior to 8, either add `dnf` or edit install and uninstall scripts to use the `yum` or `rpm` command.
+
 On Ubuntu, Fleet Desktop currently supports Xorg as X11 server, Wayland is currently not supported. Ubuntu 24.04 comes with Wayland enabled by default. To use X11 instead of Wayland you can set `WaylandEnable=false` in `/etc/gdm3/custom.conf` and reboot.
 
 The `fleetctl package` command is not supported on DISA-STIG distribution.