- [Add hosts with plain osquery](#add-hosts-with-plain-osquery)
- [Set up your Fleet enroll secret](#set-up-your-fleet-enroll-secret)
- [Provide the TLS certificate that osquery will use to communicate with Fleet](#provide-the-tls-certificate-that-osquery-will-use-to-communicate-with-fleet)
- [Configure and launch osquery](#configure-and-launch-osquery)
- [Launching osqueryd using command-line flags](#launching-osqueryd-using-command-line-flags)
- [Launching osqueryd using a flag file](#launching-osqueryd-using-a-flag-file)
- [Migrating from plain osquery to osquery installer](#migrating-from-plain-osquery-to-osquery-installer)
Fleet gathers information from an [osquery](https://github.com/osquery/osquery) agent installed on each of your hosts. The recommended way to install osquery is using Fleetd, which includes [Orbit](https://fleetdm.com/docs/using-fleet/fleetd), Fleet's lightweight osquery runtime and auto-updater.
To create a Fleet installer, you can use the `fleetctl package` command. To use the `fleetctl package` command, you must first install the `fleetctl` command-line tool. [Learn how to install `fleetctl`](https://fleetdm.com/fleetctl-preview).
The `fleetctl package` can create a Fleetd installer, which adds macOS hosts (**.pkg**), Windows hosts (**.msi**), or Linux hosts (**.deb** or **.rpm**) to Fleet.
The following command creates a Fleetd installer, `.pkg` file, which adds macOS hosts to Fleet. Locate this osquery installer in the folder where the `fleetctl package` command is run.
>**Note:** The only configuration option required to create an installer is `--type`. However, to communicate with a Fleet instance, you'll need to specify a `--fleet-url` and `--enroll-secret`. When those flags are not set, fleetd will log errors.
>**Note:** Currently, the `fleetctl package` does not provide support for signing Windows Fleetd installers. Windows installers can be signed after building.
Also, remember to replace both `AC_USERNAME` and `AC_PASSWORD` environment variables with your Apple ID and a valid [app-specific](https://support.apple.com/en-ca/HT204397) password, respectively. Some organizations (notably those with Apple Enterprise Developer Accounts) may also need to specify `AC_TEAM_ID`. This value can be found on the [Apple Developer "Membership" page](https://developer.apple.com/account/#!/membership) under "Team ID."
Once installed on the target host, Fleet Desktop will be managed by Fleetd. To learn more about Fleetd updates, see [here](https://fleetdm.com/docs/deploying/fleetctl-agent-updates).
To prevent this auto-update behavior, you can turn off auto-updates via the `--disable-updates` flag or you can set a specific channel using the `--desktop-channel` flag.
If you're managing an enterprise environment with multiple hosts, you likely have an enterprise deployment tool like [Munki](https://www.munki.org/munki/), [Jamf Pro](https://www.jamf.com/products/jamf-pro/), [Chef](https://www.chef.io/), [Ansible](https://www.ansible.com/), or [Puppet](https://puppet.com/) to deliver software to your hosts.
The Teams feature in Fleet allows you to place hosts in exclusive groups. With hosts segmented into Teams, you can apply unique queries and give users access to only the hosts in specific Teams.
You can add a host to a team by generating and using a unique osquery installer for a team or by [manually transferring a host to a team in the Fleet UI](https://fleetdm.com/docs/using-fleet/teams#transfer-hosts-to-a-team).
3. Next, select **Add hosts** and copy the `fleetctl package` command for the platform (macOS, Windows, Linux) of the hosts you'd like to add to a team in Fleet.
The following command-line flags to `fleetctl package` allow you to configure an osquery installer further to communicate with a specific Fleet instance.
| --use-system-configuration | Try to read --fleet-url and --enroll-secret using configuration in the host (currently only macOS profiles are supported) |
Fleet supports other methods for adding your hosts to Fleet, such as the [plain osquery binaries](#add-hosts-with-plain-osquery) or [Kolide Osquery Launcher](https://github.com/kolide/launcher/blob/master/docs/launcher.md#connecting-to-fleet).
You can find various ways to install osquery on your hosts at https://osquery.io/downloads. Once you have installed osquery, you need to do three things on your hosts:
The enroll secret is a value that osquery provides to authenticate with Fleet. There are a few ways you can set the enroll secret on the hosts which you control. You can either set the value as
The value of the environment variable or content of the file should be a secret shared between the osqueryd client and the Fleet server. This is osqueryd's passphrase which it uses to authenticate with Fleet, convincing Fleet that it is actually one of your hosts. The passphrase could be whatever you'd like, but it would be prudent to have the passphrase long, complex, mixed-case, etc. When you launch the Fleet server, you should specify this same value.
If you use an environment variable for this, you can specify it with the `--enroll_secret_env` flag when you launch osqueryd. If you use a local file for this, you can specify its path with the `--enroll_secret_path` flag.
If your organization has a robust internal public key infrastructure (PKI) and you already deploy TLS client certificates to each host to uniquely identify them, then osquery supports an advanced authentication mechanism that takes advantage of this. Fleet can be fronted with a proxy that will perform the TLS client authentication.
When Fleet uses a self-signed certificate, osquery agents will need a copy of that certificate in order to authenticate the Fleet server. If clients connect directly to the Fleet server, you can download the certificate through the Fleet UI. From the main dashboard (`/hosts/manage`), click **Add New Host** and **Fetch Certificate**. If Fleet is running behind a load-balancer that terminates TLS, you will have to talk to your system administrator about where to find this certificate.
Assuming that you are deploying your enroll secret in the file `/etc/osquery/enroll_secret` and your osquery server certificate is at `/etc/osquery/fleet.crt`, you could copy and paste the following command with the following flags (be sure to replace `fleet.acme.net` with the hostname or IP of your Fleet installation):
If your osquery server certificate is deployed to a path that is not `/etc/osquery/fleet.crt`, be sure to update the `--tls_server_certs` flag. Similarly, if your enroll secret is in an environment variable that is not called `OSQUERY_ENROLL_SECRET`. Then, be sure to update the `--enroll_secret_env` environment variable.
If your enroll secret is defined in a local file, specify the file's path with the `--enroll_secret_path` flag instead of using the `--enroll_secret_env` flag.
For your convenience, osqueryd supports putting all your flags into a single file. We suggest deploying this file to `/etc/osquery/fleet.flags`. If you've deployed the appropriate osquery flags to that path, you could simply launch osquery via:
When using a flag file on Windows, make sure that file paths in the flag file are absolute and not quoted. For example, in `C:\Program Files\osquery\osquery.flags`:
## Add Chromebooks with the fleetd Chrome extension
> 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.
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.
> 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.
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.
designated => identifier "com.fleetdm.orbit" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "8VBZ3948LU"
> **NOTE:** Depending on the version of `fleetctl` used to package and install Orbit, as well as the update channel you've specified, the executable path may differ.
Note down the **executable path** and the entire **identifier**.
Osqueryd will inherit the privileges from Orbit and does not need explicit permissions.
#### Creating the profile
Depending on your MDM, this might be possible in the UI or require a custom profile. If your MDM has a feature to configure *Policy Preferences*, follow these steps:
