empayre/fleet
14
0
Fork 0
mirror of https://github.com/empayre/fleet.git synced 2024-11-06 08:55:24 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

7766 backmerge main (#14324)

Browse Source
This commit is contained in:
Tim Lee 2023-10-05 11:39:48 -06:00 committed by GitHub
parent b0de002fb2
commit ccd6746633
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
140 changed files with 2218 additions and 872 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.github/workflows/build-orbit.yaml vendored
View File

@ -2,12 +2,18 @@ name: Build, Sign and Notarize Orbit for macOS
on: on:
workflow_dispatch: # allow manual action workflow_dispatch: # allow manual action
push:
paths:
# The workflow can be triggered by modifying ORBIT_VERSION env.
- '.github/workflows/build-orbit.yaml'
pull_request: pull_request:
paths: paths:
- 'orbit/**.go' - 'orbit/**.go'
# The workflow can be triggered by modifying ORBIT_VERSION env.
- '.github/workflows/build-orbit.yaml'
env: env:
ORBIT_VERSION: 1.16.0 ORBIT_VERSION: 1.17.0
# This allows a subsequently queued workflow run to interrupt previous runs # This allows a subsequently queued workflow run to interrupt previous runs
concurrency: concurrency:

2
.github/workflows/generate-desktop-targets.yml vendored
View File

@ -24,7 +24,7 @@ defaults:
shell: bash shell: bash
env: env:
FLEET_DESKTOP_VERSION: 1.16.0 FLEET_DESKTOP_VERSION: 1.17.0
permissions: permissions:
contents: read contents: read

6
CHANGELOG.md
View File

@ -1,3 +1,9 @@
## Fleet 4.38.1 (Oct 5, 2023)
### Bug Fixes
* Fixed a bug that would cause live queries to stall if a detail query override was set for a team.
## Fleet 4.38.0 (Sep 25, 2023) ## Fleet 4.38.0 (Sep 25, 2023)
### Changes ### Changes

2
articles/fleet-4.32.0.md
View File

@ -30,7 +30,7 @@ Continuing Fleet’s 🟣 Openness and GitOps forward approach to MDM, we are ex
With this addition, administrators can have different setup experiences for each team—allowing a conference room computer to skip all setup screens while users see the screens they need. Controlling the macOS Setup Assistant using a JSON file allows for version control, review, and approval using a GitOps workflow. Additionally, when Apple releases new features (keys), administrators do not need to wait for a Fleet release to support these new features. With this addition, administrators can have different setup experiences for each team—allowing a conference room computer to skip all setup screens while users see the screens they need. Controlling the macOS Setup Assistant using a JSON file allows for version control, review, and approval using a GitOps workflow. Additionally, when Apple releases new features (keys), administrators do not need to wait for a Fleet release to support these new features.
Learn more about customizing the [macOS Setup Assistant](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#macos-setup-assistant) experience. Learn more about customizing the [macOS Setup Assistant](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#macos-setup-assistant) experience.
## More new features, improvements, and bug fixes ## More new features, improvements, and bug fixes

2
charts/fleet/Chart.yaml
View File

@ -8,4 +8,4 @@ version: v5.0.1
home: https://github.com/fleetdm/fleet home: https://github.com/fleetdm/fleet
sources: sources:
- https://github.com/fleetdm/fleet.git - https://github.com/fleetdm/fleet.git
appVersion: v4.38.0 appVersion: v4.38.1

4
charts/fleet/values.yaml
View File

@ -2,7 +2,7 @@
# All settings related to how Fleet is deployed in Kubernetes # All settings related to how Fleet is deployed in Kubernetes
hostName: fleet.localhost hostName: fleet.localhost
replicas: 3 # The number of Fleet instances to deploy replicas: 3 # The number of Fleet instances to deploy
imageTag: v4.38.0 # Version of Fleet to deploy imageTag: v4.38.1 # Version of Fleet to deploy
podAnnotations: {} # Additional annotations to add to the Fleet pod podAnnotations: {} # Additional annotations to add to the Fleet pod
serviceAccountAnnotations: {} # Additional annotations to add to the Fleet service account serviceAccountAnnotations: {} # Additional annotations to add to the Fleet service account
resources: resources:
@ -199,7 +199,7 @@ environments:
# The following environment variables are used to configure Fleet to work with # The following environment variables are used to configure Fleet to work with
# Apple's MDM service. These are optional and only required if you are using # Apple's MDM service. These are optional and only required if you are using
# Fleet to manage Apple devices. # Fleet to manage Apple devices.
# To more information: https://fleetdm.com/docs/using-fleet/mdm-setup#step-3-configure-fleet-with-the-required-files # To more information: https://fleetdm.com/docs/using-fleet/mdm-macos-setup#step-3-configure-fleet-with-the-required-files
FLEET_MDM_APPLE_APNS_CERT_BYTES: "" FLEET_MDM_APPLE_APNS_CERT_BYTES: ""
FLEET_MDM_APPLE_APNS_KEY_BYTES: "" FLEET_MDM_APPLE_APNS_KEY_BYTES: ""
FLEET_MDM_APPLE_SCEP_CERT_BYTES: "" FLEET_MDM_APPLE_SCEP_CERT_BYTES: ""

2
cmd/fleetctl/apply_test.go
View File

@ -1887,7 +1887,7 @@ spec:
expectedErr error expectedErr error
}{ }{
{"signed.pkg", nil}, {"signed.pkg", nil},
{"unsigned.pkg", errors.New("applying fleet config: Couldn’t edit bootstrap_package. The bootstrap_package must be signed. Learn how to sign the package in the Fleet documentation: https://fleetdm.com/docs/using-fleet/mdm-macos-setup#step-2-sign-the-package")}, {"unsigned.pkg", errors.New("applying fleet config: Couldn’t edit bootstrap_package. The bootstrap_package must be signed. Learn how to sign the package in the Fleet documentation: https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#step-2-sign-the-package")},
{"invalid.tar.gz", errors.New("applying fleet config: Couldn’t edit bootstrap_package. The file must be a package (.pkg).")}, {"invalid.tar.gz", errors.New("applying fleet config: Couldn’t edit bootstrap_package. The file must be a package (.pkg).")},
{"wrong-toc.pkg", errors.New("applying fleet config: checking package signature: decompressing TOC: unexpected EOF")}, {"wrong-toc.pkg", errors.New("applying fleet config: checking package signature: decompressing TOC: unexpected EOF")},
} }

4
cmd/fleetctl/get.go
View File

@ -1303,10 +1303,10 @@ func getMDMAppleCommand() *cli.Command {
warnDate := time.Now().Add(expirationWarning) warnDate := time.Now().Add(expirationWarning)
if mdm.RenewDate.Before(time.Now()) { if mdm.RenewDate.Before(time.Now()) {
// certificate is expired, print an error // certificate is expired, print an error
color.New(color.FgRed).Fprintln(c.App.Writer, "\nERROR: Your Apple Push Notification service (APNs) certificate is expired. MDM features are turned off. To renew your APNs certificate, follow these instructions: https://fleetdm.com/docs/using-fleet/mdm-setup#apple-push-notification-service-apns") color.New(color.FgRed).Fprintln(c.App.Writer, "\nERROR: Your Apple Push Notification service (APNs) certificate is expired. MDM features are turned off. To renew your APNs certificate, follow these instructions: https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns")
} else if mdm.RenewDate.Before(warnDate) { } else if mdm.RenewDate.Before(warnDate) {
// certificate will soon expire, print a warning // certificate will soon expire, print a warning
color.New(color.FgYellow).Fprintln(c.App.Writer, "\nWARNING: Your Apple Push Notification service (APNs) certificate is less than 30 days from expiration. If it expires, MDM features will be turned off. To renew your APNs certificate, follow these instructions: https://fleetdm.com/docs/using-fleet/mdm-setup#renewing-apns") color.New(color.FgYellow).Fprintln(c.App.Writer, "\nWARNING: Your Apple Push Notification service (APNs) certificate is less than 30 days from expiration. If it expires, MDM features will be turned off. To renew your APNs certificate, follow these instructions: https://fleetdm.com/docs/using-fleet/mdm-macos-setup#renewing-apns")
} }
return nil return nil

5
cmd/osquery-perf/agent.go
View File

@ -551,6 +551,7 @@ func (a *agent) runOrbitLoop() {
if err != nil { if err != nil {
a.stats.IncrementOrbitErrors() a.stats.IncrementOrbitErrors()
log.Println("orbitClient.GetConfig: ", err) log.Println("orbitClient.GetConfig: ", err)
continue
} }
if len(cfg.Notifications.PendingScriptExecutionIDs) > 0 { if len(cfg.Notifications.PendingScriptExecutionIDs) > 0 {
// there are pending scripts to execute on this host, start a goroutine // there are pending scripts to execute on this host, start a goroutine
@ -562,6 +563,7 @@ func (a *agent) runOrbitLoop() {
if err := deviceClient.CheckToken(*a.deviceAuthToken); err != nil { if err := deviceClient.CheckToken(*a.deviceAuthToken); err != nil {
a.stats.IncrementOrbitErrors() a.stats.IncrementOrbitErrors()
log.Println("deviceClient.CheckToken: ", err) log.Println("deviceClient.CheckToken: ", err)
continue
} }
} }
case <-orbitTokenRotationTicker: case <-orbitTokenRotationTicker:
@ -570,6 +572,7 @@ func (a *agent) runOrbitLoop() {
if err := orbitClient.SetOrUpdateDeviceToken(*newToken); err != nil { if err := orbitClient.SetOrUpdateDeviceToken(*newToken); err != nil {
a.stats.IncrementOrbitErrors() a.stats.IncrementOrbitErrors()
log.Println("orbitClient.SetOrUpdateDeviceToken: ", err) log.Println("orbitClient.SetOrUpdateDeviceToken: ", err)
continue
} }
a.deviceAuthToken = newToken a.deviceAuthToken = newToken
// fleet desktop performs a burst of check token requests after a token is rotated // fleet desktop performs a burst of check token requests after a token is rotated
@ -579,11 +582,13 @@ func (a *agent) runOrbitLoop() {
if err := orbitClient.Ping(); err != nil { if err := orbitClient.Ping(); err != nil {
a.stats.IncrementOrbitErrors() a.stats.IncrementOrbitErrors()
log.Println("orbitClient.Ping: ", err) log.Println("orbitClient.Ping: ", err)
continue
} }
case <-fleetDesktopPolicyTicker: case <-fleetDesktopPolicyTicker:
if _, err := deviceClient.DesktopSummary(*a.deviceAuthToken); err != nil { if _, err := deviceClient.DesktopSummary(*a.deviceAuthToken); err != nil {
a.stats.IncrementDesktopErrors() a.stats.IncrementDesktopErrors()
log.Println("deviceClient.NumberOfFailingPolicies: ", err) log.Println("deviceClient.NumberOfFailingPolicies: ", err)
continue
} }
} }
} }

22
docs/01-Using-Fleet/standard-query-library/standard-query-library.yml
View File

@ -1045,3 +1045,25 @@ spec:
purpose: Informational purpose: Informational
tags: crowdstrike, plist, network, content filter tags: crowdstrike, plist, network, content filter
contributors: zwass contributors: zwass
---
apiVersion: v1
kind: query
spec:
name: Get a list of Visual Studio Code extensions
platform: darwin
description: Get a list of installed VS Code extensions. Requires (fleetd)[https://fleetdm.com/docs/using-fleet/fleetd].
query: |
SELECT split(user_path, '/', 1) as username,
json_extract(value, '$.identifier.id') as id,
json_extract(value, '$.identifier.uuid') as uuid,
json_extract(value, '$.location.path') as path,
json_extract(value, '$.version') as version,
json_extract(value, '$.metadata.publisherDisplayName') as publisher_display_name
FROM (
SELECT file_lines.path as user_path, value
FROM file_lines, json_each(line)
WHERE file_lines.path LIKE '/Users/%/.vscode/extensions/extensions.json'
);
purpose: Informational
tags: inventory
contributors: lucasmrod,sharon-fdm,zwass

6
docs/Contributing/API-for-contributors.md
View File

@ -9,9 +9,11 @@
- [Downloadable installers](#downloadable-installers) - [Downloadable installers](#downloadable-installers)
- [Setup](#setup) - [Setup](#setup)
This document includes the Fleet API routes that are helpful when developing or contributing to Fleet. This document includes the internal Fleet API routes that are helpful when developing or contributing to Fleet.
Unlike the [Fleet REST API documentation](https://fleetdm.com/docs/using-fleet/rest-api), only the Fleet UI, Fleet Desktop, and `fleetctl` clients use the API routes in this document: These endpoints are used by the Fleet UI, Fleet Desktop, and `fleetctl` clients and will frequently change to reflect current functionality.
If you are interested in gathering information from Fleet in a production environment, please see the [public Fleet REST API documentation](https://fleetdm.com/docs/using-fleet/rest-api).
## Packs ## Packs

6
docs/Contributing/Testing-and-local-development.md
View File

@ -513,13 +513,13 @@ To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/g
First ask @zwass to create an account for you in [ABM](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#abm-apple-business-manager). You'll need an account to generate an encrypted token. First ask @zwass to create an account for you in [ABM](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#abm-apple-business-manager). You'll need an account to generate an encrypted token.
Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token. Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token.
### APNs and SCEP setup ### APNs and SCEP setup
The server also needs a private key + certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers, and another for [SCEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#scep-simple-certificate-enrollment-protocol). The server also needs a private key + certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers, and another for [SCEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#scep-simple-certificate-enrollment-protocol).
To generate both, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-push-notification-service-apns). To generate both, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns).
Note that: Note that:
@ -670,7 +670,7 @@ open /opt/orbit/bin/nudge/macos/stable/Nudge.app --args -json-url file:///opt/or
A bootstrap package is a `pkg` file that gets automatically installed on hosts when they enroll via DEP. A bootstrap package is a `pkg` file that gets automatically installed on hosts when they enroll via DEP.
The `pkg` file needs to be a signed "distribution package", you can find a dummy file that meets all the requirements [in Drive](https://drive.google.com/file/d/1adwAOTD5G6D4WzWvJeMId6mDhyeFy-lm/view). We have instructions in [the docs](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#bootstrap-package) to upload a new bootstrap package to your Fleet instance. The `pkg` file needs to be a signed "distribution package", you can find a dummy file that meets all the requirements [in Drive](https://drive.google.com/file/d/1adwAOTD5G6D4WzWvJeMId6mDhyeFy-lm/view). We have instructions in [the docs](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) to upload a new bootstrap package to your Fleet instance.
The dummy package linked above adds a Fleet logo in `/Library/FleetDM/fleet-logo.png`. To verify if the package was installed, you can open that folder and verify that the logo is there. The dummy package linked above adds a Fleet logo in `/Library/FleetDM/fleet-logo.png`. To verify if the package was installed, you can open that folder and verify that the logo is there.

9
docs/Deploy/Deploy-Fleet-on-CentOS.md
View File

@ -19,12 +19,15 @@ vagrant ssh
### Installing Fleet ### Installing Fleet
To install Fleet, [download](https://github.com/fleetdm/fleet/releases), unzip, and move the latest Fleet binary to your desired install location. To install Fleet, [download](https://github.com/fleetdm/fleet/releases) the file named `Source code
(zip)`, rename, unzip, and move the latest Fleet binary to your desired install location.
For example, after downloading: For example, after downloading:
```sh ```sh
unzip fleet.zip 'linux/*' -d fleet mv <filename>.zip fleet.zip
sudo cp fleet/linux/fleet* /usr/bin/ unzip fleet.zip -d fleet
sudo cp fleet /usr/bin/
sudo chmod u+x /usr/bin/fleet
``` ```
### Installing and configuring dependencies ### Installing and configuring dependencies

24
docs/Deploy/Deploy-Fleet-on-Kubernetes.md
View File

@ -93,6 +93,8 @@ If you have not used Helm before, you must run the following to initialize your
helm init helm init
``` ```
> Note: The helm init command has been removed in Helm v3. It performed two primary functions. First, it installed Tiller which is no longer needed. Second, it set up directories and repositories where Helm configuration lived. This is now automated in Helm v3; if the directory is not present it will be created.
### Deploying Fleet with Helm ### Deploying Fleet with Helm
To configure preferences for Fleet for use in Helm, including secret names, MySQL and Redis hostnames, and TLS certificates, download the [values.yaml](https://raw.githubusercontent.com/fleetdm/fleet/main/charts/fleet/values.yaml) and change the settings to match your configuration. To configure preferences for Fleet for use in Helm, including secret names, MySQL and Redis hostnames, and TLS certificates, download the [values.yaml](https://raw.githubusercontent.com/fleetdm/fleet/main/charts/fleet/values.yaml) and change the settings to match your configuration.
@ -117,16 +119,24 @@ For the sake of this tutorial, we will again use Helm, this time to install MySQ
The MySQL that we will use for this tutorial is not replicated and it is not Highly Available. If you're deploying Fleet on a Kubernetes managed by a cloud provider (GCP, Azure, AWS, etc), I suggest using their MySQL product if possible as running HA MySQL in Kubernetes can be difficult. To make this tutorial cloud provider agnostic however, we will use a non-replicated instance of MySQL. The MySQL that we will use for this tutorial is not replicated and it is not Highly Available. If you're deploying Fleet on a Kubernetes managed by a cloud provider (GCP, Azure, AWS, etc), I suggest using their MySQL product if possible as running HA MySQL in Kubernetes can be difficult. To make this tutorial cloud provider agnostic however, we will use a non-replicated instance of MySQL.
To install MySQL from Helm, run the following command. Note that there are some options that are specified. These options basically just enumerate that: To install MySQL from Helm, run the following command. Note that there are some options that need to be defined:
- There should be a `fleet` database created - There should be a `fleet` database created
- The default user's username should be `fleet` - The default user's username should be `fleet`
Helm v2
```sh ```sh
helm install \ helm install \
--name fleet-database \ --name fleet-database \
--set mysqlUser=fleet,mysqlDatabase=fleet \ --set mysqlUser=fleet,mysqlDatabase=fleet \
stable/mysql oci://registry-1.docker.io/bitnamicharts/mysql
```
Helm v3
```sh
helm install fleet-database \
--set mysqlUser=fleet,mysqlDatabase=fleet \
oci://registry-1.docker.io/bitnamicharts/mysql
``` ```
This helm package will create a Kubernetes `Service` which exposes the MySQL server to the rest of the cluster on the following DNS address: This helm package will create a Kubernetes `Service` which exposes the MySQL server to the rest of the cluster on the following DNS address:
@ -156,11 +166,19 @@ kubectl create -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-migrat
#### Redis #### Redis
Helm v2
```sh ```sh
helm install \ helm install \
--name fleet-cache \ --name fleet-cache \
--set persistence.enabled=false \ --set persistence.enabled=false \
stable/redis oci://registry-1.docker.io/bitnamicharts/redis
```
Helm v3
```sh
helm install fleet-cache \
--set persistence.enabled=false \
oci://registry-1.docker.io/bitnamicharts/redis
``` ```
This helm package will create a Kubernetes `Service` which exposes the Redis server to the rest of the cluster on the following DNS address: This helm package will create a Kubernetes `Service` which exposes the Redis server to the rest of the cluster on the following DNS address:

5
docs/Get started/FAQ.md
View File

@ -2,6 +2,11 @@
## Using Fleet ## Using Fleet
### Can you host Fleet for me?
Fleet offers managed cloud hosting for large deployments. Unfortunately, while organizations of all kinds use Fleet, from Fortune 500 companies to school districts to hobbyists, we are not currently able to provide hosting for deployments smaller than 1000 hosts. If you are comfortable doing so, you can still buy a license and host Fleet yourself.
### How can I switch to Fleet from Kolide Fleet? ### How can I switch to Fleet from Kolide Fleet?
To migrate to Fleet from Kolide Fleet, please follow the steps outlined in the [Upgrading Fleet section](https://fleetdm.com/docs/deploying/upgrading-fleet) of the documentation. To migrate to Fleet from Kolide Fleet, please follow the steps outlined in the [Upgrading Fleet section](https://fleetdm.com/docs/deploying/upgrading-fleet) of the documentation.

12
docs/REST API/rest-api.md
View File

@ -1074,7 +1074,7 @@ Modifies the Fleet's configuration with the supplied information.
| webhook_url | string | body | _mdm.macos_migration settings_. The webhook url configured to receive requests to unenroll devices migrating from your old MDM solution. **Requires Fleet Premium license** | | webhook_url | string | body | _mdm.macos_migration settings_. The webhook url configured to receive requests to unenroll devices migrating from your old MDM solution. **Requires Fleet Premium license** |
| custom_settings | list | body | _mdm.macos_settings settings_. Hosts that belong to no team and are enrolled into Fleet's MDM will have those custom profiles applied. | | custom_settings | list | body | _mdm.macos_settings settings_. Hosts that belong to no team and are enrolled into Fleet's MDM will have those custom profiles applied. |
| enable_disk_encryption | boolean | body | _mdm.macos_settings settings_. Hosts that belong to no team and are enrolled into Fleet's MDM will have disk encryption enabled if set to true. **Requires Fleet Premium license** | | enable_disk_encryption | boolean | body | _mdm.macos_settings settings_. Hosts that belong to no team and are enrolled into Fleet's MDM will have disk encryption enabled if set to true. **Requires Fleet Premium license** |
| enable_end_user_authentication | boolean | body | _mdm.macos_setup settings_. If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#end-user-authentication). **Requires Fleet Premium license** | | enable_end_user_authentication | boolean | body | _mdm.macos_setup settings_. If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula). **Requires Fleet Premium license** |
| additional_queries | boolean | body | Whether or not additional queries are enabled on hosts. | | additional_queries | boolean | body | Whether or not additional queries are enabled on hosts. |
| force | bool | query | Force apply the agent options even if there are validation errors. | | force | bool | query | Force apply the agent options even if there are validation errors. |
| dry_run | bool | query | Validate the configuration and return any validation errors, but do not apply the changes. | | dry_run | bool | query | Validate the configuration and return any validation errors, but do not apply the changes. |
@ -1829,7 +1829,7 @@ the `software` table.
| page | integer | query | Page number of the results to fetch. | | page | integer | query | Page number of the results to fetch. |
| per_page | integer | query | Results per page. | | per_page | integer | query | Results per page. |
| order_key | string | query | What to order results by. Can be any column in the hosts table. | | order_key | string | query | What to order results by. Can be any column in the hosts table. |
| after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. **Note:** Use `page` instead of `after`. |
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. |
| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, `mia` or `missing`. | | status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, `mia` or `missing`. |
| query | string | query | Search query keywords. Searchable fields include `hostname`, `machine_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an `@`, no space, etc.). | | query | string | query | Search query keywords. Searchable fields include `hostname`, `machine_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an `@`, no space, etc.). |
@ -3333,7 +3333,7 @@ created_at,updated_at,id,detail_updated_at,label_updated_at,policy_updated_at,la
Requires the [macadmins osquery extension](https://github.com/macadmins/osquery-extension) which comes bundled Requires the [macadmins osquery extension](https://github.com/macadmins/osquery-extension) which comes bundled
in [Fleet's osquery installers](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer). in [Fleet's osquery installers](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer).
Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup).
Retrieves the disk encryption key for a host. Retrieves the disk encryption key for a host.
@ -3366,7 +3366,7 @@ Retrieves the disk encryption key for a host.
### Get configuration profiles assigned to a host ### Get configuration profiles assigned to a host
Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup).
Retrieves a list of the configuration profiles assigned to a host. Retrieves a list of the configuration profiles assigned to a host.
@ -3849,7 +3849,7 @@ Deletes the label specified by ID.
## Mobile device management (MDM) ## Mobile device management (MDM)
These API endpoints are used to automate MDM features in Fleet. Read more about MDM features in Fleet [here](https://fleetdm.com/docs/using-fleet/mdm-setup). These API endpoints are used to automate MDM features in Fleet. Read more about MDM features in Fleet [here](https://fleetdm.com/docs/using-fleet/mdm-macos-setup).
- [Add custom macOS setting (configuration profile)](#add-custom-macos-setting-configuration-profile) - [Add custom macOS setting (configuration profile)](#add-custom-macos-setting-configuration-profile)
- [List custom macOS settings (configuration profiles)](#list-custom-macos-settings-configuration-profiles) - [List custom macOS settings (configuration profiles)](#list-custom-macos-settings-configuration-profiles)
@ -7093,7 +7093,7 @@ _Available in Fleet Premium_
| &nbsp;&nbsp;macos_settings | object | body | MacOS-specific settings. | | &nbsp;&nbsp;macos_settings | object | body | MacOS-specific settings. |
| &nbsp;&nbsp;&nbsp;&nbsp;enable_disk_encryption | boolean | body | Hosts that belong to this team and are enrolled into Fleet's MDM will have disk encryption enabled if set to true. | | &nbsp;&nbsp;&nbsp;&nbsp;enable_disk_encryption | boolean | body | Hosts that belong to this team and are enrolled into Fleet's MDM will have disk encryption enabled if set to true. |
| &nbsp;&nbsp;macos_setup | object | body | Setup for automatic MDM enrollment of macOS devices. | | &nbsp;&nbsp;macos_setup | object | body | Setup for automatic MDM enrollment of macOS devices. |
| &nbsp;&nbsp;&nbsp;&nbsp;enable_end_user_authentication | boolean | body | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#end-user-authentication). | | &nbsp;&nbsp;&nbsp;&nbsp;enable_end_user_authentication | boolean | body | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula). |
#### Example (add users to a team) #### Example (add users to a team)

33
docs/Using Fleet/CIS-Benchmarks.md
View File

@ -12,6 +12,37 @@ Fleet has implemented native support for CIS Benchmarks for the following platfo
[Where possible](#limitations), each CIS Benchmark is implemented with a [policy query](./REST-API.md#policies) in Fleet. [Where possible](#limitations), each CIS Benchmark is implemented with a [policy query](./REST-API.md#policies) in Fleet.
These benchmarks are intended to gauge your organization's security posture, rather than the current state of a given host. A host may fail a CIS Benchmark policy despite having the correct settings enabled if there is not a specific policy in place to enforce that setting. For example, this is the query for **CIS - Ensure FileVault Is Enabled (MDM Required)**:
```sql
SELECT 1 WHERE
EXISTS (
SELECT 1 FROM managed_policies WHERE
domain='com.apple.MCX' AND
name='dontAllowFDEDisable' AND
(value = 1 OR value = 'true') AND
username = ''
)
AND NOT EXISTS (
SELECT 1 FROM managed_policies WHERE
domain='com.apple.MCX' AND
name='dontAllowFDEDisable' AND
(value != 1 AND value != 'true')
)
AND EXISTS (
SELECT 1 FROM disk_encryption WHERE
user_uuid IS NOT "" AND
filevault_status = 'on'
);
```
Two things are being evaluated in this policy:
1. Is FileVault currently enabled?
2. Is there a profile in place that prevents FileVault from being disabled?
If either of these conditions fails, the host is considered to be failing the policy.
## Requirements ## Requirements
Following are the requirements to use the CIS Benchmarks in Fleet: Following are the requirements to use the CIS Benchmarks in Fleet:
@ -23,7 +54,7 @@ Following are the requirements to use the CIS Benchmarks in Fleet:
### MDM required ### MDM required
Some of the policies created by Fleet use the [managed_policies](https://www.fleetdm.com/tables/managed_policies) table. This checks whether an MDM solution has turned on the setting to enforce the policy. Some of the policies created by Fleet use the [managed_policies](https://www.fleetdm.com/tables/managed_policies) table. This checks whether an MDM solution has turned on the setting to enforce the policy.
Using MDM is the recommended way to manage and enforce CIS Benchmarks. To learn how to set up MDM in Fleet, visit [here](/docs/using-fleet/mdm-setup). Using MDM is the recommended way to manage and enforce CIS Benchmarks. To learn how to set up MDM in Fleet, visit [here](/docs/using-fleet/mdm-macos-setup).
### Fleetd required ### Fleetd required
Fleet's CIS Benchmarks require our [osquery manager, Fleetd](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer). This is because Fleetd includes tables which are not part of vanilla osquery in order to accomplish auditing the benchmarks. Fleet's CIS Benchmarks require our [osquery manager, Fleetd](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer). This is because Fleetd includes tables which are not part of vanilla osquery in order to accomplish auditing the benchmarks.

78
docs/Using Fleet/MDM-Windows-setup.md Normal file
View File

@ -0,0 +1,78 @@
# Windows setup
## Overview
> Windows MDM features are not ready for production and are currently in development. These features are disabled by default.
Turning on Windows MDM features requires configuring Fleet with a certificate and key. This guide will walk you through how to upload these to Fleet and turn on Windows MDM.
## Requirements
To use Fleet's Windows MDM features you need to have:
- A [deployed Fleet instance](../Deploying/Introduction.md).
- A Fleet user with the admin role.
## Turning on Windows MDM
Fleet uses a certificate and key pair to authenticate and manage interactions between Fleet and Windows hosts.
This section will show you how to:
1. Generate your certificate and key
2. Configure Fleet with your certificate and key
3. Turn on Windows MDM in Fleet
### Step 1: generate your certificate and key
If you're already using Fleet's macOS MDM features, you already have a certificate and key. These are your SCEP certificate and SCEP private key you used when turning on macOS MDM.
If you're not using macOS MDM features, 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>
```
Save the SCEP certificate and SCEP key. These are your certificate and key. You can ignore the downloaded APNs key and the APNs CSR that was sent to your email.
### Step 2: configure Fleet with your certificate and key
1. In your Fleet server configuration, set the contents of the certificate and key in the following environment variables:
> Note: Any environment variable that ends in `_BYTES` expects the file's actual content to be passed in, not a path to the file. If you want to pass in a file path, remove the `_BYTES` suffix from the environment variable.
- [FLEET_MDM_WINDOWS_WSTEP_IDENTITY_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-windows-wstep-identity-cert-bytes)
- [FLEET_MDM_WINDOWS_WSTEP_IDENTITY_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-windows-wstep-identity-key-bytes)
2. Set the `FLEET_MDM_WINDOWS_ENABLED_AND_CONFIGURED` environment variable to `true`.
3. Restart the Fleet server.
### Step 2: Turn on Windows MDM in Fleet
Fleet UI:
1. Head to the **Settings > Integrations > Mobile device management (MDM) enrollment** page.
2. Next to **Turn on Windows MDM** select **Turn on** to navigate to the **Turn on Windows MDM** page.
3. Select **Turn on**.
fleetctl CLI:
1. Create `fleet-config.yaml` file or add to your existing `config` YAML file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
windows_enabled_and_configured: true
...
```
2. Run the fleetctl `apply -f fleet-config.yml` command to turn on Windows MDM.
3. Confirm that Windows MDM is turned on by running `fleetctl get config`.
<meta name="pageOrderInSection" value="1501">
<meta name="title" value="Windows setup">
<meta name="description" value="Learn how to set up Windows MDM features in Fleet.">
<meta name="navSection" value="Device management">

4
docs/Using Fleet/MDM-commands.md
View File

@ -117,7 +117,7 @@ The command ID can be used to view command results as documented in [step 4 of t
* Error: the host responded with "Error" status via the MDM protocol: an error occurred. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error. * Error: the host responded with "Error" status via the MDM protocol: an error occurred. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error.
* CommandFormatError: the host responded with "CommandFormatError" status via the MDM protocol: a protocol error occurred, which can result from a malformed command. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error. * CommandFormatError: the host responded with "CommandFormatError" status via the MDM protocol: a protocol error occurred, which can result from a malformed command. Run the `fleetctl get mdm-command-results --id=<insert-command-id` to view the error.
<meta name="pageOrderInSection" value="1506"> <meta name="pageOrderInSection" value="1507">
<meta name="title" value="MDM commands"> <meta name="title" value="Commands">
<meta name="description" value="Learn how to run custom MDM commands on macOS hosts using Fleet."> <meta name="description" value="Learn how to run custom MDM commands on macOS hosts using Fleet.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

4
docs/Using Fleet/MDM-custom-macOS-settings.md
View File

@ -99,7 +99,7 @@ Learn more about configuration options for hosts that aren't assigned to a team
3. In the list of hosts, click on an individual host and click the **macOS settings** item to see the status for a specific setting. 3. In the list of hosts, click on an individual host and click the **macOS settings** item to see the status for a specific setting.
<meta name="pageOrderInSection" value="1504"> <meta name="pageOrderInSection" value="1505">
<meta name="title" value="MDM custom macOS settings"> <meta name="title" value="Custom macOS settings">
<meta name="description" value="Learn how to enforce custom settings on macOS hosts using Fleet's configuration profiles."> <meta name="description" value="Learn how to enforce custom settings on macOS hosts using Fleet's configuration profiles.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

4
docs/Using Fleet/MDM-disk-encryption.md
View File

@ -118,7 +118,7 @@ How to reset a macOS host's password using the disk encryption key:
4. The Mac will display a prompt to reset the password. Reset the password and save this password somewhere safe. If you plan to prepare this Mac for a new employee, you'll need this password to erase all content and settings on the Mac. 4. The Mac will display a prompt to reset the password. Reset the password and save this password somewhere safe. If you plan to prepare this Mac for a new employee, you'll need this password to erase all content and settings on the Mac.
<meta name="pageOrderInSection" value="1503"> <meta name="pageOrderInSection" value="1504">
<meta name="title" value="MDM disk encryption"> <meta name="title" value="Disk encryption">
<meta name="description" value="Learn how to enforce disk encryption on macOS hosts and manage encryption keys with Fleet Premium."> <meta name="description" value="Learn how to enforce disk encryption on macOS hosts and manage encryption keys with Fleet Premium.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

345
docs/Using Fleet/MDM-macOS-setup-experience.md Normal file
View File

@ -0,0 +1,345 @@
# macOS setup experience
_Available in Fleet Premium_
In Fleet, you can customize the out-of-the-box macOS setup experience for your end users:
* Require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac.
* Customize the macOS Setup Assistant by choosing to show or hide specific panes.
* Install a bootstrap package to gain full control over the setup experience by installing tools like Puppet, Munki, DEP notify, custom scripts, and more.
In addition to the customization above, Fleet automatically installs the fleetd agent during out-of-the-box macOS setup. This agent is responsible for reporting host vitals to Fleet and presenting Fleet Desktop to the end user.
MacOS setup features require connecting Fleet to Apple Business Manager (ABM). Learn how [here](./mdm-macos-setup.md#apple-business-manager-abm).
## End user authentication and EULA
Using Fleet, you can require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac.
To require end user authentication, we will do the following steps:
1. Connect Fleet to your IdP
2. Upload a EULA to Fleet (optional)
3. Enable end user authentication
### Step 1: connect Fleet to your IdP
Fleet UI:
1. Head to the **Settings > Integrations > Automatic enrollment** page.
2. Under **End user authentication**, enter your IdP credentials and select **Save**.
> If you've already configured [single sign-on (SSO) for logging in to Fleet](https://fleetdm.com/docs/configuration/fleet-server-configuration#okta-idp-configuration), you'll need to create a separate app in your IdP so your end users can't log in to Fleet. In this separate app, use "https://fleetserver.com/api/v1/fleet/mdm/sso/callback" for the SSO URL.
fleetctl CLI:
1. Create a `fleet-config.yaml` file or add to your existing `config` YAML file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
end_user_authentication:
identity_provider_name: "Okta"
entity_id: "https://fleetserver.com"
issuer_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
metadata_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
...
```
2. Fill in the relevant information from your IdP under the `mdm.end_user_authentication` key.
3. Run the fleetctl `apply -f fleet-config.yml` command to add your IdP credentials.
4. Confirm that your IdP credentials were saved by running `fleetctl get config`.
### Step 2: upload a EULA to Fleet
1. Head to the **Settings > Integrations > Automatic enrollment** page.
2. Under **End user license agreement (EULA)**, select **Upload** and choose your EULA.
> Uploading a EULA is optional. If you don't upload a EULA, the end user will skip this step and continue to the next step of the new Mac setup experience after they authenticate with your IdP.
### Step 3: enable end user authentication
You can enable end user authentication using the Fleet UI or fleetctl command-line tool.
Fleet UI:
1. Head to the **Controls > macOS settings > macOS setup > End user authentication** page.
2. Choose which team you want to enable end user authentication for by selecting the desired team in the teams dropdown in the upper left corner.
3. Select the **On** checkbox and select **Save**.
fleetctl CLI:
1. Choose which team you want to enable end user authentication on.
In this example, we'll enable end user authentication on the "Workstations (canary)" team so that the authentication is only required for hosts that automatically enroll to this team.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to enable authentication on hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
enable_end_user_authentication: true
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.enable_end_user_authentication` key to your YAML document. This key accepts a boolean value.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to enable authentication for this team.
5. Confirm that end user authentication is enabled by running the `fleetctl get teams --name=Workstations --yaml` command.
If you enabled authentication on "No team," run `fleetctl get config`.
You should see a `true` value for `mdm.macos_setup.enable_end_user_authentication`.
## Bootstrap package
Fleet supports installing a bootstrap package on macOS hosts that automatically enroll to Fleet.
This enables installing tools like [Puppet](https://www.puppet.com/), [Munki](https://www.munki.org/munki/), or [Chef](https://www.chef.io/products/chef-infra) for configuration management and/or running custom scripts and installing tools like [DEP notify](https://gitlab.com/Mactroll/DEPNotify) to customize the setup experience for your end users.
The following are examples of what some organizations deploy using a bootstrap package:
* Munki client to install and keep software up to date on your Macs
* Puppet agent to run custom scripts on your Macs
* Custom scripts and several packages bundled into one bootstrap package using a tool like [InstallApplications](https://github.com/macadmins/installapplications) to install a base set of applications, set the Mac's background, and install the latest macOS update for the end user.
To add a bootstrap package to Fleet, we will do the following steps:
1. Download or generate a package
2. Sign the package
3. Upload the package to Fleet
4. Confirm package is uploaded
### Step 1: download or generate a package
Whether you have to download or generate a package depends on what you want to deploy using your bootstrap package:
* A single client or agent, like Munki or Puppet, can usually be downloaded from the tool's GitHub repository or website. For example, you can download Munki, the Munki client on their [releases page on GitHub](https://github.com/munki/munki/releases).
* To deploy custom scripts, you need to generate a package. The [munkipkg tool](https://github.com/munki/munki-pkg) is a popular tool for generating packages.
Apple requires that your package is a distribution package. Verify that the package is a distribution package:
1. Run the following commands to expand your package and look at the files in the expanded folder:
```bash
$ pkgutil --expand package.pkg expanded-package
$ ls expanded-package
```
If your package is a distribution package you should see a `Distribution` file.
2. If you don't see a `Distribution` file, run the following command to convert your package into a distribution package.
```bash
$ productbuild --package package.pkg distrbution-package.pkg
```
Make sure your package is a `.pkg` file.
### Step 2: sign the package
To sign the package we need a valid Developer ID Installer certificate:
1. Login to your [Apple Developer account](https://developer.apple.com/account).
2. Follow Apple's instructions to create a Developer ID Installer certificate [here](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates).
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package.
Confirm that certificate is installed on your Mac by opening the **Keychain Access** application. You should see your certificate in the **Certificates** tab.
3. Run the following command in the **Terminal** application to sign your package with your Developer ID certificate:
```bash
$ productsign --sign "Developer ID Installer: Your name (Serial number)" /path/to/package.pkg /path/to/signed-package.pkg
```
You might be prompted to enter the password for your local account.
Confirm that your package is signed by running the following command:
```bash
$ pkgutil --check-signature /path/to/signed-package.pkg
```
In the output you should see that your package has a "signed" status.
### Step 3: upload the package to Fleet
Fleet UI:
1. Head to the **Controls > macOS settings > macOS setup > Bootstrap package** page.
2. Choose which team you want to add the bootstrap package to by selecting the desired team in the teams dropdown in the upper left corner.
3. Select **Upload** and choose your bootstrap package.
fleetctl CLI:
1. Upload the package to a storage location (ex. S3 or GitHub). During step 4, Fleet will retrieve the package from this storage location and host it for deployment.
> The URL must be accessible by the computer that uploads the package to Fleet.
> This could be your local computer or the computer that runs your CI/CD workflow.
2. Choose which team you want to add the bootstrap package to.
In this example, we'll add a bootstrap package to the "Workstations (canary)" team so that the package only gets installed on hosts that automatically enroll to this team.
3. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to install the package on hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.bootstrap_package` key to your YAML document. This key accepts the URL for the storage location of the bootstrap package.
4. Run the fleetctl `apply -f workstations-canary-config.yml` command to upload your bootstrap package to Fleet.
5. Confirm that your bootstrap package was uploaded to Fleet by running the `fleetctl get teams --name=Workstations --yaml` command.
If you uploaded the package to "No team," run `fleetctl get config`.
You should see the URL for your bootstrap package as the value for `mdm.macos_setup.bootstrap_package`.
## macOS Setup Assistant
When an end user unboxes their new Mac, or starts up a freshly wiped Mac, they're presented with the macOS Setup Assistant. Here they see panes that allow them to configure accessibility, appearance, and more.
In Fleet, you can customize the macOS Setup Assistant by using an automatic enrollment profile.
To customize the macOS Setup Assistant, we will do the following steps:
1. Create an automatic enrollment profile
2. Upload the profile to Fleet
3. Test the custom macOS Setup Assistant
### Step 1: create an automatic enrollment profile
1. Download Fleet's example automatic enrollment profile by navigating to the example [here on GitHub](https://github.com/fleetdm/fleet/blob/main/mdm_profiles/setup_assistant.json) and clicking the download icon.
2. Open the automatic enrollment profile and replace the `profile_name` key with your organization's name.
3. View the the list of macOS Setup Assistant properties (panes) [here in Apple's Device Management documentation](https://developer.apple.com/documentation/devicemanagement/skipkeys) and choose which panes to hide from your end users.
4. In your automatic enrollment profile, edit the `skip_setup_items` array so that it includes the panes you want to hide.
> You can modify properties other than `skip_setup_items`. These are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/profile).
### Step 2: upload the profile to Fleet
1. Choose which team you want to add the automatic enrollment profile to.
In this example, let's assume you have a "Workstations" team as your [default team](./mdm-macos-setup.md#step-6-optional-set-the-default-team-for-hosts-enrolled-via-abm) in Fleet and you want to test your profile before it's used in production.
To do this, we'll create a new "Workstations (canary)" team and add the automatic enrollment profile to it. Only hosts that automatically enroll to this team will see the custom macOS Setup Assistant.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to customize the macOS Setup Assistant for hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.macos_setup_assistant` key to your YAML document. This key accepts a path to your automatic enrollment profile.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to upload the automatic enrollment profile to Fleet.
### Step 3: test the custom macOS Setup Assistant
Testing requires a test Mac that is present in your Apple Business Manager (ABM) account. We will wipe this Mac and use it to test the custom macOS Setup Assistant.
1. Wipe the test Mac by selecting the Apple icon in top left corner of the screen, selecting **System Settings** or **System Preference**, and searching for "Erase all content and settings." Select **Erase All Content and Settings**.
2. In Fleet, navigate to the Hosts page and find your Mac. Make sure that the host's **MDM status** is set to "Pending."
> New Macs purchased through Apple Business Manager appear in Fleet with MDM status set to "Pending." Learn more about these hosts [here](./mdm-macos-setup.md#pending-hosts).
3. Transfer this host to the "Workstations (canary)" team by selecting the checkbox to the left of the host and selecting **Transfer** at the top of the table. In the modal, choose the Workstations (canary) team and select **Transfer**.
4. Boot up your test Mac and complete the custom out-of-the-box setup experience.
<meta name="pageOrderInSection" value="1506">
<meta name="title" value="macOS setup experience">
<meta name="description" value="Customize your macOS setup experience with Fleet Premium by managing user authentication, Setup Assistant panes, and installing bootstrap packages.">
<meta name="navSection" value="Device management">

485
docs/Using Fleet/MDM-macOS-setup.md
View File

@ -1,345 +1,286 @@
# macOS setup # macOS setup
_Available in Fleet Premium_ ## Overview
In Fleet, you can customize the out-of-the-box macOS setup experience for your end users: 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.
* Require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac. [Automated Device Enrollment](https://support.apple.com/en-us/HT204142) 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.
* Customize the macOS Setup Assistant by choosing to show or hide specific panes. > **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."
* Install a bootstrap package to gain full control over the setup experience by installing tools like Puppet, Munki, DEP notify, custom scrips, and more. ## Requirements
To use Fleet's MDM features you need to have:
- A [deployed Fleet instance](../Deploying/Introduction.md).
- A Fleet user with the admin role.
In addition to the customization above, Fleet automatically installs the fleetd agent during out-of-the-box macOS setup. This agent is responsible for reporting host vitals to Fleet and presenting Fleet Desktop to the end user. ## Apple Push Notification service (APNs)
Apple uses APNs to authenticate and manage interactions between Fleet and the host.
MacOS setup features require connecting Fleet to Apple Business Manager (ABM). Learn how [here](./MDM-setup.md#apple-business-manager-abm). This section will show you how to:
1. Generate the files to connect Fleet to APNs.
2. Generate an APNs certificate from Apple Push Certificates Portal.
3. Configure Fleet with the required files.
## End user authentication and EULA ### Step 1: generate the required files
For the MDM protocol to function, we need to generate the four following files:
- APNs certificate
- APNs private key
- Simple Certificate Enrollment Protocol (SCEP) certificate
- SCEP private key
Using Fleet, you can require end users to authenticate with your identity provider (IdP) and agree to an end user license agreement (EULA) before they can use their new Mac. The APNs certificates serve as authentication between Fleet and Apple, while the SCEP certificates serve as authentication between Fleet and hosts.
To require end user authentication, we will do the following steps: Use either of the following methods to generate the necessary files:
1. Connect Fleet to your IdP #### Fleet UI
2. Upload a EULA to Fleet (optional)
3. Enable end user authentication
### Step 1: connect Fleet to your IdP 1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Push Certificates Portal**, select **Request**, then fill out the form. This should generate three files and send an email to you with an attached CSR file.
Fleet UI: #### Fleetctl CLI
1. Head to the **Settings > Integrations > Automatic enrollment** page. Run the following command to download three files and send an email to you with an attached CSR file.
2. Under **End user authentication**, enter your IdP credentials and select **Save**. ```sh
fleetctl generate mdm-apple --email <email> --org <org>
> If you've already configured [single sign-on (SSO) for logging in to Fleet](https://fleetdm.com/docs/configuration/fleet-server-configuration#okta-idp-configuration), you'll need to create a separate app in your IdP so your end users can't log in to Fleet. In this separate app, use "https://fleetserver.com/api/v1/fleet/mdm/sso/callback" for the SSO URL.
fleetctl CLI:
1. Create `fleet-config.yaml` file or add to your existing `config` YAML file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
end_user_authentication:
identity_provider_name: "Okta"
entity_id: "https://fleetserver.com"
issuer_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
metadata_url: "https://okta-instance.okta.com/84598y345hjdsshsfg/sso/saml/metadata"
...
``` ```
2. Fill in the relevant information from your IdP under the `mdm.end_user_authentication` key. ### Step 2: generate an APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com).
2. Select **Create a Certificate**.
3. Upload your CSR and input a friendly name, such as "Fleet."
4. Download the APNs certificate.
3. Run the fleetctl `apply -f fleet-config.yml` command to add your IdP credentials. > **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.
4. Confirm that your IdP credentials were saved by running `fleetctl get config`. ### Step 3: configure Fleet with the generated files
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:
### Step 2: upload a EULA to Fleet > Note: Any environment variable that ends in `_BYTES` expects the file's actual content to be passed in, not a path to the file. If you want to pass in a file path, remove the `_BYTES` suffix from the environment variable.
1. Head to the **Settings > Integrations > Automatic enrollment** page. * [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-cert-bytes)
* [FLEET_MDM_APPLE_SCEP_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CHALLENGE](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-challenge)
2. Under **End user license agreement (EULA)**, select **Upload** and choose your EULA. > You do not need to provide the APNs CSR which was emailed to you.
> Uploading a EULA is optional. If you don't upload a EULA, the end user will skip this step and continue to the next step of the new Mac setup experience after they authenticate with your IdP. ### Step 4: confirm that Fleet is set up correctly
### Step 3: enable end user authentication 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.
You can enable end user authentication using the Fleet UI or fleetctl command-line tool. #### Fleet UI
Fleet UI: Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
1. Head to the **Controls > macOS settings > macOS setup > End user authentication** page. #### Fleetctl CLI
2. Choose which team you want to enable end user authentication for by selecting the desired team in the teams dropdown in the upper left corner. ```
fleetctl get mdm-apple
3. Select the **On** checkbox and select **Save**.
fleetctl CLI:
1. Choose which team you want to enable end user authentication on.
In this example, we'll enable end user authentication on the "Workstations (canary)" team so that the authentication is only required for hosts that automatically enroll to this team.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
enable_end_user_authentication: true
...
``` ```
Learn more about team configurations options [here](./configuration-files/README.md#teams). ## Renewing APNs
If you want to enable authentication on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file: > **Important:** Apple requires that APNs certificates are renewed annually.
> - 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.
```yaml This section will guide you through how to:
apiVersion: v1 1. Generate the files required to renew your APNs certificate.
kind: config 2. Renew your APNs certificate in Apple Push Certificates Portal.
spec: 3. Configure Fleet with the required files.
mdm: 4. Confirm that Fleet is set up correctly.
macos_setup:
enable_end_user_authentication: true Use either of the following methods to see your APNs certificate's renewal date and other important information:
...
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
``` ```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings). ### Step 1: generate the required files
- A new APNs certificate.
- A new APNs private key.
3. Add an `mdm.macos_setup.enable_end_user_authentication` key to your YAML document. This key accepts a boolean value. 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.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to enable authentication for this team. ```sh
fleetctl generate mdm-apple --email <email> --org <org>
5. Confirm that end user authentication is enabled by running the `fleetctl get teams --name=Workstations --yaml` command.
If you enabled authentication on "No team," run `fleetctl get config`.
You should see a `true` value for `mdm.macos_setup.enable_end_user_authentication`.
## Bootstrap package
Fleet supports installing a bootstrap package on macOS hosts that automatically enroll to Fleet.
This enables installing tools like [Puppet](https://www.puppet.com/), [Munki](https://www.munki.org/munki/), or [Chef](https://www.chef.io/products/chef-infra) for configuration management and/or running custom scrips and installing tools like [DEP notify](https://gitlab.com/Mactroll/DEPNotify) to customize the setup experience for you end users.
The following are examples of what some organizations deploy using a bootstrap package:
* Munki client to install and keep software up to date on your Macs
* Puppet agent to run custom scripts on your Macs
* Custom scripts and several packages bundled into one bootstrap package using a tool like [InstallApplications](https://github.com/macadmins/installapplications) to install a base set of applications, set the Mac's background, and install the latest macOS update for the end user.
To add a bootstrap package to Fleet, we will do the following steps:
1. Download or generate a package
2. Sign the package
3. Upload the package to Fleet
4. Confirm package is uploaded
### Step 1: download or generate a package
Whether you have to download or generate a package depends on what you want to deploy using your bootstrap package:
* A single client or agent, like Munki or Puppet, can usually be downloaded from the tool's GitHub repository or website. For example, you can download Munki, the Munki client on their [releases page on GitHub](https://github.com/munki/munki/releases).
* To deploy custom scripts, you need to generate a package. The [munkipkg tool](https://github.com/munki/munki-pkg) is a popular tool for generating packages.
Apple requires that your package is a distribution package. Verify that the package is a distribution package:
1. Run the following commands to expand you package and look at the files in the expanded folder:
```bash
$ pkgutil --expand package.pkg expanded-package
$ ls expanded-package
``` ```
If your package is a distribution package should see a `Distribution` file. ### Step 2: renew APNs certificate
2. If you don't see a `Distribution` file, run the following command to convert your package into a distribution package. 1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com) using the same Apple ID you used to get your original APNs certificate.
2. Click **Renew** next to the expired certificate.
3. Upload your CSR.
4. Download the new APNs certificate.
```bash ### Step 3: configure Fleet with the generated files
$ productbuild --package package.pkg distrbution-package.pkg Restart the Fleet server with the contents of the APNs certificate and APNs private key in following environment variables:
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Follow the on-screen instructions in the **Apple Push Certificates Portal** section.
#### Fleetctl CLI:
Run the following command. You should see information about the new APNs certificate such as serial number and renewal date.
```sh
fleetctl get mdm-apple
``` ```
Make sure your package is a `.pkg` file. ## Renewing SCEP
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.
### Step 2: sign the package ## Apple Business Manager (ABM)
To sign the package we need a valid Developer ID Installer certificate: > Available in Fleet Premium
1. Login to your [Apple Developer account](https://developer.apple.com/account). 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.
2. Follow Apple's instructions to create a Developer ID Installer certificate [here](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates).
> During step 3 in Apple's instructions, make sure you choose "Developer ID Installer." You'll need this kind of certificate to sign the package. This section will guide you through how to:
Confirm that certificate is installed on your Mac by opening the **Keychain Access** application. You should see your certificate in the **Certificates** tab. 1. Generate certificate and private key for ABM
2. Create a new MDM server record for Fleet in ABM
3. Download the MDM server token from ABM
4. Upload the server token, certificate, and private key to the Fleet server
5. Set the new MDM server as the auto-enrollment server for Macs in ABM
3. Run the following command in the **Terminal** application to sign your package with your Developer ID certificate: ### Step 1: generate the required certificate and private key
```bash User either of the following methods to generate a certificate and private key pair. This pair is how Fleet authenticates itself to ABM:
$ productsign --sign "Developer ID Installer: Your name (Serial number)" /path/to/package.pkg /path/to/signed-package.pkg
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Business Manager**, click the "Download" button
#### Fleetctl CLI:
```sh
fleetctl generate mdm-apple-bm
``` ```
You might be prompted to enter the password for your local account. ### Step 2: create a new MDM server in ABM
Confirm that your package is signed by running the following command: Create an MDM server record in ABM which represents Fleet:
```bash 1. Log in to or enroll in [ABM](https://business.apple.com)
$ pkgutil --check-signature /path/to/signed-package.pkg 2. Click your name at the bottom left of the screen
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Click the **Add** button at the top
6. Enter a name for the server such as "Fleet"
7. Upload the certificate generated in Step 1
### Step 3: download the server token
In the details page of the newly created server, click **Download Token** at the top. You should receive a `.p7m` file.
### Step 4: upload server token, certificate, and private key to Fleet
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:
* [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
* [FLEET_MDM_APPLE_BM_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-cert-bytes)
* [FLEET_MDM_APPLE_BM_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-key-bytes)
### Step 3: confirm that Fleet is set up correctly
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.
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Navigate to the **Apple Business Manager** section.
#### Fleetctl CLI:
```sh
fleetctl get mdm-apple
``` ```
In the output you should see that package has a "signed" status. ### Step 5: set Fleet to be the MDM server for Macs in ABM
Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized reseller:
### Step 3: upload the package to Fleet 1. Log in to [Apple Business Manager](https://business.apple.com)
2. Click your profile icon in the bottom left
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Switch Macs to the new Fleet instance.
Fleet UI: ### Step 6 (optional): set the default team for hosts enrolled via ABM
1. Head to the **Controls > macOS settings > macOS setup > Bootstrap package** page. 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".
2. Choose which team you want to add the bootstrap package to by selecting the desired team in the teams dropdown in the upper left corner. > A host can be transferred to a new (not default) team before it enrolls. Learn how [here](./Teams.md#transfer-hosts-to-a-team). Transferring a host will automatically enforce the new team's settings when it enrolls.
3. Select **Upload** and choose your bootstrap package. Use either of the following methods to change the default team:
fleetctl CLI: #### Fleet UI
1. Upload the package to a storage location (ex. S3 or GitHub). During step 4, Fleet will retrieve the package from this storage location and host it for deployment. 1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
> The URL must be accessible by the computer that uploads the package to Fleet. 2. In the Apple Business Manager section, select the **Edit team** button next to **Default team**.
> * This could be your local computer or the computer that runs your CI/CD workflow.
2. Choose which team you want to add the bootstrap package to. 3. Choose a team and select **Save**.
In this example, we'll add a bootstrap package to the "Workstations (canary)" team so that the package only gets installed on hosts that automatically enroll to this team. #### Fleetctl CLI
3. Create a `workstations-canary-config.yaml` file: 1. Create a `config` YAML document if you don't have one already. Learn how [here](./configuration-files/README.md#organization-settings). This document is used to change settings in Fleet.
```yaml 2. Set the `mdm.apple_bm_default_team` configuration option to the desired team's name.
apiVersion: v1
kind: team 3. Run the `fleetctl apply -f <your-YAML-file-here>` command.
spec:
team: ### Pending hosts
name: Workstations (canary) 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.
mdm:
macos_setup: ## Renewing ABM
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
... > 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:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Look at the **Apple Business Manager** section.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
``` ```
Learn more about team configurations options [here](./configuration-files/README.md#teams). 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](https://support.apple.com/en-ca/guide/apple-business-manager/axme0f8659ec/web), the token expires after a year or whenever the account that downloaded the token has their password changed.
If you want to install the package on hosts that automatically enroll to "No team," we'll need to create an `fleet-config.yaml` file: To renew the token:
1. Log in to [business.apple.com](https://business.apple.com)
2. Select Fleet's MDM server record
3. Download a new token for that server record
4. In your Fleet server, update the environment variable [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
5. Restart the Fleet server
```yaml <meta name="pageOrderInSection" value="1500">
apiVersion: v1 <meta name="title" value="macOS setup">
kind: config <meta name="description" value="Learn how to configure Fleet to use Apple's Push Notification service and connect to Apple Business Manager.">
spec:
mdm:
macos_setup:
bootstrap_package: https://github.com/organinzation/repository/bootstrap-package.pkg
...
```
Learn more about "No team" configuration options [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.bootstrap_package` key to your YAML document. This key accepts the URL for the storage location of the bootstrap package.
4. Run the fleetctl `apply -f workstations-canary-config.yml` command to upload your bootstrap package to Fleet.
5. Confirm that your bootstrap package was uploaded to Fleet by running the `fleetctl get teams --name=Workstations --yaml` command.
If you uploaded the package to "No team," run `fleetctl get config`.
You should see the URL for your bootstrap package as the value for `mdm.macos_setup.bootstrap_package`.
## macOS Setup Assistant
When an end user unboxes their new Mac, or starts up a freshly wiped Mac, they're presented with the macOS Setup Assistant. Here they see panes that allow them to configure accessibility, appearance, and more.
In Fleet, you can customize the macOS Setup Assistant by using an automatic enrollment profile.
To customize the macOS Setup Assistant, we will do the following steps:
1. Create an automatic enrollment profile
2. Upload the profile to Fleet
3. Test the custom macOS Setup Assistant
### Step 1: create an automatic enrollment profile
1. Download Fleet's example automatic enrollment profile by navigating to the example [here on GitHub](https://github.com/fleetdm/fleet/blob/main/mdm_profiles/setup_assistant.json) and clicking the download icon.
2. Open the automatic enrollment profile and replace the `profile_name` key with your organization's name.
3. View the the list of macOS Setup Assistant properties (panes) [here in Apple's Device Management documentation](https://developer.apple.com/documentation/devicemanagement/skipkeys) and choose which panes to hide from your end users.
4. In your automatic enrollment profile, edit the `skip_setup_items` array so that it includes the panes you want to hide.
> You can modify properties other than `skip_setup_items`. These are documented by Apple [here](https://developer.apple.com/documentation/devicemanagement/profile).
### Step 2: upload the profile to Fleet
1. Choose which team you want to add the automatic enrollment profile to.
In this example, let's assume you have a "Workstations" team as your [default team](./MDM-setup.md#step-6-optional-set-the-default-team-for-hosts-enrolled-via-abm) in Fleet and you want to test your profile before it's used in production.
To do this, we'll create a new "Workstations (canary)" team and add the automatic enrollment profile to it. Only hosts that automatically enroll to this team will see the custom macOS Setup Assistant.
2. Create a `workstations-canary-config.yaml` file:
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Workstations (canary)
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about team configurations options [here](./configuration-files/README.md#teams).
If you want to customize the macOS Setup Assistant for hosts that automatically enroll to "No team," we'll need to create a `fleet-config.yaml` file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_setup:
macos_setup_assistant: ./path/to/automatic_enrollment_profile.json
...
```
Learn more about configuration options for hosts that aren't assigned to a team [here](./configuration-files/README.md#organization-settings).
3. Add an `mdm.macos_setup.macos_setup_assistant` key to your YAML document. This key accepts a path to your automatic enrollment profile.
4. Run the `fleetctl apply -f workstations-canary-config.yml` command to upload the automatic enrollment profile to Fleet.
### Step 3: test the custom macOS Setup Assistant
Testing requires a test Mac that is present in your Apple Business Manager (ABM) account. We will wipe this Mac and use it to test the custom macOS Setup Assistant.
1. Wipe the test Mac by selecting the Apple icon in top left corner of the screen, selecting **System Settings** or **System Preference**, and searching for "Erase all content and settings." Select **Erase All Content and Settings**.
2. In Fleet, navigate to the Hosts page and find your Mac. Make sure that the host's **MDM status** is set to "Pending."
> New Macs purchased through Apple Business Manager appear in Fleet with MDM status set to "Pending." Learn more about these hosts [here](./MDM-setup.md#pending-hosts).
3. Transfer this host to the "Workstations (canary)" team by selecting the checkbox to the left of the host and selecting **Transfer** at the top of the table. In the modal, choose the Workstations (canary) team and select **Transfer**.
4. Boot up your test Mac and complete the custom out-of-the-box setup experience.
<meta name="pageOrderInSection" value="1505">
<meta name="title" value="MDM macOS setup">
<meta name="description" value="Customize your macOS setup experience with Fleet Premium by managing user authentication, Setup Assistant panes, and installing bootstrap packages.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

4
docs/Using Fleet/MDM-macOS-updates.md
View File

@ -158,7 +158,7 @@ Request payload:
</plist> </plist>
``` ```
<meta name="pageOrderInSection" value="1502"> <meta name="pageOrderInSection" value="1503">
<meta name="title" value="MDM macOS updates"> <meta name="title" value="macOS updates">
<meta name="description" value="Learn how to manage macOS updates and set up end user reminders with Fleet MDM."> <meta name="description" value="Learn how to manage macOS updates and set up end user reminders with Fleet MDM.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

10
docs/Using Fleet/MDM-migration-guide.md
View File

@ -1,11 +1,11 @@
# Migration # Migration guide
This section provides instructions for migrating your hosts away from your old MDM solution to Fleet. This section provides instructions for migrating your hosts away from your old MDM solution to Fleet.
## Requirements ## Requirements
1. A [deployed Fleet instance](../Deploying/Introduction.md) 1. A [deployed Fleet instance](../Deploying/Introduction.md)
2. [Fleet connected to Apple](./MDM-setup.md) 2. [Fleet connected to Apple](./mdm-macos-setup.md)
## Migrate manually enrolled hosts ## Migrate manually enrolled hosts
@ -46,7 +46,7 @@ To migrate automatically enrolled hosts, we will do the following steps:
### Step 1: prepare to migrate hosts ### Step 1: prepare to migrate hosts
1. Connect Fleet to Apple Business Manager (ABM). Learn how [here](./MDM-setup.md#apple-business-manager-abm). 1. Connect Fleet to Apple Business Manager (ABM). Learn how [here](./mdm-macos-setup.md#apple-business-manager-abm).
2. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop) 2. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
3. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account. 3. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
4. Migrate your hosts to Fleet in ABM: 4. Migrate your hosts to Fleet in ABM:
@ -220,7 +220,7 @@ For all other settings:
<img width="1399" alt="My device page - turn on disk encryption" src="https://user-images.githubusercontent.com/5359586/229950451-cfcd2314-a993-48db-aecf-11aac576d297.png"> <img width="1399" alt="My device page - turn on disk encryption" src="https://user-images.githubusercontent.com/5359586/229950451-cfcd2314-a993-48db-aecf-11aac576d297.png">
<meta name="pageOrderInSection" value="1501"> <meta name="pageOrderInSection" value="1502">
<meta name="title" value="MDM migration guide"> <meta name="title" value="Migration guide">
<meta name="description" value="Instructions for migrating hosts away from an old MDM solution to Fleet."> <meta name="description" value="Instructions for migrating hosts away from an old MDM solution to Fleet.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

286
docs/Using Fleet/MDM-setup.md
View File

@ -1,286 +0,0 @@
# MDM setup
## Overview
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](https://support.apple.com/en-us/HT204142) 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."
## Requirements
To use Fleet's MDM features you need to have:
- A [deployed Fleet instance](../Deploying/Introduction.md).
- A Fleet user with the admin role.
## Apple Push Notification service (APNs)
Apple uses APNs to authenticate and manage interactions between Fleet and the host.
This section will show you how to:
1. Generate the files to connect Fleet to APNs.
2. Generate an APNs certificate from Apple Push Certificates Portal.
3. Configure Fleet with the required files.
### Step 1: generate the required files
For the MDM protocol to function, we need to generate the four following files:
- APNs certificate
- APNs private key
- Simple Certificate Enrollment Protocol (SCEP) certificate
- SCEP private key
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:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Push Certificates Portal**, select **Request**, then fill out the form. This should generate three files and send an email to you with an attached CSR file.
#### Fleetctl CLI
Run the following command to download three files and send an email to you with an attached CSR file.
```sh
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: generate an APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com).
2. Select **Create a Certificate**.
3. Upload your CSR and input a friendly name, such as "Fleet."
4. Download the APNs certificate.
> **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.
### Step 3: configure Fleet with the generated files
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:
> Note: Any environment variable that ends in `_BYTES` expects the file's actual content to be passed in, not a path to the file. If you want to pass in a file path, remove the `_BYTES` suffix from the environment variable.
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-cert-bytes)
* [FLEET_MDM_APPLE_SCEP_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-key-bytes)
* [FLEET_MDM_APPLE_SCEP_CHALLENGE](https://fleetdm.com/docs/deploying/configuration#mdm-apple-scep-challenge)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
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.
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
```
## Renewing APNs
> **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:
1. Generate the files required to renew your APNs certificate.
2. Renew your APNs certificate in Apple Push Certificates Portal.
3. Configure Fleet with the required files.
4. Confirm that Fleet is set up correctly.
Use either of the following methods to see your APNs certificate's renewal date and other important information:
#### Fleet UI
Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
#### Fleetctl CLI
```sh
fleetctl get mdm-apple
```
### Step 1: generate the required files
- A new APNs certificate.
- A new APNs private key.
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.
```sh
fleetctl generate mdm-apple --email <email> --org <org>
```
### Step 2: renew APNs certificate
1. Log in to or enroll in [Apple Push Certificates Portal](https://identity.apple.com) using the same Apple ID you used to get your original APNs certificate.
2. Click **Renew** next to the expired certificate.
3. Upload your CSR.
4. Download the new APNs certificate.
### Step 3: configure Fleet with the generated files
Restart the Fleet server with the contents of the APNs certificate and APNs private key in following environment variables:
* [FLEET_MDM_APPLE_APNS_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-cert-bytes)
* [FLEET_MDM_APPLE_APNS_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-apns-key-bytes)
> You do not need to provide the APNs CSR which was emailed to you.
### Step 4: confirm that Fleet is set up correctly
Use either of the following methods to confirm that Fleet is set up:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Follow the on-screen instructions in the **Apple Push Certificates Portal** section.
#### Fleetctl CLI:
Run the following command. You should see information about the new APNs certificate such as serial number and renewal date.
```sh
fleetctl get mdm-apple
```
## Renewing SCEP
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.
## Apple Business Manager (ABM)
> 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:
1. Generate certificate and private key for ABM
2. Create a new MDM server record for Fleet in ABM
3. Download the MDM server token from ABM
4. Upload the server token, certificate, and private key to the Fleet server
5. Set the new MDM server as the auto-enrollment server for Macs in ABM
### Step 1: generate the required certificate and private key
User either of the following methods to generate a certificate and private key pair. This pair is how Fleet authenticates itself to ABM:
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Under **Apple Business Manager**, click the "Download" button
#### Fleetctl CLI:
```sh
fleetctl generate mdm-apple-bm
```
### Step 2: create a new MDM server in ABM
Create an MDM server record in ABM which represents Fleet:
1. Log in to or enroll in [ABM](https://business.apple.com)
2. Click your name at the bottom left of the screen
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Click the **Add** button at the top
6. Enter a name for the server such as "Fleet"
7. Upload the certificate generated in Step 1
### Step 3: download the server token
In the details page of the newly created server, click **Download Token** at the top. You should receive a `.p7m` file.
### Step 4: upload server token, certificate, and private key to Fleet
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:
* [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
* [FLEET_MDM_APPLE_BM_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-cert-bytes)
* [FLEET_MDM_APPLE_BM_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-key-bytes)
### Step 3: confirm that Fleet is set up correctly
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.
#### Fleet UI:
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Navigate to the **Apple Business Manager** section.
#### Fleetctl CLI:
```sh
fleetctl get mdm-apple
```
### Step 5: set Fleet to be the MDM server for Macs in ABM
Set Fleet to be the MDM for all future Macs purchased via Apple or an authorized reseller:
1. Log in to [Apple Business Manager](https://business.apple.com)
2. Click your profile icon in the bottom left
3. Click **Preferences**
4. Click **MDM Server Assignment**
5. Switch Macs to the new Fleet instance.
### Step 6 (optional): set the default team for hosts enrolled via ABM
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](./Teams.md#transfer-hosts-to-a-team). 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:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. In the Apple Business Manager section, select the **Edit team** button next to **Default team**.
3. Choose a team and select **Save**.
#### Fleetctl CLI
1. Create a `config` YAML document if you don't have one already. Learn how [here](./configuration-files/README.md#organization-settings). This document is used to change settings in Fleet.
2. Set the `mdm.apple_bm_default_team` configuration option to the desired team's name.
3. Run the `fleetctl apply -f <your-YAML-file-here>` command.
### Pending hosts
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.
## Renewing ABM
> 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:
#### Fleet UI
1. Navigate to the **Settings > Integrations > Mobile device management (MDM)** page.
2. Look at the **Apple Business Manager** section.
#### Fleetctl CLI
```sh
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](https://support.apple.com/en-ca/guide/apple-business-manager/axme0f8659ec/web), the token expires after a year or whenever the account that downloaded the token has their password changed.
To renew the token:
1. Log in to [business.apple.com](https://business.apple.com)
2. Select Fleet's MDM server record
3. Download a new token for that server record
4. In your Fleet server, update the environment variable [FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-apple-bm-server-token-bytes)
5. Restart the Fleet server
<meta name="pageOrderInSection" value="1500">
<meta name="title" value="MDM setup">
<meta name="description" value="Learn how to configure Fleet to use Apple's Push Notification service and connect to Apple Business Manager.">
<meta name="navSection" value="Device management">

2
docs/Using Fleet/Puppet-module.md
View File

@ -151,7 +151,7 @@ if $err != '' {
The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](./MDM-commands.md). The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](./MDM-commands.md).
<meta name="pageOrderInSection" value="1508"> <meta name="pageOrderInSection" value="1509">
<meta name="title" value="Puppet module"> <meta name="title" value="Puppet module">
<meta name="description" value="Learn how to use Fleet's Puppet module to automatically assign custom configuration profiles on your macOS hosts."> <meta name="description" value="Learn how to use Fleet's Puppet module to automatically assign custom configuration profiles on your macOS hosts.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

4
docs/Using Fleet/Scripts.md
View File

@ -49,7 +49,7 @@ osascript -e 'tell application "Finder" to set desktop picture to POSIX file "'"
1. Run this fleetctl command: 1. Run this fleetctl command:
```sh ```sh
fleetctl run-script --script_path=set-wallpaper-to-fleet.sh --host=hostname` fleetctl run-script --script-path=set-wallpaper-to-fleet.sh --host=hostname
``` ```
> Replace --host flag with your target host's hostname. > Replace --host flag with your target host's hostname.
@ -64,7 +64,7 @@ Script execution can only be enabled by someone with root access to the host.
Turning MDM on for a macOS host or pushing a new fleetd agent qualify as root access. Turning MDM on for a macOS host or pushing a new fleetd agent qualify as root access.
<meta name="pageOrderInSection" value="1506"> <meta name="pageOrderInSection" value="1508">
<meta name="title" value="Scripts"> <meta name="title" value="Scripts">
<meta name="description" value="Learn how to execute a custom script on macOS, Windows, and Linux hosts in Fleet."> <meta name="description" value="Learn how to execute a custom script on macOS, Windows, and Linux hosts in Fleet.">
<meta name="navSection" value="Device management"> <meta name="navSection" value="Device management">

2
docs/Using Fleet/Usage-statistics.md
View File

@ -126,6 +126,8 @@ To disable usage statistics:
3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings." 3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings."
Usage statistics can also be disabled via [configuration files](https://fleetdm.com/docs/configuration/configuration-files#server-settings-enable-analytics).
<meta name="pageOrderInSection" value="1100"> <meta name="pageOrderInSection" value="1100">
<meta name="description" value="Learn about Fleet's usage statistics and what information is collected."> <meta name="description" value="Learn about Fleet's usage statistics and what information is collected.">
<meta name="navSection" value="Dig deeper"> <meta name="navSection" value="Dig deeper">

1
docs/Using Fleet/enroll-chromebooks.md
View File

@ -23,7 +23,6 @@ By default, the hostname for a Chromebook host will be blank. The hostname can b
## Debugging ChromeOS ## Debugging ChromeOS
To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension). To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension).
<meta name="title" value="Enroll Chromebooks"> <meta name="title" value="Enroll Chromebooks">
<meta name="pageOrderInSection" value="2000"> <meta name="pageOrderInSection" value="2000">
<meta name="navSection" value="Dig deeper"> <meta name="navSection" value="Dig deeper">

35
docs/Using Fleet/enroll-hosts.md
View File

@ -314,9 +314,27 @@ expiration setting. To configure this setting, in the Fleet UI, head to **Settin
> The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using [Google Admin](https://admin.google.com). It is not intended for non-ChromeOS hosts with the Chrome browser installed. > The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using [Google Admin](https://admin.google.com). It is not intended for non-ChromeOS hosts with the Chrome browser installed.
### Overview
Google Admin uses organizational units (OUs) to organize devices and users.
One limitation in Google Admin is that extensions can only be configured at the user level, meaning that a user with a MacBook running Chrome, for example, will also get the fleetd Chrome extension.
When deployed on OSs other than ChromeOS, the fleetd Chrome extension will not perform any operation and will not appear in the Chrome toolbar.
However, it will appear in the "Manage Extensions" page of Chrome.
Fleet admins who are comfortable with this situation can skip step 2 below.
To install the fleetd Chrome extension on Google Admin, there are two steps:
1. Create an OU for all users who have Chromebooks and force-install the fleetd Chrome extension for those users
2. Create an OU for all non-Chromebook devices and block the fleetd Chrome extension on this OU
> More complex setups may be necessary, depending on the organization's needs, but the basic principle remains the same.
### Step 1: OU for Chromebook users
Create an [organizational unit](https://support.google.com/a/answer/182537?hl=en) where the extension should be installed. [Add all the relevant users](https://support.google.com/a/answer/182449?hl=en) to this OU.
Visit the Google Admin console. In the navigation menu, visit Devices > Chrome > Apps & Extensions > Users & browsers. Visit the Google Admin console. In the navigation menu, visit Devices > Chrome > Apps & Extensions > Users & browsers.
Select the relevant organizational unit, users, or group where you want the fleetd Chrome extension to be installed. Select the relevant OU where you want the fleetd Chrome extension to be installed.
> Currently, the Chrome extension can only be installed across the entire organization. The work to enable installation for sub-groups is tracked in https://github.com/fleetdm/fleet/issues/13353. > Currently, the Chrome extension can only be installed across the entire organization. The work to enable installation for sub-groups is tracked in https://github.com/fleetdm/fleet/issues/13353.
@ -330,6 +348,21 @@ Under "Installation Policy", select "Force install". Under "Update URL", select
> For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above > For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above
### Step 2: OU to block non-Chromebook devices
Create an [organizational unit](https://support.google.com/a/answer/182537?hl=en) to house devices where the extension should not be installed. [Add all the relevant devices](https://support.google.com/chrome/a/answer/2978876?hl=en) to this OU.
In the Google Admin console, in the navigation menu, visit Devices > Chrome > Managed Browsers.
Select the relevant OU where you want the fleetd Chrome extension to be blocked.
In the bottom right, click the yellow "+" button and select "Add Chrome app or extension by ID."
Visit your Fleet instance and select Hosts > Add Hosts and select ChromeOS in the popup modal.
Enter the "Extension ID" and "Installation URL" using the data provided in the modal.
Under "Installation Policy", select "Block".
## Grant full disk access to osquery on macOS ## Grant full disk access to osquery on macOS
macOS does not allow applications to access all system files by default. If you are using MDM, which macOS does not allow applications to access all system files by default. If you are using MDM, which
is required to deploy these profiles, you is required to deploy these profiles, you

2
docs/Using Fleet/fleetctl-CLI.md
View File

@ -202,7 +202,7 @@ An API-only user does not have access to the Fleet UI. Instead, it's only purpos
To create your new API-only user, run `fleetctl user create` and pass values for `--name`, `--email`, and `--password`, and include the `--api-only` flag: To create your new API-only user, run `fleetctl user create` and pass values for `--name`, `--email`, and `--password`, and include the `--api-only` flag:
```sh ```sh
fleetctl user create --name "API User" --email api@example.com --password temp!pass --api-only fleetctl user create --name "API User" --email api@example.com --password temp@pass123 --api-only
``` ```
### Creating an API-only user ### Creating an API-only user

2
ee/server/service/mdm.go
View File

@ -78,7 +78,7 @@ func getAppleBMAccountDetail(ctx context.Context, depStorage storage.AllStorage,
// Request. // Request.
msg := err.Error() msg := err.Error()
if authErr.StatusCode == http.StatusUnauthorized { if authErr.StatusCode == http.StatusUnauthorized {
msg = "The Apple Business Manager certificate or server token is invalid. Restart Fleet with a valid certificate and token. See https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm for help." msg = "The Apple Business Manager certificate or server token is invalid. Restart Fleet with a valid certificate and token. See https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-business-manager-abm for help."
} }
return nil, ctxerr.Wrap(ctx, &fleet.BadRequestError{ return nil, ctxerr.Wrap(ctx, &fleet.BadRequestError{
Message: msg, Message: msg,

2
frontend/pages/ManageControlsPage/SetupExperience/cards/BootstrapPackage/components/BootstrapPackageUploader/BootstrapPackageUploader.tsx
View File

@ -60,7 +60,7 @@ const BootstrapPackageUploader = ({
(ex. Munki, Chef, or Puppet) on hosts that automatically enroll to (ex. Munki, Chef, or Puppet) on hosts that automatically enroll to
Fleet.{" "} Fleet.{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup#bootstrap-package" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package"
text="Learn more" text="Learn more"
newTab newTab
/> />

2
frontend/pages/ManageControlsPage/SetupExperience/cards/BootstrapPackage/components/UploadedPackageView/UploadedPackageView.tsx
View File

@ -28,7 +28,7 @@ const UploadedPackageView = ({
This package is automatically installed on hosts that automatically This package is automatically installed on hosts that automatically
enroll to this team. Delete the package to upload a new one.{" "} enroll to this team. Delete the package to upload a new one.{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience"
text="Learn more" text="Learn more"
newTab newTab
/> />

2
frontend/pages/admin/IntegrationsPage/cards/AutomaticEnrollment/components/AppleBusinessManagerSection/AppleBusinessManagerSection.tsx
View File

@ -129,7 +129,7 @@ const AppleBusinessManagerSection = ({
<span className={`${baseClass}__400-error-info`}> <span className={`${baseClass}__400-error-info`}>
See our{" "} See our{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-business-manager-abm"
text="ABM documentation" text="ABM documentation"
newTab newTab
/>{" "} />{" "}

2
frontend/pages/admin/IntegrationsPage/cards/AutomaticEnrollment/components/EulaSection/components/EulaUploader/EulaUploader.tsx
View File

@ -56,7 +56,7 @@ const EulaUploader = ({ onUpload }: IEulaUploaderProps) => {
Require end users to agree to a EULA when they first setup their new Require end users to agree to a EULA when they first setup their new
macOS hosts.{" "} macOS hosts.{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience"
text="Learn more" text="Learn more"
newTab newTab
/> />

2
frontend/pages/admin/IntegrationsPage/cards/AutomaticEnrollment/components/EulaSection/components/UploadedEulaView/UploadedEulaView.tsx
View File

@ -23,7 +23,7 @@ const UploadedEulaView = ({
Require end users to agree to a EULA when they first setup their new Require end users to agree to a EULA when they first setup their new
macOS hosts.{" "} macOS hosts.{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup#end-user-authentication" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula"
text="Learn more" text="Learn more"
newTab newTab
/> />

2
frontend/pages/admin/IntegrationsPage/cards/AutomaticEnrollment/components/IdpSection/IdpSection.tsx
View File

@ -79,7 +79,7 @@ const IdpSection = () => {
Connect Fleet to your identity provider to require end users to Connect Fleet to your identity provider to require end users to
authenticate when they first setup their new macOS hosts.{" "} authenticate when they first setup their new macOS hosts.{" "}
<CustomLink <CustomLink
url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup#end-user-authentication" url="https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience##end-user-authentication-and-eula"
text="Learn more" text="Learn more"
newTab newTab
/> />

1
handbook/business-operations/README.md
View File

@ -217,6 +217,7 @@ The following table lists this department's rituals, frequency, and Directly Res
| Vanta check | Monthly | Look for any new actions in Vanta due in the upcoming months and create issues to ensure they're done on time. | Nathan Holliday | | Vanta check | Monthly | Look for any new actions in Vanta due in the upcoming months and create issues to ensure they're done on time. | Nathan Holliday |
| Investor reporting | Quarterly | Provide updated metrics for CRV in Chronograph. | Nathanael Holliday | | Investor reporting | Quarterly | Provide updated metrics for CRV in Chronograph. | Nathanael Holliday |
| Applicant forwarding | Daily | Whenever an application notification arrives in the BizOps slack channel, forward this notification to the hiring channel for that position. | Joanne Stableford | | Applicant forwarding | Daily | Whenever an application notification arrives in the BizOps slack channel, forward this notification to the hiring channel for that position. | Joanne Stableford |
| KPI roundup + weekly update | Weekly | Update KPI spreadsheet with BizOps KPI data by 5pm US central time every Friday. At 5pm check other department KPIs to make sure they have been updated, and if not, notify DRIs and the apprentice to the CEO which KPIs have not been updated. | Nathanael Holliday |
<!-- <!--

41
handbook/ceo.md
View File

@ -38,8 +38,9 @@ Internal meetings can sometimes be moved to make room. External meetings, blocke
- **Rescheduling:** All items on Mike's calendar are subject to change by the CEO to better serve the company. Send last-minute changes or cancellations to Mike [via direct message (DM)](#why-not-mention-the-ceo-in-slack-threads). - **Rescheduling:** All items on Mike's calendar are subject to change by the CEO to better serve the company. Send last-minute changes or cancellations to Mike [via direct message (DM)](#why-not-mention-the-ceo-in-slack-threads).
### Request equipment from Fleet IT ### Request equipment from Fleet IT
The Apprentice fulfills equipment requests once per week. Follow the process for [buying new equipment](https://fleetdm.com/handbook/company/communications#buying-other-new-equipment) and submit an [equipment request](https://github.com/fleetdm/confidential/issues/new?assignees=&labels=%23g-business-operations&projects=&template=equipment-request.md&title=%F0%9F%92%BB+Equipment+request+for+%7BGithub+%20username%7D). The Apprentice fulfills approved equipment requests once per week. Follow the process for [buying new equipment](https://fleetdm.com/handbook/company/communications#buying-other-new-equipment) and submit an [equipment request](https://github.com/fleetdm/confidential/issues/new?assignees=&labels=%23g-business-operations&projects=&template=equipment-request.md&title=%F0%9F%92%BB+Equipment+request+for+%7BGithub+%20username%7D).
The Apprentice will [ship the approved equipment](https://fleetdm.com/handbook/ceo#ship-approved-equipment) and at-mention the requestor with tracking information.
## Why not mention the CEO in Slack threads? ## Why not mention the CEO in Slack threads?
Everyone else who works at Fleet is expected to read (and reply or acknowledge with an emoji reaction) every time they're mentioned in Slack, even deep inside long threads. Everyone else who works at Fleet is expected to read (and reply or acknowledge with an emoji reaction) every time they're mentioned in Slack, even deep inside long threads.
@ -77,13 +78,8 @@ Thank you so much!" 🙇
- I can be inconsistent about how certain I sound about the same topics at different times. Even when I am probably still certain. That's because I try to question blind certainty, even my own. The problem is, I don't always remember why I first became certain about every topic. It is okay to stop and share what you observe: "You seem less sure about this. What's up?" If I am waffling, it can be helpful to say "Did we write down a decision on that? I'll make a GitHub issue." (Luke is good at this.) - I can be inconsistent about how certain I sound about the same topics at different times. Even when I am probably still certain. That's because I try to question blind certainty, even my own. The problem is, I don't always remember why I first became certain about every topic. It is okay to stop and share what you observe: "You seem less sure about this. What's up?" If I am waffling, it can be helpful to say "Did we write down a decision on that? I'll make a GitHub issue." (Luke is good at this.)
- I get grumpy when I am tired and I worry that I'll forget to follow up about things. You can say: "Would it help if I made a confidential issue about this for you and Sam to go over tonight?" - I get grumpy when I am tired and I worry that I'll forget to follow up about things. You can say: "Would it help if I made a confidential issue about this for you and Sam to go over tonight?"
- I sometimes will keep talking longer than I otherwise would (ESPECIALLY OVER ZOOM AND ESPECIALLY WHILE SCREENSHARING) when it is harder to see faces and pick up on subtle cues. This is exacerbated by me being afraid I’ll forget to come back to the topic, and feeling like I have to get to address it immediately or it will be lost. - I sometimes will keep talking longer than I otherwise would (ESPECIALLY OVER ZOOM AND ESPECIALLY WHILE SCREENSHARING) when it is harder to see faces and pick up on subtle cues. This is exacerbated by me being afraid I’ll forget to come back to the topic, and feeling like I have to get to address it immediately or it will be lost.
- When you think I am riffing 🎸 /monologuing 🗣️ on a tangential topic that isn’t in the agenda, its ok to interruptively share your screen and show me the sprawl visually in the notes you’ve been taking, select the text of the tangent, and say: “I’m taking notes, and I noticed that we’ve veered onto a tangent. Want me to tag you in a google doc comment on this you can follow up later? - When you think I am riffing 🎸 /monologuing 🗣️ on a tangential topic that isn’t in the agenda, its ok to interrupt by sharing your screen and show me the sprawl visually in the notes you’ve been taking, select the text of the tangent and say: “I’m taking notes, and I noticed that we’ve veered onto a tangent. Do you want me to tag you in a Google Doc comment to follow up later on this?
<!--
[![SC2021 - Keynote: The Voyage of Sails - Mike McNeil](https://img.youtube.com/vi/_T-UR9mU4-o/0.jpg)](https://www.youtube.com/watch?v=_T-UR9mU4-o)
"[Broken links and bugs](https://gist.github.com/mikermcneil/0ce44f6c4f803ff6b4f6), fleas, dance tights, [focus](https://kevin.burke.dev/kevin/dont-use-sails-or-waterline/), [running out of money](https://nathanleclaire.com/blog/2013/12/28/the-good-the-bad-and-the-ugly-of-sails-dot-js-realtime-javascript-mvc-framework/), etc."
-->
## Automated filing of signed documents ## Automated filing of signed documents
We use Zapier to automate how completed DocuSign envelopes are formatted and stored. This process ensures we store signed documents in the correct folder and that filenames are formatted consistently. We use Zapier to automate how completed DocuSign envelopes are formatted and stored. This process ensures we store signed documents in the correct folder and that filenames are formatted consistently.
@ -155,18 +151,20 @@ The Apprentice will reduce the scope of Mike's inbox to only include necessary a
- Escalate actionable sales communication and update Mike directly. - Escalate actionable sales communication and update Mike directly.
- Ensure all calendar invites have the necessary documents included. - Ensure all calendar invites have the necessary documents included.
### Document performance feedback
Every Friday at 5PM a [Business Operations team member](https://fleetdm.com/handbook/business-operations#team) will look for missing data in the [KPIs spreadsheet](https://docs.google.com/spreadsheets/d/1Hso0LxqwrRVINCyW_n436bNHmoqhoLhC8bcbvLPOs9A/edit#gid=0).
1. If KPIs are not reported on time, the BizOps Engineer will notify the Apprentice to the CEO and the DRI.
2. The Apprentice will update the "performance management" section of the appropriate individual's 1:1 doc so that the CEO can address during the next 1:1 meeting with the DRI.
### Send the weekly update ### Send the weekly update
We like to be open about milestones and announcements. We like to be open about milestones and announcements.
- Every Friday, e-group members [report their KPIs for the week](https://docs.google.com/spreadsheets/d/1Hso0LxqwrRVINCyW_n436bNHmoqhoLhC8bcbvLPOs9A/edit) by 5:00pm U.S. Central Time Zone. - Every Friday, e-group members [report their KPIs for the week](https://docs.google.com/spreadsheets/d/1Hso0LxqwrRVINCyW_n436bNHmoqhoLhC8bcbvLPOs9A/edit) by 5:00pm U.S. Central Time Zone.
- When KPIs are not reported on time, the BizOps Engineer will notify the Apprentice to the CEO and the DRI. - Every Friday at 6PM, the Apprentice will post a short update in [#general](https://fleetdm.slack.com/archives/C019FNQPA23) including:
- The Apprentice will update the "performance management" section of the appropriate individual's 1:1 doc so that the CEO can address during the next 1:1 meeting with the DRI.
- Friday nights, the Apprentice will post a short update in [#general](https://fleetdm.slack.com/archives/C019FNQPA23) including:
- A link to view KPIs - A link to view KPIs
- Who was on-call that week - Who was on-call that week
- Fleeties who are currently onboarding - Fleeties who are currently onboarding
- Planned hires who haven't started yet - Planned hires who haven't started yet
- Fleeties who had their lady day that week - Fleeties that departed that week
- Change the "⚡️" to "🔭" in the beginning of the formula - Change the "⚡️" to "🔭" in the beginning of the formula
@ -195,6 +193,27 @@ The Apprentice schedules all travel arrangements for the CEO including flights,
- Use the Brex card. - Use the Brex card.
- Frequent flyer details of all (previously flown) airlines are in 1Password as well as important travel documents. - Frequent flyer details of all (previously flown) airlines are in 1Password as well as important travel documents.
### Process incoming equipment
Upon receiving any device, the Apprentice will process the incoming equipment by:
1. Search for the SN of the physical device in the ["Company equipment" spreadsheet](https://docs.google.com/spreadsheets/d/1hFlymLlRWIaWeVh14IRz03yE-ytBLfUaqVz0VVmmoGI/edit#gid=0) to confirm the correct equipment was received.
- If the serial numbers do not match [create an issue](https://fleetdm.com/handbook/business-operations#contact-us) to get help from the Business Operations department.
3. Visibly inspect equipment and all related components (e.g. laptop charger) for damage.
4. Remove any stickers and clean devices and components.
5. Using the device's charger plug in the device.
6. Turn on the device and enter recovery mode using the [appropriate method](https://support.apple.com/en-us/HT204904).
7. Connect the device to WIFI.
8. Using the "Recovery assistant" tab (In the top left corner), select "Delete this Mac".
9. Follow the prompts to activate the device and reinstall the appropriate version of macOS.
### Ship approved equipment
Once the Business Operations department approves inventory to be shipped from Fleet IT, the Apprentice will ship the equipment by:
1. Compare the equipment request issue with the ["Company equipment" spreadsheet](https://docs.google.com/spreadsheets/d/1hFlymLlRWIaWeVh14IRz03yE-ytBLfUaqVz0VVmmoGI/edit#gid=0) and verify physical inventory.
2. Plug in the device and ensure inventory has been correctly processed and all components are present (e.g. charger cord, power converter).
3. package equipment for shipment and include Yubikeys (if requested).
4. Change the "Company equipment" spreadsheet to reflect the new user
5. Ship via FedEx to the address listed in the equipment request.
6. Add a comment to the equipment request issue, at-mentioning the requestor with the FedEx tracking info and close the issue.
### Prepare for the All hands ### Prepare for the All hands
- **Every month** the Apprentice will do the prep work for the monthly "✌️ All hands 🖐👋🤲👏🙌🤘" call. - **Every month** the Apprentice will do the prep work for the monthly "✌️ All hands 🖐👋🤲👏🙌🤘" call.

2
handbook/company/ceo.rituals.yml
View File

@ -19,7 +19,7 @@
moreInfoUrl: "https://fleetdm.com/handbook/company/ceo#process-the-ceos-email" moreInfoUrl: "https://fleetdm.com/handbook/company/ceo#process-the-ceos-email"
dri: "sampfluger88" dri: "sampfluger88"
- -
task: "Process all /"New requests/" on the #g-ceo kanban board" task: "Process all \"New requests\" on the #g-ceo kanban board"
startedOn: "2023-07-29" startedOn: "2023-07-29"
frequency: "Daily ⏰" frequency: "Daily ⏰"
description: "Process and prioritize all new issues and PRs" description: "Process and prioritize all new issues and PRs"

8
handbook/company/leadership.md
View File

@ -35,7 +35,7 @@ If you have any questions or feedback, please contact us: https://fleetdm.com/ha
- Outline the specific responsibilities of the department. - Outline the specific responsibilities of the department.
- `## Team` - `## Team`
- Table that displays each position and the team member(s) that fill that position, linking the Fleetie's LinkedIn to their name and GitHub to GiHub user name. See [handbook/ceo#team](https://fleetdm.com/handbook/ceo#team) for example. - Table that displays each position and the team member(s) that fill that position, linking the Fleetie's LinkedIn to their name and GitHub to GitHub user name. See [handbook/ceo#team](https://fleetdm.com/handbook/ceo#team) for example.
- `## Contact us` - `## Contact us`
@ -345,10 +345,8 @@ Once the new team member replies and accepts their offer in writing, 🔦 Head o
``` ```
2. **Ask hiring manager to send rejections:** Post to the `hiring-xxxxx-yyyy` Slack channel to let folks know the offer was accepted, and at-mention the _hiring manager_ to ask them to communicate with [all other interviewees](https://fleetdm.com/handbook/company#empathy) who are still in the running and [let them know that we chose a different person](https://fleetdm.com/handbook/business-operations#candidate-correspondence-email-templates). 2. **Ask hiring manager to send rejections:** Post to the `hiring-xxxxx-yyyy` Slack channel to let folks know the offer was accepted, and at-mention the _hiring manager_ to ask them to communicate with [all other interviewees](https://fleetdm.com/handbook/company#empathy) who are still in the running and [let them know that we chose a different person](https://fleetdm.com/handbook/business-operations#candidate-correspondence-email-templates).
>_**Note:** Send rejection emails quickly, within 1 business day. It only gets harder if you wait._ >_**Note:** Send rejection emails quickly, within 1 business day. It only gets harder if you wait._
3. **Remove open position:** Take down the newly-filled position from the fleetdm.com website by making the following two changes: (please only submit [one, single pull request that changes both of these files](https://www.loom.com/share/75da64632a93415cbe0e7752107c1af2): 3. **Remove open position:** The hiring manager removes the newly-filled position from the fleetdm.com website by [making a pull request](https://fleetdm.com/handbook/company/communications#making-a-pull-request) to delete it from the [open-positions.yml](https://github.com/fleetdm/fleet/blob/main/handbook/company/open-positions.yml) file.
- Edit the [list of open positions](https://fleetdm.com/handbook/company#open-positions) to remove the newly-filled position from the list. 4. **Close Slack channel:** Then archive and close the channel.
- Remove the [job description file](https://github.com/fleetdm/fleet/tree/main/handbook/company) that corresponds with the newly-filled position. (This is a Markdown file named after the role, with a filename ending in `.md`.)
5. **Close Slack channel:** Then archive and close the channel.
Now what happens? 🔦 Business Operations will then follow the steps in the "Hiring" issue, which includes reaching out to the new team member within 1 business day from a separate email thread to get additional information as needed, prepare their agreement, add them to the company's payroll system, and get their new laptop and hardware security keys ordered so that everything is ready for them to start on their first day. Now what happens? 🔦 Business Operations will then follow the steps in the "Hiring" issue, which includes reaching out to the new team member within 1 business day from a separate email thread to get additional information as needed, prepare their agreement, add them to the company's payroll system, and get their new laptop and hardware security keys ordered so that everything is ready for them to start on their first day.

31
handbook/company/open-positions.yml
View File

@ -113,37 +113,6 @@
- 🛠️ Technical: You understand the software development processes. You understand that software quality matters. - 🛠️ Technical: You understand the software development processes. You understand that software quality matters.
- 🟣 Openness: You are flexible and open to new ideas and ways of working. - 🟣 Openness: You are flexible and open to new ideas and ways of working.
- ➕ Bonus: Cybersecurity or IT background. - ➕ Bonus: Cybersecurity or IT background.
- jobTitle: 🐋 Account Executive
department: Customers
hiringManagerName: Alex Mitchell
hiringManagerLinkedInUrl: https://www.linkedin.com/in/alexandercmitchell/
hiringManagerGithubUsername: alexmitchelliii
responsibilities: |
- 🎯 Direct and participate in prospecting target companies, identifying key decision makers and influencers, leading when assigned/necessary/appropriate
- 📈 Use available data to identify opportunities and trends with individual prospects
- 📣 Actively promote FleetDM product and services on social media
- 🖥️ Actively present and demonstrate the value of FleetDM products and services and upgrades targeting customer expansion opportunities
- ❔ Appropriately use and follow MEDDPPICC process to qualify and progress opportunities to best help prospects solve problems
- 🤔 Anticipate market trends and identify new opportunities for growth
- 🕴️ Utilize systems and tools such as salesforce to analyze pipeline and opportunity data and keep all information up to date for leadership reporting
- 🚀 Work collaboratively with the product management, customer support, and engineering teams to facilitate feature development based on customer asks
- 🧑‍💻 Collaborate with the marketing team to plan, execute and track impactful marketing campaigns, in order to meet and/or exceed quarterly pipeline and revenue targets
- 🤝 Work with prospects to find win-win commercial agreements
experience: |
- 🦉 5+ years experience selling to enterprise customers
- 📣 Have excellent communication and interpersonal skills
- 🧑‍💻 Love technology and can explain how things work in detail
- 🧪 Extensive experience with Slack, Salesforce, Zendesk, Google Suite, and GitHub
- ⏩ Thrive in a complex, fast-paced, results driven environment with the ability to pivot to organizational changes easily
- 🤝 Decisive with the ability to shift gears between thinking and doing
- 📈 Ability to partner with various teams and stakeholders to drive sales
- 👀 Strong understanding of the enterprise procurement process
- ➕ Bonus: Direct experience with Fleet, MDM, osquery or SQL query writing, and working with SRE,CPE, or SecOps teams
- 💭 You know how to manage complex sales, difficult escalations, and challenging procurement processes with the utmost care and organization
- 💖 You know how to manage your time and priorities between leads, opportunities other day-to-day responsibilities
- ✍ You have the ability to effectively influence key stakeholders, from senior executives to day-to-day engineering contacts, and drive Fleet's value with them
- 🧬 You care about delivering an outstanding customer experience and advocating for the customer's needs within Fleet
- ➕ Bonus: You are comfortable with concepts like security, APIs, and DevOps
- jobTitle: 🐋 Sales Development Representative (SDR) - jobTitle: 🐋 Sales Development Representative (SDR)
department: Customers department: Customers
hiringManagerName: Alex Mitchell hiringManagerName: Alex Mitchell

2
handbook/company/pricing-features-table.yml
View File

@ -15,7 +15,7 @@
- name: Zero-touch setup for macOS computers - name: Zero-touch setup for macOS computers
tier: Premium tier: Premium
comingSoon: false comingSoon: false
- name: Safely execute custom scripts - name: Safely execute custom scripts (macOS, Windows, and Linux)
tier: Premium tier: Premium
comingSoon: false comingSoon: false
- name: End-user macOS update reminders (via Nudge) - name: End-user macOS update reminders (via Nudge)

26
handbook/customers/README.md
View File

@ -32,28 +32,6 @@ The Fleet Customer team embodies [our values](https://fleetdm.com/handbook/compa
Fleet's main source for prospects to learn about the company and its offerings is our website, fleetdm.com. There are many places across the website for prospects to ask for more information, request merchandise, try the product and even purchase licenses directly. If the user experience in any of these locations asks for an email address or other contact information, Fleet may use that contact information for follow-up, including sales and marketing purposes. That contact information is for Fleet's sole use, and we do not give or sell that information to any third parties. Fleet's main source for prospects to learn about the company and its offerings is our website, fleetdm.com. There are many places across the website for prospects to ask for more information, request merchandise, try the product and even purchase licenses directly. If the user experience in any of these locations asks for an email address or other contact information, Fleet may use that contact information for follow-up, including sales and marketing purposes. That contact information is for Fleet's sole use, and we do not give or sell that information to any third parties.
## Contacting Fleet
In the case of a prospect or customer request, we strive to adhere to the following response times:
- Web chat: 1 hour response during working hours, 8 hours otherwise
- Talk to an expert: prospects can schedule chats via our calendar tool
- All other enquiries: 1-2 days
If you're using a free version of Fleet, you can access free community support by opening an issue in the [Fleet GitHub repository](https://github.com/fleetdm/fleet/).
Customers on a paid tier of Fleet can get in touch directly for commercial support:
| Level of impact | Response time - premium tier | Response time - ultimate tier |
| :--- | :--- | :--- |
| Low to medium impact </br> Email/chat support during business hours </br> Email: Support email address </br> Chat: Dedicated Slack channel (confidential) </br>| **1 business day** | **1 business day** |
| High to emergency impact </br> Expedited phone/chat/email support </br> Call or text: Fleet support phone number </br> Email: Emergency support email address </br> | **4 business hours** | **≤1 hour during business hours** </br> **≤2 hours outside business hours**
| Level of impact | Type of support |
| :--- | :--- |
| Low to medium impact | Chat support during business hours Chat: Dedicated Slack channel (confidential) </br> Response time: **≤1 business day** |
| High to emergency impact | Expedited phone/chat support during business hours </br> Call or text [the Fleet phone number](https://docs.google.com/document/d/1tE-NpNfw1icmU2MjYuBRib0VWBPVAdmq4NiCrpuI0F0/edit) that was provided in the invoice. </br> Response time: **≤4 hours** |
## Customer codenames ## Customer codenames
Occasionally, we will need to track public issues for customers that wish to remain anonymous on our public issue tracker. To do this, we choose an appropriate minor planet name from this [Wikipedia page](https://en.wikipedia.org/wiki/List_of_named_minor_planets_(alphabetical)) and create a label which we attach to the issue and any future issues for this customer. Occasionally, we will need to track public issues for customers that wish to remain anonymous on our public issue tracker. To do this, we choose an appropriate minor planet name from this [Wikipedia page](https://en.wikipedia.org/wiki/List_of_named_minor_planets_(alphabetical)) and create a label which we attach to the issue and any future issues for this customer.
@ -71,7 +49,7 @@ Fleet's intro deck adds additional detail to our pitch. Find it in [pdf](https:/
Fleet's intro video shows how to get started with Fleet as an admin. Find it on [YouTube](https://www.youtube.com/watch?v=rVxSgvKjrWo). Fleet's intro video shows how to get started with Fleet as an admin. Find it on [YouTube](https://www.youtube.com/watch?v=rVxSgvKjrWo).
## Customer support service level agreements (SLA's) ## Contacting Fleet: customer support service level agreements (SLA's)
### Fleet Free ### Fleet Free
| Impact Level | Definition | Preferred Contact | Response Time | | Impact Level | Definition | Preferred Contact | Response Time |
@ -88,7 +66,7 @@ Note: If you're using Fleet Free, you can also access community support by openi
| Medium (P2) | Something is preventing normal Fleet operation, and there may or may not be minor business impact. | Standard email/chat support | ≤1 business day | | Medium (P2) | Something is preventing normal Fleet operation, and there may or may not be minor business impact. | Standard email/chat support | ≤1 business day |
| Low (P3) | Questions or clarifications around features, documentation, deployments, or 'how to's'. | Standard email/chat support | 1-2 business days | | Low (P3) | Questions or clarifications around features, documentation, deployments, or 'how to's'. | Standard email/chat support | 1-2 business days |
Note: Fleet business hours for support are Monday-Friday, 7AM-4PM Pacific Time, excluding current U.S. federal holidays during which responses may be delayed for Medium and Low impact issues. Note: Fleet business hours for support are Monday-Friday, 7AM-4PM Pacific Time, excluding current U.S. federal holidays during which responses may be delayed for Medium and Low impact issues. Fleeties can find Fleet general contact information [here](https://docs.google.com/document/d/1tE-NpNfw1icmU2MjYuBRib0VWBPVAdmq4NiCrpuI0F0/edit).
### Fleet Ultimate ### Fleet Ultimate

2
handbook/engineering/scaling-fleet.md
View File

@ -69,7 +69,7 @@ However, this database feature doesn’t come without a cost. The one to focus o
The TLDR is: understand very well how a table will be used. If we do bulk inserts/updates, InnoDB might lock more than you anticipate and cause issues. This is not an argument to not do bulk inserts/updates, but to be very careful when you add a foreign key. The TLDR is: understand very well how a table will be used. If we do bulk inserts/updates, InnoDB might lock more than you anticipate and cause issues. This is not an argument to not do bulk inserts/updates, but to be very careful when you add a foreign key.
In particular, host_id is a foreign key we’ve been skipping in all the new additional host data tables, which is not something that comes for free, as with that, [we have to keep the data consistent by hand with cleanups](https://github.com/fleetdm/fleet/blob/main/server/datastore/mysql/hosts.go#L309-L309). In particular, host_id is a foreign key we’ve been skipping in all the new additional host data tables, which is not something that comes for free, as with that, [we have to keep the data consistent by hand with cleanups](https://github.com/fleetdm/fleet/blob/71a237042a9c39a45bc8f9c76465e5ff6039eba9/server/datastore/mysql/hosts.go#L444).
### In this section ### In this section

13
handbook/marketing/README.md
View File

@ -51,6 +51,8 @@ Here are some topics for social media posts:
### Ads ### Ads
Fleet uses advertising to spread awareness through a broader audience and foster greater engagement within user communities. The more people actively using Fleet, or contributing, the better Fleet will be. Fleet uses advertising to spread awareness through a broader audience and foster greater engagement within user communities. The more people actively using Fleet, or contributing, the better Fleet will be.
### Events
It's important for Fleet to engage at events. This provides an opportunity to directly engage with potential users and contributors, build relationships, gather feedback, and create a stronger sense of community and trust.
## Responsibilities ## Responsibilities
@ -116,6 +118,17 @@ Any changes to the current running ads visible to a user, including designs, key
2. Compare existing ads against the newly proposed ad within the corresponding ad platform. ([Google Ads](https://ads.google.com/home/), [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/), etc.) 2. Compare existing ads against the newly proposed ad within the corresponding ad platform. ([Google Ads](https://ads.google.com/home/), [LinkedIn Campaign Manager](https://www.linkedin.com/campaignmanager/), etc.)
3. If your change is approved, Field Marketer makes changes and creates a calendar reminder to check performance two weeks from the date changes were made. 3. If your change is approved, Field Marketer makes changes and creates a calendar reminder to check performance two weeks from the date changes were made.
### Book an event
For an event to be considered, booked, and scheduled, we follow the event issue template.
1. Create a [new GitHub issue for the #g-marketing board](https://fleetdm.com/handbook/marketing#contact-us) and select the "Event-preparation" template..
2. Drag the issue into the "🗓 Ideas for future events" column.
Once approval has been received, move the event into the "🗓 Planned events" column.
### Review ongoing events
Check the "🗓 Planned events" column in [#g-marketing board](https://app.zenhub.com/workspaces/g-marketing-64e6c8e2d35c7f001a457b7f/board) and continue to work through steps in each event's issue.
## Rituals ## Rituals
<rituals :rituals="rituals['handbook/marketing/marketing.rituals.yml']"></rituals> <rituals :rituals="rituals['handbook/marketing/marketing.rituals.yml']"></rituals>

14
handbook/marketing/marketing.rituals.yml
View File

@ -21,3 +21,17 @@
description: "Complete draft orders." # example of a longer thing: description: "[Prioritizing next sprint](https://fleetdm.com/handbook/company/communication)" description: "Complete draft orders." # example of a longer thing: description: "[Prioritizing next sprint](https://fleetdm.com/handbook/company/communication)"
moreInfoUrl: "https://fleetdm.com/handbook/marketing#process-pending-swag-requests-from-the-website" #URL used to highlight "description:" test in table moreInfoUrl: "https://fleetdm.com/handbook/marketing#process-pending-swag-requests-from-the-website" #URL used to highlight "description:" test in table
dri: "drewbakerfdm" # DRI for ritual (assignee if autoIssue) (TODO display GitHub proflie pic instead of name or title) dri: "drewbakerfdm" # DRI for ritual (assignee if autoIssue) (TODO display GitHub proflie pic instead of name or title)
-
task: "Review ongoing events"
startedOn: "2023-10-02"
frequency: "Daily"
description: "Check 🗓️ Planned events and complete steps in each issue"
moreInfoUrl: "https://fleetdm.com/handbook/marketing#review-ongoing-events"
dri: "drewbakerfdm"
-
task: "Book an event"
startedOn: "2023-10-02"
frequency: "Weekly"
description: "Populate 🗓️ Ideas for future events"
moreInfoUrl: "https://fleetdm.com/handbook/marketing#book-an-event"
dri: "drewbakerfdm"

27
handbook/product/README.md
View File

@ -308,7 +308,7 @@ We track competitors' capabilities and adjacent (or commonly integrated) product
## Intake ## Intake
- [Making a request](#making-a-request) - [Making a request](#making-a-request)
- [How features are evaluated](#how-features-are-evaluated) - [How feature requests are evaluated](#how-feature-requests-are-evaluated)
- [After the feature is accepted](#after-the-feature-is-accepted) - [After the feature is accepted](#after-the-feature-is-accepted)
- [Why this way?](#why-this-way) - [Why this way?](#why-this-way)
@ -316,7 +316,7 @@ To stay in-sync with our customers' needs, Fleet accepts feature requests from c
### Making a request ### Making a request
To make a feature request or advocate for a feature request from a customer or community member, add your request to the list in the [🎁🗣 Feature Fest agenda](https://docs.google.com/document/d/1mwu5WfdWBWwJ2C3zFDOMSUC9QCyYuKP4LssO_sIHDd0/edit#heading=h.zahrflvvks7q) and attend the next scheduled 🎁🗣 Feature Fest meeting. To make a feature request or advocate for a feature request from a customer or community member, [create an issue](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=~customer+request&projects=&template=feature-request.md&title=) and attend the next scheduled 🎁🗣 Feature Fest meeting.
Requests are weighed from top to bottom while prioritizing attendee requests. This means that if the individual that added a feature request is not in attendance, the feature request will be discussed towards the end of the call if there's time. Requests are weighed from top to bottom while prioritizing attendee requests. This means that if the individual that added a feature request is not in attendance, the feature request will be discussed towards the end of the call if there's time.
@ -330,16 +330,20 @@ To help the product team, other pieces of information can be optionally included
- How does this change fit into the requester's overall usage of Fleet? - How does this change fit into the requester's overall usage of Fleet?
- What other potential changes to the product have you considered? - What other potential changes to the product have you considered?
To ensure your request appears on the ["Feature Fest" board](https://app.zenhub.com/workspaces/-feature-fest-651b2962605ba29209324c57/board):
- Add the `~feature fest` label to your issue
- Add the relevant customer label (if applicable)
To maximize your chances of having a feature accepted, requesters can visit the [🗣 Product office hours](#rituals) meeting to get feedback on requests prior to being accepted. To maximize your chances of having a feature accepted, requesters can visit the [🗣 Product office hours](#rituals) meeting to get feedback on requests prior to being accepted.
### How feature requests are evaluated ### How feature requests are evaluated
Digestion of these new product ideas (requests) happens at the **🎁🗣 Feature Fest** meeting. Digestion of these new product ideas (requests) happens at the **🎁🗣 Feature Fest** meeting.
At the **🎁🗣 Feature Fest** meeting, the DRI (Head of Product) weighs all requests in the agenda. When the team weighs a request, it is immediately prioritized or put to the side. At the **🎁🗣 Feature Fest** meeting, the DRI (Head of Product) weighs all requests on the board. When the team weighs a request, it is immediately prioritized or put to the side.
- A _request is prioritized_ when the DRI decides it is a priority. When this happens, the team sets the request to be estimated within five business days. - A _request is prioritized_ when the DRI decides it is a priority. When this happens, the team sets the request to be estimated within five business days.
- A _request is put to the side_ when the business perceives competing priorities as more pressing in the immediate moment. - A _request is put to the side_ when the business perceives competing priorities as more pressing in the immediate moment.
If a feature is not prioritized, it only means that the feature has been rejected _at that time_. It is up to the requestor to bring the request back again at another 🎁🗣 Feature Fest meeting. If a feature is not prioritized during a 🎁🗣 Feature Fest meeting, it only means the feature has been rejected _at that time_. Requestors will be notified by the Head of Product, and they can resubmit their request at a future meeting.
Requests are weighed by: Requests are weighed by:
- The completeness of the request (see [making a request](#making-a-request)) - The completeness of the request (see [making a request](#making-a-request))
@ -348,11 +352,16 @@ Requests are weighed by:
- How well the request fits within Fleet's product vision and roadmap - How well the request fits within Fleet's product vision and roadmap
- Whether the feature seems like it can be designed, estimated, and developed in 6 weeks, given its individual complexity and when combined with other work already accepted - Whether the feature seems like it can be designed, estimated, and developed in 6 weeks, given its individual complexity and when combined with other work already accepted
### Customer feature requests
The product team's goal is to prioritize 16 customer feature requests at Feature Fest, then take them from settled to shipped. The customer success team is responsible for providing the Head of Product a live count during the Feature Fest meeting. Product Operations is responsible for monitoring this KPI and raising alarms throughout the design and engineering sprints.
> Customer stories should be estimated at 1-3 points each to count as 1 request. If a feature request spans across multiple customers, it will be counted as the number of customers involved.
### After the feature is accepted ### After the feature is accepted
- After the 🎁🗣 Feature Fest meeting, the Head of Product resets the agenda to blank by doing the following: After the 🎁🗣 Feature Fest meeting, Product Operations will clear the Feature Fest board as follows:
- Create issues for accepted items **Prioritized features:** Remove `feature fest` label, add `:product` label, and assign the group Product Manager.
- Notify absent requesters of decisions **Put to the side features:** Remove `feature fest` label and close the issue.
- Move that week's feature requests to the backup journal document
Group Product Managers will then develop user stories for the prioritized features.
> The product team's commitment to the requester is that a prioritized feature will be delivered within 6 weeks or the requester will be notified within 1 business day of the decision to de-prioritize the feature. > The product team's commitment to the requester is that a prioritized feature will be delivered within 6 weeks or the requester will be notified within 1 business day of the decision to de-prioritize the feature.
@ -423,7 +432,7 @@ Directly Responsible Individuals (DRI) engage in the ritual(s) below at the freq
| Quality check | Daily | Every day, Product Operations will review the "Settled" column on the drafting board to ensure all product action items are complete. | Isabell Reedy | | Quality check | Daily | Every day, Product Operations will review the "Settled" column on the drafting board to ensure all product action items are complete. | Isabell Reedy |
| Bug de-prioritization | Mid-sprint | CEO, Head of Product, and Director of Product Development review the bugs which did not meet the 6-week delivery timeline. Align on next steps for which bugs to schedule into the next sprint and which can be de-prioritized. | Mo Zhu | | Bug de-prioritization | Mid-sprint | CEO, Head of Product, and Director of Product Development review the bugs which did not meet the 6-week delivery timeline. Align on next steps for which bugs to schedule into the next sprint and which can be de-prioritized. | Mo Zhu |
| Product confirm and celebrate | Weekly (Wednesday) | The Head of Product meets with the designers and product managers to discuss completed user stories. They also verify all updates to documentation, communications, guides, and the pricing and transparency pages, ensuring everything is set for the next steps. | Mo Zhu | | Product confirm and celebrate | Weekly (Wednesday) | The Head of Product meets with the designers and product managers to discuss completed user stories. They also verify all updates to documentation, communications, guides, and the pricing and transparency pages, ensuring everything is set for the next steps. | Mo Zhu |
| Pre-sprint prioritization call (CX) | Sprintly (Monday) | The product manager and engineering manager meet to confirm alignment on prioritization for the upcoming sprint. | Mo Zhu | | Pre-sprint prioritization call (CX) | Sprintly (Monday) | The product manager, engineering manager, and product operations meet before each sprint to align on priorities and note what wasn't completed in the previous sprint. Product operations then informs the customer success team about related customer requests. | Mo Zhu |
| Bug review (CX) | Weekly (Tuesday) | The product manager meets with the engineering manager and a product quality engineer to ensure synchronization on bug prioritization and actions preceding CX estimation sessions. | Mo Zhu | | Bug review (CX) | Weekly (Tuesday) | The product manager meets with the engineering manager and a product quality engineer to ensure synchronization on bug prioritization and actions preceding CX estimation sessions. | Mo Zhu |
| Bug round-up | Mid-sprint | Product Operations will compile a list of churned bugs, including issue numbers, specifics, and age. They will also notify the Customer Success team of any churned bugs that have customer tags | Isabell Reedy | | Bug round-up | Mid-sprint | Product Operations will compile a list of churned bugs, including issue numbers, specifics, and age. They will also notify the Customer Success team of any churned bugs that have customer tags | Isabell Reedy |
| Churned bug review | Mid-sprint | The Head of Product meets with the group product managers to examine churned bugs and categorize them as either schedule, needs prioritization, or de-prioritize. | Mo Zhu | | Churned bug review | Mid-sprint | The Head of Product meets with the group product managers to examine churned bugs and categorize them as either schedule, needs prioritization, or de-prioritize. | Mo Zhu |

2
infrastructure/dogfood/terraform/aws/variables.tf
View File

@ -56,7 +56,7 @@ variable "database_name" {
variable "fleet_image" { variable "fleet_image" {
description = "the name of the container image to run" description = "the name of the container image to run"
default = "fleetdm/fleet:v4.38.0" default = "fleetdm/fleet:v4.38.1"
} }
variable "software_inventory" { variable "software_inventory" {

2
infrastructure/dogfood/terraform/gcp/variables.tf
View File

@ -68,5 +68,5 @@ variable "redis_mem" {
} }
variable "image" { variable "image" {
default = "fleet:v4.38.0" default = "fleet:v4.38.1"
} }

2
infrastructure/sandbox/JITProvisioner/jitprovisioner.tf
View File

@ -206,7 +206,7 @@ resource "random_uuid" "jitprovisioner" {
# Use the local to make the trigger work. # Use the local to make the trigger work.
locals { locals {
fleet_tag = "v4.38.0" fleet_tag = "v4.38.1"
} }
resource "null_resource" "standard-query-library" { resource "null_resource" "standard-query-library" {

2
infrastructure/sandbox/PreProvisioner/lambda/deploy_terraform/main.tf
View File

@ -165,7 +165,7 @@ resource "helm_release" "main" {
set { set {
name = "imageTag" name = "imageTag"
value = "v4.38.0" value = "v4.38.1"
} }
set { set {

8
orbit/CHANGELOG.md
View File

@ -1,3 +1,11 @@
## Orbit 1.17.0 (Sep 28, 2023)
* Updated the image and the overall layout of the migration dialog
* Added a mechanism to retry a Fleet Desktop token when the Fleet server response indicates it has expired or is invalid.
* Upgraded Go version to 1.21.1
## Orbit 1.16.0 (Sep 6, 2023) ## Orbit 1.16.0 (Sep 6, 2023)
* Updated the default TUF update roots with the newest metadata in the server. (#13381) * Updated the default TUF update roots with the newest metadata in the server. (#13381)

1
orbit/changes/13715-bump-go-version
View File

@ -1 +0,0 @@
* Upgrade Go version to 1.21.1

1
orbit/changes/13858-migration-tweaks
View File

@ -1 +0,0 @@
* Updated the image and the overall layout of the migration dialog

1
orbit/changes/issue-13635-retry-invalid-token
View File

@ -1 +0,0 @@
* Added a mechanism to retry a Fleet Desktop token when the Fleet server response indicates it has expired or is invalid.

5
orbit/cmd/desktop/desktop.go
View File

@ -158,12 +158,13 @@ func main() {
log.Fatal().Err(err).Msg("unable to initialize request client") log.Fatal().Err(err).Msg("unable to initialize request client")
} }
client.WithInvalidTokenRetry(func() string { client.WithInvalidTokenRetry(func() string {
log.Debug().Msg("refetching token from disk for API retry")
newToken, err := tokenReader.Read() newToken, err := tokenReader.Read()
if err != nil { if err != nil {
log.Error().Err(err).Msg("refetch token") log.Error().Err(err).Msg("refetch token from disk for API retry")
return "" return ""
} }
log.Debug().Msg("successfully refetched the token from disk") log.Debug().Msg("successfully refetched the token from disk for API retry")
return newToken return newToken
}) })

1
orbit/cmd/orbit/orbit.go
View File

@ -786,6 +786,7 @@ func main() {
// check again when the token will expire, which will happen // check again when the token will expire, which will happen
// before the next rotation check // before the next rotation check
rotationTicker.Reset(remain) rotationTicker.Reset(remain)
log.Debug().Msgf("token will expire soon, checking again in: %s", remain)
} }
case <-remoteCheckTicker.C: case <-remoteCheckTicker.C:

2
server/fleet/users.go
View File

@ -353,7 +353,7 @@ func ValidatePasswordRequirements(password string) error {
return nil return nil
} }
return errors.New("Password does not meet required criteria") return errors.New("Password does not meet required criteria: Must include 12 characters, at least 1 number (e.g. 0 - 9), and at least 1 symbol (e.g. &*#).")
} }
// ValidateEmail checks that the provided email address is valid, this function // ValidateEmail checks that the provided email address is valid, this function

2
server/service/client_mdm.go
View File

@ -222,7 +222,7 @@ func downloadRemoteMacosBootstrapPackage(pkgURL string) (*fleet.MDMAppleBootstra
case errors.Is(err, file.ErrInvalidType): case errors.Is(err, file.ErrInvalidType):
return nil, errors.New("Couldn’t edit bootstrap_package. The file must be a package (.pkg).") return nil, errors.New("Couldn’t edit bootstrap_package. The file must be a package (.pkg).")
case errors.Is(err, file.ErrNotSigned): case errors.Is(err, file.ErrNotSigned):
return nil, errors.New("Couldn’t edit bootstrap_package. The bootstrap_package must be signed. Learn how to sign the package in the Fleet documentation: https://fleetdm.com/docs/using-fleet/mdm-macos-setup#step-2-sign-the-package") return nil, errors.New("Couldn’t edit bootstrap_package. The bootstrap_package must be signed. Learn how to sign the package in the Fleet documentation: https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#step-2-sign-the-package")
default: default:
return nil, fmt.Errorf("checking package signature: %w", err) return nil, fmt.Errorf("checking package signature: %w", err)
} }

13
server/service/device_client.go
View File

@ -12,6 +12,7 @@ import (
"github.com/fleetdm/fleet/v4/pkg/retry" "github.com/fleetdm/fleet/v4/pkg/retry"
"github.com/fleetdm/fleet/v4/server/fleet" "github.com/fleetdm/fleet/v4/server/fleet"
"github.com/fleetdm/fleet/v4/server/ptr" "github.com/fleetdm/fleet/v4/server/ptr"
"github.com/rs/zerolog/log"
) )
// Device client is used consume the `device/...` endpoints and meant to be used by Fleet Desktop // Device client is used consume the `device/...` endpoints and meant to be used by Fleet Desktop
@ -47,6 +48,7 @@ func NewDeviceClient(addr string, insecureSkipVerify bool, rootCA string, fleetC
// ErrUnauthenticated. The client will call this function to get a fresh token // ErrUnauthenticated. The client will call this function to get a fresh token
// and retry if it returns a different, non-empty token. // and retry if it returns a different, non-empty token.
func (dc *DeviceClient) WithInvalidTokenRetry(fn func() string) { func (dc *DeviceClient) WithInvalidTokenRetry(fn func() string) {
log.Debug().Msg("setting invalid token retry hook")
dc.invalidTokenRetryFunc = fn dc.invalidTokenRetryFunc = fn
} }
@ -55,7 +57,7 @@ func (dc *DeviceClient) WithInvalidTokenRetry(fn func() string) {
// (the pathFmt is used as-is as path). It will retry if the request fails due // (the pathFmt is used as-is as path). It will retry if the request fails due
// to an invalid token and the invalidTokenRetryFunc field is set. // to an invalid token and the invalidTokenRetryFunc field is set.
func (dc *DeviceClient) request(verb, pathFmt, token, query string, params interface{}, responseDest interface{}) error { func (dc *DeviceClient) request(verb, pathFmt, token, query string, params interface{}, responseDest interface{}) error {
const maxAttempts = 3 const maxAttempts = 4
var attempt int var attempt int
for { for {
attempt++ attempt++
@ -67,11 +69,18 @@ func (dc *DeviceClient) request(verb, pathFmt, token, query string, params inter
reqErr := dc.requestAttempt(verb, path, query, params, responseDest) reqErr := dc.requestAttempt(verb, path, query, params, responseDest)
if attempt >= maxAttempts || dc.invalidTokenRetryFunc == nil || token == "-" || !errors.Is(reqErr, ErrUnauthenticated) { if attempt >= maxAttempts || dc.invalidTokenRetryFunc == nil || token == "-" || !errors.Is(reqErr, ErrUnauthenticated) {
// no retry possible, return the result // no retry possible, return the result
if reqErr != nil {
log.Debug().Msgf("not retrying API error; attempt=%d, hook set=%t, token unset=%t, error is auth=%t",
attempt, dc.invalidTokenRetryFunc != nil, token == "-", errors.Is(reqErr, ErrUnauthenticated))
}
return reqErr return reqErr
} }
time.Sleep(time.Duration(attempt) * time.Second) delay := time.Duration(attempt) * time.Second
log.Debug().Msgf("retrying API error in %s", delay)
time.Sleep(delay)
newToken := dc.invalidTokenRetryFunc() newToken := dc.invalidTokenRetryFunc()
log.Debug().Msgf("retrying API error; token is different=%t", newToken != "" && newToken != token)
if newToken != "" { if newToken != "" {
token = newToken token = newToken
} }

2
server/service/device_client_test.go
View File

@ -162,6 +162,6 @@ func TestDeviceClientRetryInvalidToken(t *testing.T) {
_, err = client.DesktopSummary("bad") _, err = client.DesktopSummary("bad")
require.Error(t, err) require.Error(t, err)
require.ErrorIs(t, err, ErrUnauthenticated) require.ErrorIs(t, err, ErrUnauthenticated)
require.Equal(t, int64(3), callCounts.Load()) require.Equal(t, int64(4), callCounts.Load())
}) })
} }

1
server/service/integration_core_test.go
View File

@ -79,6 +79,7 @@ func (s *integrationTestSuite) TestSlowOsqueryHost() {
SkipCreateTestUsers: true, SkipCreateTestUsers: true,
//nolint:gosec // G112: server is just run for testing this explicit config. //nolint:gosec // G112: server is just run for testing this explicit config.
HTTPServerConfig: &http.Server{ReadTimeout: 2 * time.Second}, HTTPServerConfig: &http.Server{ReadTimeout: 2 * time.Second},
EnableCachedDS: true,
}, },
) )
defer func() { defer func() {

96
server/service/integration_enterprise_test.go
View File

@ -54,9 +54,10 @@ func (s *integrationEnterpriseTestSuite) SetupSuite() {
License: &fleet.LicenseInfo{ License: &fleet.LicenseInfo{
Tier: fleet.TierPremium, Tier: fleet.TierPremium,
}, },
Pool: s.redisPool, Pool: s.redisPool,
Lq: s.lq, Lq: s.lq,
Logger: log.NewLogfmtLogger(os.Stdout), Logger: log.NewLogfmtLogger(os.Stdout),
EnableCachedDS: true,
} }
users, server := RunServerForTestsWithDS(s.T(), s.ds, &config) users, server := RunServerForTestsWithDS(s.T(), s.ds, &config)
s.server = server s.server = server
@ -4106,3 +4107,92 @@ func (s *integrationEnterpriseTestSuite) TestOrbitConfigExtensions() {
} }
}`), http.StatusBadRequest) }`), http.StatusBadRequest)
} }
func (s *integrationEnterpriseTestSuite) TestTeamConfigDetailQueriesOverrides() {
ctx := context.Background()
t := s.T()
teamName := t.Name() + "team1"
team := &fleet.Team{
Name: teamName,
Description: "desc team1",
}
s.Do("POST", "/api/latest/fleet/teams", team, http.StatusOK)
spec := []byte(fmt.Sprintf(`
name: %s
features:
additional_queries:
time: SELECT * FROM time
enable_host_users: true
detail_query_overrides:
users: null
software_linux: "select * from blah;"
disk_encryption_linux: null
`, teamName))
s.applyTeamSpec(spec)
team, err := s.ds.TeamByName(ctx, teamName)
require.NoError(t, err)
require.NotNil(t, team.Config.Features.DetailQueryOverrides)
require.Nil(t, team.Config.Features.DetailQueryOverrides["users"])
require.Nil(t, team.Config.Features.DetailQueryOverrides["disk_encryption_linux"])
require.NotNil(t, team.Config.Features.DetailQueryOverrides["software_linux"])
require.Equal(t, "select * from blah;", *team.Config.Features.DetailQueryOverrides["software_linux"])
// create a linux host
linuxHost, err := s.ds.NewHost(context.Background(), &fleet.Host{
DetailUpdatedAt: time.Now().Add(-10 * time.Hour),
LabelUpdatedAt: time.Now().Add(-10 * time.Hour),
PolicyUpdatedAt: time.Now().Add(-10 * time.Hour),
SeenTime: time.Now().Add(-1 * time.Minute),
OsqueryHostID: ptr.String(t.Name()),
NodeKey: ptr.String(t.Name()),
UUID: uuid.New().String(),
Hostname: fmt.Sprintf("%sfoo.local", t.Name()),
Platform: "linux",
})
require.NoError(t, err)
// add the host to team1
err = s.ds.AddHostsToTeam(context.Background(), &team.ID, []uint{linuxHost.ID})
require.NoError(t, err)
// get distributed queries for the host
s.lq.On("QueriesForHost", linuxHost.ID).Return(map[string]string{fmt.Sprintf("%d", linuxHost.ID): "select 1 from osquery;"}, nil)
req := getDistributedQueriesRequest{NodeKey: *linuxHost.NodeKey}
var dqResp getDistributedQueriesResponse
s.DoJSON("POST", "/api/osquery/distributed/read", req, http.StatusOK, &dqResp)
require.NotContains(t, dqResp.Queries, "fleet_detail_query_users")
require.NotContains(t, dqResp.Queries, "fleet_detail_query_disk_encryption_linux")
require.Contains(t, dqResp.Queries, "fleet_detail_query_software_linux")
require.Contains(t, dqResp.Queries, "fleet_distributed_query_17")
spec = []byte(fmt.Sprintf(`
name: %s
features:
additional_queries:
time: SELECT * FROM time
enable_host_users: true
detail_query_overrides:
software_linux: "select * from blah;"
`, teamName))
s.applyTeamSpec(spec)
team, err = s.ds.TeamByName(ctx, teamName)
require.NoError(t, err)
require.NotNil(t, team.Config.Features.DetailQueryOverrides)
require.Nil(t, team.Config.Features.DetailQueryOverrides["users"])
require.Nil(t, team.Config.Features.DetailQueryOverrides["disk_encryption_linux"])
require.NotNil(t, team.Config.Features.DetailQueryOverrides["software_linux"])
require.Equal(t, "select * from blah;", *team.Config.Features.DetailQueryOverrides["software_linux"])
// get distributed queries for the host
req = getDistributedQueriesRequest{NodeKey: *linuxHost.NodeKey}
dqResp = getDistributedQueriesResponse{}
s.DoJSON("POST", "/api/osquery/distributed/read", req, http.StatusOK, &dqResp)
require.Contains(t, dqResp.Queries, "fleet_detail_query_users")
require.Contains(t, dqResp.Queries, "fleet_detail_query_disk_encryption_linux")
require.Contains(t, dqResp.Queries, "fleet_detail_query_software_linux")
require.Contains(t, dqResp.Queries, "fleet_distributed_query_17")
}

2
server/service/osquery_utils/queries.go
View File

@ -1617,7 +1617,7 @@ func GetDetailQueries(
unknownQueries = append(unknownQueries, name) unknownQueries = append(unknownQueries, name)
continue continue
} }
if override == nil { if override == nil || *override == "" {
delete(generatedMap, name) delete(generatedMap, name)
} else { } else {
query.Query = *override query.Query = *override

12
server/service/osquery_utils/queries_test.go
View File

@ -873,6 +873,18 @@ func TestAppConfigReplaceQuery(t *testing.T) {
queries = GetDetailQueries(context.Background(), config.FleetConfig{}, nil, &fleet.Features{EnableHostUsers: true, DetailQueryOverrides: replacementMap}) queries = GetDetailQueries(context.Background(), config.FleetConfig{}, nil, &fleet.Features{EnableHostUsers: true, DetailQueryOverrides: replacementMap})
_, exists := queries["users"] _, exists := queries["users"]
assert.False(t, exists) assert.False(t, exists)
// put the query back again
replacementMap["users"] = ptr.String("select 1 from blah")
queries = GetDetailQueries(context.Background(), config.FleetConfig{}, nil, &fleet.Features{EnableHostUsers: true, DetailQueryOverrides: replacementMap})
assert.NotEqual(t, originalQuery, queries["users"].Query)
assert.Equal(t, "select 1 from blah", queries["users"].Query)
// empty strings are also ignored
replacementMap["users"] = ptr.String("")
queries = GetDetailQueries(context.Background(), config.FleetConfig{}, nil, &fleet.Features{EnableHostUsers: true, DetailQueryOverrides: replacementMap})
_, exists = queries["users"]
assert.False(t, exists)
} }
func TestDirectIngestSoftware(t *testing.T) { func TestDirectIngestSoftware(t *testing.T) {

11
server/service/testing_client.go
View File

@ -298,6 +298,17 @@ func (ts *withServer) getConfig() *appConfigResponse {
return responseBody return responseBody
} }
func (ts *withServer) applyTeamSpec(yamlSpec []byte) {
var teamSpec any
err := yaml.Unmarshal(yamlSpec, &teamSpec)
require.NoError(ts.s.T(), err)
specsReq := map[string]any{
"specs": []any{teamSpec},
}
ts.Do("POST", "/api/latest/fleet/spec/teams", specsReq, http.StatusOK)
}
func (ts *withServer) LoginSSOUser(username, password string) (fleet.Auth, string) { func (ts *withServer) LoginSSOUser(username, password string) (fleet.Auth, string) {
t := ts.s.T() t := ts.s.T()
auth, res := ts.loginSSOUser(username, password, "/api/v1/fleet/sso", http.StatusOK) auth, res := ts.loginSSOUser(username, password, "/api/v1/fleet/sso", http.StatusOK)

5
server/service/testing_utils.go
View File

@ -17,6 +17,7 @@ import (
eeservice "github.com/fleetdm/fleet/v4/ee/server/service" eeservice "github.com/fleetdm/fleet/v4/ee/server/service"
"github.com/fleetdm/fleet/v4/server/config" "github.com/fleetdm/fleet/v4/server/config"
"github.com/fleetdm/fleet/v4/server/contexts/license" "github.com/fleetdm/fleet/v4/server/contexts/license"
"github.com/fleetdm/fleet/v4/server/datastore/cached_mysql"
"github.com/fleetdm/fleet/v4/server/fleet" "github.com/fleetdm/fleet/v4/server/fleet"
"github.com/fleetdm/fleet/v4/server/logging" "github.com/fleetdm/fleet/v4/server/logging"
"github.com/fleetdm/fleet/v4/server/mail" "github.com/fleetdm/fleet/v4/server/mail"
@ -288,9 +289,13 @@ type TestServerOpts struct {
UseMailService bool UseMailService bool
APNSTopic string APNSTopic string
ProfileMatcher fleet.ProfileMatcher ProfileMatcher fleet.ProfileMatcher
EnableCachedDS bool
} }
func RunServerForTestsWithDS(t *testing.T, ds fleet.Datastore, opts ...*TestServerOpts) (map[string]fleet.User, *httptest.Server) { func RunServerForTestsWithDS(t *testing.T, ds fleet.Datastore, opts ...*TestServerOpts) (map[string]fleet.User, *httptest.Server) {
if len(opts) > 0 && opts[0].EnableCachedDS {
ds = cached_mysql.New(ds)
}
var rs fleet.QueryResultStore var rs fleet.QueryResultStore
if len(opts) > 0 && opts[0].Rs != nil { if len(opts) > 0 && opts[0].Rs != nil {
rs = opts[0].Rs rs = opts[0].Rs

2
server/service/users.go
View File

@ -863,7 +863,7 @@ func (svc *Service) PerformRequiredPasswordReset(ctx context.Context, password s
} }
if err := fleet.ValidatePasswordRequirements(password); err != nil { if err := fleet.ValidatePasswordRequirements(password); err != nil {
return nil, fleet.NewInvalidArgumentError("new_password", "Password does not meet required criteria") return nil, fleet.NewInvalidArgumentError("new_password", "Password does not meet required criteria: Must include 12 characters, at least 1 number (e.g. 0 - 9), and at least 1 symbol (e.g. &*#).")
} }
user.AdminForcedPasswordReset = false user.AdminForcedPasswordReset = false

4
terraform/addons/saml-auth-proxy/outputs.tf
View File

@ -11,3 +11,7 @@ output "name" {
output "lb_target_group_arn" { output "lb_target_group_arn" {
value = module.saml_auth_proxy_alb.target_group_arns[0] value = module.saml_auth_proxy_alb.target_group_arns[0]
} }
output "secretsmanager_secret_id" {
value = aws_secretsmanager_secret.saml_auth_proxy_cert.id
}

2
terraform/byo-vpc/byo-db/byo-ecs/variables.tf
View File

@ -13,7 +13,7 @@ variable "fleet_config" {
type = object({ type = object({
mem = optional(number, 4096) mem = optional(number, 4096)
cpu = optional(number, 512) cpu = optional(number, 512)
image = optional(string, "fleetdm/fleet:v4.38.0") image = optional(string, "fleetdm/fleet:v4.38.1")
family = optional(string, "fleet") family = optional(string, "fleet")
sidecars = optional(list(any), []) sidecars = optional(list(any), [])
depends_on = optional(list(any), []) depends_on = optional(list(any), [])

2
terraform/byo-vpc/byo-db/variables.tf
View File

@ -74,7 +74,7 @@ variable "fleet_config" {
type = object({ type = object({
mem = optional(number, 4096) mem = optional(number, 4096)
cpu = optional(number, 512) cpu = optional(number, 512)
image = optional(string, "fleetdm/fleet:v4.38.0") image = optional(string, "fleetdm/fleet:v4.38.1")
family = optional(string, "fleet") family = optional(string, "fleet")
sidecars = optional(list(any), []) sidecars = optional(list(any), [])
depends_on = optional(list(any), []) depends_on = optional(list(any), [])

2
terraform/byo-vpc/example/main.tf
View File

@ -17,7 +17,7 @@ provider "aws" {
} }
locals { locals {
fleet_image = "fleetdm/fleet:v4.38.0" fleet_image = "fleetdm/fleet:v4.38.1"
} }
resource "random_pet" "main" {} resource "random_pet" "main" {}

2
terraform/byo-vpc/variables.tf
View File

@ -163,7 +163,7 @@ variable "fleet_config" {
type = object({ type = object({
mem = optional(number, 4096) mem = optional(number, 4096)
cpu = optional(number, 512) cpu = optional(number, 512)
image = optional(string, "fleetdm/fleet:v4.38.0") image = optional(string, "fleetdm/fleet:v4.38.1")
family = optional(string, "fleet") family = optional(string, "fleet")
sidecars = optional(list(any), []) sidecars = optional(list(any), [])
depends_on = optional(list(any), []) depends_on = optional(list(any), [])

2
terraform/variables.tf
View File

@ -215,7 +215,7 @@ variable "fleet_config" {
type = object({ type = object({
mem = optional(number, 4096) mem = optional(number, 4096)
cpu = optional(number, 512) cpu = optional(number, 512)
image = optional(string, "fleetdm/fleet:v4.38.0") image = optional(string, "fleetdm/fleet:v4.38.1")
family = optional(string, "fleet") family = optional(string, "fleet")
sidecars = optional(list(any), []) sidecars = optional(list(any), [])
depends_on = optional(list(any), []) depends_on = optional(list(any), [])

2
tools/fleetctl-npm/package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "fleetctl", "name": "fleetctl",
"version": "v4.38.0", "version": "v4.38.1",
"description": "Installer for the fleetctl CLI tool", "description": "Installer for the fleetctl CLI tool",
"bin": { "bin": {
"fleetctl": "./run.js" "fleetctl": "./run.js"

27
website/api/controllers/view-integrations.js vendored Normal file
View File

@ -0,0 +1,27 @@
module.exports = {
friendlyName: 'View integrations',
description: 'Display "integrations" page.',
exits: {
success: {
viewTemplatePath: 'pages/integrations'
}
},
fn: async function () {
// Respond with view.
return {};
}
};

18
website/api/helpers/strings/to-html.js vendored
View File

@ -98,12 +98,18 @@ module.exports = {
}; };
} }
// Creating a custom codeblock renderer function to render mermaid code blocks (```mermaid```) without the added <pre> tags. // Creating a custom codeblock renderer function to add syntax highlighting keywords and render mermaid code blocks (```mermaid```) without the added <pre> tags.
customRenderer.code = function(code) { customRenderer.code = function(code, infostring) {
if(code.match(/\<!-- __LANG=\%mermaid\%__ --\>/g)) { if(infostring === 'mermaid') {
return '<code>'+_.escape(code)+'\n</code>'; return `<code class="mermaid">${_.escape(code)}</code>`;
} else { } else if(infostring === 'js') {// Interpret `js` as `javascript`
return '<pre><code>'+_.escape(code)+'\n</code></pre>'; return `<pre><code class="hljs javascript">${_.escape(code)}</code></pre>`;
} else if(infostring === 'bash' || infostring === 'sh') {// Interpret `sh` and `bash` as `bash`
return `<pre><code class="hljs bash">${_.escape(code)}</code></pre>`;
} else if(infostring !== '') {// leaving the code language as-is if the infoString is anything else.
return `<pre><code class="hljs ${_.escape(infostring)}">${_.escape(code)}</code></pre>`;
} else {// When unspecified, default to `text`
return `<pre><code class="nohighlight">${_.escape(code)}</code></pre>`;
} }
}; };

BIN
website/assets/images/icon-idp-22x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
website/assets/images/icon-rest-api-35x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
website/assets/images/icon-webhooks-30x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

BIN
website/assets/images/logo-active-directory-169x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.2 KiB

BIN
website/assets/images/logo-ansible-147x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.4 KiB

BIN
website/assets/images/logo-atlassian-140x18@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.2 KiB

BIN
website/assets/images/logo-aws-46x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

BIN
website/assets/images/logo-azure-169x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.0 KiB

BIN
website/assets/images/logo-chef-169x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

BIN
website/assets/images/logo-elastic-82x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.7 KiB

BIN
website/assets/images/logo-fastly-75x30@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

BIN
website/assets/images/logo-github-89x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

BIN
website/assets/images/logo-gitlab-124x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

BIN
website/assets/images/logo-google-chronicle-128x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.7 KiB

BIN
website/assets/images/logo-google-cloud-174x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
website/assets/images/logo-gusto-64x24@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
website/assets/images/logo-jira-185x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
website/assets/images/logo-munki-101x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.9 KiB

BIN
website/assets/images/logo-okta-85x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
website/assets/images/logo-puppet-79x28@2x.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

Some files were not shown because too many files have changed in this diff Show More