Skip to content

Commit

Permalink
Docs v4.63.0 (#26019)
Browse files Browse the repository at this point in the history 
Documentation changes for 4.63.0

---------

Co-authored-by: Marko Lisica <[email protected]>
Co-authored-by: Eugene <[email protected]>
Co-authored-by: Ian Littman <[email protected]>
Co-authored-by: Scott Gress <[email protected]>
Co-authored-by: Victor Lyuboslavsky <[email protected]>
Co-authored-by: Noah Talerman <[email protected]>
  • Loading branch information
@rachaelshaw @marko-lisica
@eugkuo @iansltx @sgress454 @getvictor @noahtalerman
7 people authored Feb 4, 2025
1 parent c4837a7 commit 33b481f
Show file tree
Hide file tree
Showing 11 changed files with 311 additions and 56 deletions.
56 changes: 23 additions & 33 deletions articles/automatic-software-install-in-fleet.md
View file
Original file line number Diff line number Diff line change
@@ -1,74 +1,64 @@
# 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.

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.

> 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))
## Prerequisites

* Fleet premium with Admin permissions.
* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) or greater.
In Fleet, you can automatically and remotely install software on hosts. This guide will walk you through the process of configuring Fleet to install software on your hosts.

## 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) app
- Windows: .msi, .exe
- Linux: .deb, .rpm

Coming soon:
- VPP for iOS and iPadOS
> 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.
> 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.
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*

App Store (VPP) apps won't be installed if a host has MDM turned off or if you run out of licenses (purchased in Apple Business Manager). Currently, these errors aren't surfaced in Fleet. After turning MDM on for a host or purchasing more licenses, you can retry installing the app on the host's **Host details** page (learn how [here](https://fleetdm.com/guides/deploy-software-packages#install-the-package)). To retry on multiple hosts at once, head to **Policies > Manage Automations** in Fleet and turn the app's policy automation off and back on.

Currently, App Store apps (VPP) are not installed as [Managed Apps](https://support.apple.com/guide/deployment/distribute-managed-apps-dep575bfed86/web). Uninstalling VPP apps is coming soon.

## 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 +99,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 +119,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.">
55 changes: 55 additions & 0 deletions articles/cdn-signed-urls.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# How to use CloudFront signed URLs with Fleet

Fleet [v4.63.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.63.0) allows you to use CloudFront signed URLs for downloading MDM bootstrap packages and software installation packages to your hosts. This speeds up onboarding for organizations that onboard new employees at different headquarters across the world.

CloudFront signed URLs grant access to a specific CloudFront distribution resource and are valid for a specified duration.

## Prerequisites

- Fleet v4.63.0
- Orbit v1.39.0 agent installed on hosts (for software installation packages)
- S3 bucket with CloudFront distribution and a signing key pair

To add a CloudFront distribution with a signer to your S3 bucket, follow the instructions in the [AWS documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html) or the [How to securely serve private CDN content using CloudFront](https://victoronsoftware.com/posts/cloudfront-signed-urls/) guide written by one of our engineers.

## Configure Fleet server for S3 and CloudFront

To configure S3 and CloudFront in Fleet, use the [S3 server configuration options](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3). Set these options via the command line, environment variables, or a configuration file.

To enable CloudFront signed URLs, set the following options in your Fleet server configuration:

- `s3_software_installers_cloudfront_url`: The base URL of your CloudFront distribution, such as `https://d1234567890.cloudfront.net`.
- `s3_software_installers_cloudfront_key_pair_id`: The CloudFront signer's key pair ID, such as `K1HFGXOMBB6TFF`.
- `s3_software_installers_cloudfront_private_key`: The CloudFront signer's private key, such as `-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAz...`.

The `FLEET_S3_SOFTWARE_INSTALLERS_CLOUDFRONT_URL_SIGNING_PRIVATE_KEY` environment variable can be set from a file. On macOS, it requires [gnu-sed](https://formulae.brew.sh/formula/gnu-sed) (`gsed`) to replace newlines with `\n` characters.

```bash
export FLEET_S3_SOFTWARE_INSTALLERS_CLOUDFRONT_URL_SIGNING_PRIVATE_KEY=$(cat ./private_key.pem | gsed -z 's/\n/\\n/g')
```

Non-signed CDN URLs are not secure and are not supported.

## Use CloudFront signed URLs in Fleet

Once configured, Fleet will automatically use CloudFront signed URLs to install MDM bootstrap packages and software packages on your hosts. The signed URLs are generated on the fly and are valid for six hours.

If the Fleet server encounters an error while generating a signed URL for the bootstrap package, it will fall back to using the Fleet server's URL.

If the Orbit agent encounters an error while downloading a software package using a signed URL, it will retry the download using the Fleet server's URL.

To make sure that the signed URLs are working correctly, you can check the CloudFront logs (if enabled) as well as [APM](https://aws.amazon.com/what-is/application-performance-monitoring/) or Fleet server debug logs. In APM or Fleet server logs, you should NOT see devices downloading packages from the Fleet server's non-CDN API paths, such as:

- `GET /api/v1/fleet/bootstrap`
- `POST /api/fleet/orbit/software_install/package`

## Conclusion

Using CloudFront signed URLs with Fleet can help speed up downloads and reduce the load on your Fleet server. If you have any questions or need help configuring CloudFront signed URLs, please contact our [support team](https://fleetdm.com/contact).

<meta name="articleTitle" value="How to use CloudFront signed URLs with Fleet">
<meta name="authorFullName" value="Victor Lyuboslavsky">
<meta name="authorGitHubUsername" value="getvictor">
<meta name="category" value="guides">
<meta name="publishedOn" value="2025-02-03">
<meta name="description" value="A guide on using signed URLs with MDM bootstrap packages and software installers.">
2 changes: 1 addition & 1 deletion articles/deploy-software-packages.md
View file
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
Loading

0 comments on commit 33b481f

Please sign in to comment.