Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: VPP policy automations #25593

Merged
merged 3 commits into from
Jan 20, 2025
Merged

Docs: VPP policy automations #25593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fc98968
Update software automation guide to mention VPP apps
iansltx Jan 20, 2025
186a16f
Update VPP article to mention automatic installs, misc. cleanup on so…
iansltx Jan 20, 2025
3a1e773
Simplify initial paragraph
iansltx Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 32 additions & 28 deletions articles/automatic-software-install-in-fleet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,74 +1,78 @@
# Automatically install software

Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) introduces the ability to automatically and remotely install software on hosts based on predefined policy failures. This guide will walk you through the process of configuring Fleet for automatic installation of software on hosts using uploaded custom packages or Fleet-maintained apps and based on programmed policies. You'll learn how to configure and use this feature, as well as understand how the underlying mechanism works.
_Available in Fleet Premium_

Fleet allows its users to upload trusted software installation files to be installed and used on hosts. This installation could be conditioned on a failure of a specific Fleet Policy.
Fleet lets you automatically and remotely install software on hosts based on predefined policy failures. This guide will walk you through the process of configuring Fleet for automatic installation of software on hosts based on programmed policies. You'll learn how to configure and use this feature, as well as understand how the underlying mechanism works.

> Currently, Fleet-maintained apps can be automatically installed on macOS hosts and custom packages can be automatically installed on macOS, Windows, and Linux hosts. (macOS App Store apps [coming soon](https://github.com/fleetdm/fleet/issues/23115))
> Currently, Fleet-maintained apps and Apple App Store apps can be automatically installed on macOS hosts, and custom packages can be automatically installed on macOS, Windows, and Linux hosts.

## Prerequisites

* Fleet premium with Admin permissions.
* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) or greater.
* Fleet Premium with Admin permissions.
* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) or greater, or [v4.63.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.63.0) or greater for Apple App Store (VPP) apps.
* For VPP apps, see [additional prerequisites](https://fleetdm.com/guides/install-vpp-apps-on-macos-using-fleet#prerequisites).

## Step-by-step instructions

1. **Adding software**: Add any software to be available for installation. Follow the [deploying software](https://fleetdm.com/guides/deploy-security-agents) document with instructions how to do it. Note that all installation steps (pre-install query, install script, and post-install script) will be executed as configured, regardless of the policy that triggers the installation.


![Add software](../website/assets/images/articles/automatic-software-install-add-software.png)
1. **Adding software**: Follow the [deploying software](https://fleetdm.com/guides/deploy-security-agents) guide to make a software title available for installation. Note that for Fleet maintained Apps and custom packages all installation steps (pre-install query, install script, and post-install script) will be executed as configured, regardless of the policy that triggers the installation.

Current supported software deployment formats:
- macOS: .pkg
- macOS: .pkg and App Store (VPP)
- Windows: .msi, .exe
- Linux: .deb, .rpm

Coming soon:
- VPP for iOS and iPadOS

> Note: starting with v4.62.0, you can have Fleet create an automatic install policy for you when you upload a package. If you use this "Automatic" installation mode, you do not have to create your own policy. See our [deploying software](https://fleetdm.com/guides/deploy-security-agents) guide for more details.
> As of v4.62.0, Fleet can create an automatic install policy for you when you upload a custom package or add a Fleet Maintained App. If you use this "Automatic" installation mode, you do not have to create your own policy, so you can skip the remaining steps of this process.

2. **Add a policy**: In Fleet, add a policy that failure to pass will trigger the required installation. Go to Policies tab --> Press the "Add policy" button --> Click "create your own policy" --> Enter your policy SQL --> Save --> Fill in details in the Save modal and Save.
2. **Add a policy**: In Fleet, add a policy that failure to pass will trigger the required installation. Go the **Policies** tab, select a team, then press the **Add policy** button. Next, click **Create your own policy**, enter your policy SQL, click **Save**, fill in remaining details in the Save modal, then and click **Save** again.

```sql
SELECT 1 FROM apps WHERE name = 'Adobe Acrobat Reader.app' AND version_compare(bundle_short_version, '23.001.20687') >= 0;
```

Note: In order to know the exact application name to put in the query (e.g. "Adobe Acrobat Reader.app" in the query above) you can manually install it on a canary/test host and then query SELECT * from apps;
> In order to know the exact application name to put in the query (e.g. "Adobe Acrobat Reader.app" in the query above) you can manually install it on a canary/test host and then query `SELECT * from apps;`


3. **Manage automation**: Open Manage Automations: Policies Tab --> top right "Manage automations" --> "Install software".
3. **Open the software install automation modal**: In the **Policies** tab, click the **Manage automations** button on the top-right, then select **Install software** from the context menu that pops up.

![Manage policies](../website/assets/images/articles/automatic-software-install-policies-manage.png)

4. **Select policy**: Select (click the check box of) your newly created policy. To the right of it select from the
4. **Select policy**: Click the checkbox next to your newly created policy's name. To the right of it select from the
drop-down list the software you would like to be installed upon failure of this policy.

![Install software modal](../website/assets/images/articles/automatic-software-install-install-software.png)

Upon failure of the selected policy, the selected software installation will be triggered.

> Adding software to a policy will reset the policy's host counts.
> Adding a software automation to a policy, or changing the automated software title, will reset the policy's host counts.

## How does it work?

* After configuring Fleet to auto-install a specific software the rest will be done automatically.
* The policy check mechanism runs on a typical 1 hour cadence on all online hosts.
* Fleet will send install requests to the hosts on the first policy failure (first "No" result for the host) or if a policy goes from "Yes" to "No". On this iteration it will not send an install request if a policy is already failing and continues to fail ("No" -> "No"). See the following flowchart for details.
* The policy check mechanism runs on a typical one-hour cadence on all online hosts.
* Fleet will send install requests to the hosts on the first policy failure (first "No" result for the host) or if a policy goes from "Yes" to "No". Currently, Fleet will not send an install request if a policy is already failing and continues to fail ("No" -> "No"). See the following flowchart for details.

![Flowchart](../website/assets/images/articles/automatic-software-install-workflow.png)
*Detailed flowchart*

> If a software installer excludes a host via label scoping, the associated policy query will run but policy failures will show as `-` and a software install will not be queued.

### Notes on automated VPP installs

VPP installs will not be queued for hosts that are not enrolled in MDM, or for apps that have run out of VPP licenses. If this issue affects a large number of hosts covered by a policy, after resolving the host and/or license count issue, remove and re-add the software automation. This will reset policy status for all hosts, and the app will install on hosts failing the policy query the next time policy queries run on those hosts.

As with manual VPP installs, apps are currently installed unmanaged, and Fleet does not yet support uninstalling VPP apps.

## Templates for policy queries

Use the following policy templates to see if the software is already installed. Fleet uses these templates to automatically install software.

### macOS (pkg)
### macOS (pkg and VPP)

```sql
SELECT 1 FROM apps WHERE name = '<SOFTWARE_TITLE_NAME>' AND version_compare(bundle_short_version, '<SOFTWARE_PACKAGE_VERSION>') >= 0;
```

> `SOFTWARE_TITLE_NAME` includes the `.app` extension. You can also use `bundle_identifier` for a more precise match that works if an end user renames the app on their machine.

### Windows (msi and exe)

```sql
Expand Down Expand Up @@ -109,13 +113,13 @@ SELECT 1 WHERE EXISTS (
);
```

## Using the REST API for self-service software packages
## Via the API

Fleet provides a REST API for managing software packages, including self-service software packages. Learn more about Fleet's [REST API](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy).
Fleet provides a REST API for managing policies, including software install automations. Learn more about Fleet's [REST API](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy).

## Managing self-service software packages with GitOps
## Via GitOps

To manage self-service software packages using Fleet's best practice GitOps, check out the `software` key in the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#policies).
To manage software automations using Fleet's best practice GitOps, check out the `install_software` key in the [policies section of the GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#policies).

## Conclusion

Expand All @@ -129,5 +133,5 @@ By automating software deployment, you can gain greater control over what's inst
<meta name="authorFullName" value="Sharon Katz">
<meta name="authorGitHubUsername" value="sharon-fdm">
<meta name="category" value="guides">
<meta name="publishedOn" value="2024-09-23">
<meta name="publishedOn" value="2025-01-21">
<meta name="description" value="A guide to workflows using automatic software installation in Fleet.">
2 changes: 1 addition & 1 deletion articles/deploy-software-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ In Fleet you can deploy [Fleet-maintained apps](https://fleetdm.com/guides/insta

This guide will walk you through steps to manually install custom packages on your hosts.

Learn more about automatically installing software in a separate guide [here](https://fleetdm.com/guides/automatic-software-install-in-fleet).
Learn more about automatically installing software [the Automatically install software guide](https://fleetdm.com/guides/automatic-software-install-in-fleet).

## Prerequisites

Expand Down
8 changes: 5 additions & 3 deletions articles/install-vpp-apps-on-macos-using-fleet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ _Available in Fleet Premium_

In Fleet, you can install Apple App Store apps using the [Volume Purchasing Program (VPP)](https://support.apple.com/guide/app-store/volume-purchasing-app-store-mac-firc1767ec54/mac) on your macOS, iOS, and iPadOS hosts. This guide will walk you through using this feature to add apps from your Apple Business Manager account to Fleet and install those apps on your hosts.

Once a VPP app has been added to a team, it can be [automatically installed on hosts via policy automations](https://fleetdm.com/guides/automatic-software-install-in-fleet) as of Fleet [v4.63.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.63.0).

## Prerequisites
* **MDM features**: to use the VPP integration, you must first enable MDM features in Fleet. See the [MDM setup guide](https://fleetdm.com/docs/using-fleet/mdm-setup) for instructions on enabling MDM features.

Expand Down Expand Up @@ -59,7 +61,7 @@ To add apps to Fleet, you must first purchase them through Apple Business Manage
the **Details** -> **Activity** -> **Upcoming** tab of this page. After the app is installed and
the host details are refetched, the app will show up as **Installed** in the **Software** tab.

>**Note:** VPP managed apps currently can't be uninstalled from devices. Please see: [Uninstall App Store apps #20729](https://github.com/fleetdm/fleet/issues/20729).
> Currently, VPP apps are installed as unmanaged, and can't be uninstalled from devices via Fleet. Please see: [Uninstall App Store apps #20729](https://github.com/fleetdm/fleet/issues/20729).

## Install an app via self-service

Expand Down Expand Up @@ -92,12 +94,12 @@ Fleet also provides a REST API for managing apps programmatically. You can add,

## Manage apps with GitOps

To manage App Store apps using Fleet's best practice GitOps, check out the `software` key in the GitOps reference documentation [here](https://fleetdm.com/docs/using-fleet/gitops#software).
To manage App Store apps using Fleet's best practice GitOps, check out the `software` key in [the GitOps reference documentation](https://fleetdm.com/docs/using-fleet/gitops#software).

<meta name="articleTitle" value="Install App Store (VPP) apps">
<meta name="authorFullName" value="Jahziel Villasana-Espinoza">
<meta name="authorGitHubUsername" value="jahzielv">
<meta name="category" value="guides">
<meta name="publishedOn" value="2024-08-12">
<meta name="publishedOn" value="2025-01-21">
<meta name="articleImageUrl" value="../website/assets/images/articles/install-vpp-apps-on-macos-using-fleet-1600x900@2x.png">
<meta name="description" value="This guide will walk you through installing VPP apps on macOS, iOS, and iPadOS using Fleet.">
Loading