Fleet gathers information from an osquery agent installed on each of your hosts. The recommended way to install osquery is using fleetd.
You can enroll macOS, Windows or Linux hosts via the CLI or UI. To learn how to enroll Chromebooks, see Enroll Chromebooks.
Fleet supports the latest version of osquery.
You must have
fleetctl
installed. Learn how to installfleetctl
.
The fleetctl package
command is used to generate Fleet's agent (fleetd) install package..
The --type
flag is used to specify the fleetd installer type. Note that Windows can only generate an MSI package:
A --fleet-url
(Fleet instance URL) and --enroll-secret
(Fleet enrollment secret) must be specified in order to communicate with Fleet instance.
Generate fleetd on macOS (.pkg)
fleetctl package --type pkg --fleet-url=example.fleetinstance.com --enroll-secret=85O6XRG8'!l~P&zWt_'f&$QK(sM8_D4x
Tip: To see all options for fleetctl package
command, run fleetctl package -h
in your Terminal.
To generate Fleet's agent (fleetd) in Fleet UI:
With hosts segmented into teams, you can apply unique queries and give users access to only the hosts in specific teams. Learn more about teams.
To enroll to a specific team: from the Hosts page, select the desired team from the menu at the top of the screen, then follow the instructions above for generating Fleet's agent (fleetd). The team's enroll secret will be included in the generated command.
If you're managing an enterprise environment with multiple hosts, you likely have an enterprise deployment tool like Munki, Jamf Pro, Chef, Ansible, or Puppet to deliver software to your hosts. You can use your software management tool of choice to distribute Fleet's agent (fleetd) generated via the instructions above.
Fleet Desktop is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine.
You can include Fleet Desktop in Fleet's agent (fleetd) by including --fleet-desktop
in the fleetctl package
command.
You can use fleetctl debug connection
to troubleshoot issues with server/client TLS certificates, e.g.:
# Test TLS connection using the CA root file that will be embedded on fleetd packages:
fleetctl debug connection \
https://fleet.example.com
# Test TLS connection using a custom CA root file:
fleetctl debug connection \
--fleet-certificate ./your-ca-root.pem \
https://fleet.example.com
The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using Google Admin. 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:
More complex setups may be necessary, depending on the organization's needs, but the basic principle remains the same.
Create an organizational unit where the extension should be installed. Add all the relevant users to this OU.
In the Google Admin console:
For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above
Create an organizational unit to house devices where the extension should not be installed. Add all the relevant devices to this OU.
In the Google Admin console:
How to unenroll a host from Fleet:
Determine if your host has MDM features turned on by looking at the MDM status on the host's Host details page.
For macOS hosts with MDM turned on, select Actions > Turn off MDM to turn MDM off. Instructions for turning off MDM on Windows hosts coming soon.
Determine the platform of the host you're trying to unenroll and follow the instructions to uninstall the fleetd agent:
sudo apt remove fleet-osquery -y
.sudo rpm -e fleet-osquery-X.Y.Z.x86_64
.graph LR;
tuf["<a href=https://theupdateframework.io/>TUF</a> file server<br>(default: <a href=https://tuf.fleetctl.com>tuf.fleetctl.com</a>)"];
fleet_server[Fleet<br>Server];
subgraph fleetd
orbit[orbit];
desktop[Fleet Desktop<br>Tray App];
osqueryd[osqueryd];
desktop_browser[Fleet Desktop<br> from Browser];
end
orbit -- "Fleet Orbit API (TLS)" --> fleet_server;
desktop -- "Fleet Desktop API (TLS)" --> fleet_server;
osqueryd -- "osquery<br>remote API (TLS)" --> fleet_server;
desktop_browser -- "My Device API (TLS)" --> fleet_server;
orbit -- "Auto Update (TLS)" --> tuf;
Note: Currently, the
fleetctl package
command does not support signing Windows fleetd. Windows fleetd can be signed after building.
The fleetctl package
command supports signing and notarizing macOS fleetd via the
--sign-identity
and --notarize
flags.
Check out the example below:
[email protected] AC_PASSWORD=app-specific-password fleetctl package --type pkg --sign-identity=[PATH TO SIGN IDENTITY] --notarize --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET]
The above command must be run on a macOS device, as the notarizing and signing of macOS fleetd can only be done on macOS devices.
Also, remember to replace both AC_USERNAME
and AC_PASSWORD
environment variables with your Apple ID and a valid app-specific 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 under "Team ID."
MacOS does not allow applications to access all system files by default.
If you are using an MDM solution or Fleet's MDM features, one of which is required to deploy these profiles, you can deploy a "Privacy Preferences Policy Control" policy to grant fleetd or osquery that level of access.
This is required to query for files located in protected paths as well as to use event tables that require access to the EndpointSecurity API, such as es_process_events.
If you use plain osquery, instructions are available here.
On a system with osquery installed via Fleet's agent (fleetd), obtain the
CodeRequirement
of fleetd by running:
codesign -dr - /opt/orbit/bin/orbit/macos/stable/orbit
The output should be similar or identical to:
Executable=/opt/orbit/bin/orbit/macos/edge/orbit
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 down the executable path and the entire identifier.
Osqueryd will inherit the privileges from Orbit and does not need explicit permissions.
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:
If your MDM solution does not have built-in support for privacy preferences profiles, you can use PPPC-Utility to create a profile with those values, then upload it to your MDM as a custom profile.
Link the profile to a test group that contains at least one Mac. Once the computer has received the profile, which you can verify by looking at Profiles in System Preferences, run this query from Fleet:
SELECT * FROM file WHERE path LIKE '/Users/%/Downloads/%%';
If this query returns files, the profile was applied, as Downloads is a protected location. You can now enjoy the benefits of osquery on all system files and start using the es_process_events table!
If this query does not return data, you can look at operating system logs to confirm whether or not full disk access has been applied.
See the last hour of logs related to TCC permissions with this command:
log show --predicate 'subsystem == "com.apple.TCC"' --info --last 1h
You can then look for orbit
or osquery
to narrow down results.
Applies only to Fleet Premium
Fleetd supports using TLS client certificates for authentication to the Fleet server and TUF server.
When generating the packages, use the following flags:
fleetctl package \
[...]
--fleet-tls-client-certificate=fleet-client.crt \
--fleet-tls-client-key=fleet-client.key \
--update-tls-client-certificate=update-client.crt \
--update-tls-client-key=update-client.key \
[...]
The certificates must be in PEM format.
The client certificates can also be pushed to existing installations by placing them in the following locations:
/opt/orbit/fleet_client.crt
/opt/orbit/fleet_client.key
/opt/orbit/update_client.crt
/opt/orbit/update_client.key
C:\Program Files\Orbit\fleet_client.crt
C:\Program Files\Orbit\fleet_client.key
C:\Program Files\Orbit\update_client.crt
C:\Program Files\Orbit\update_client.key
If using Fleet Desktop, you may need to specify an alternative host for the "My device" URL (in the Fleet tray icon). Such alternative host should not require client certificates on the TLS connection.
fleetctl package
[...]
--fleet-desktop \
--fleet-desktop-alternative-browser-host=fleet-desktop.example.com \
[...]
If this setting is not used, you will need to configure client TLS certificates on devices' browsers.
Fleetd uses the concept of "update channels" to determine the version of it's components: Orbit, Fleet Desktop, osquery.
Configure update channels for these components with the --orbit-channel
, --desktop-channel
and --osqueryd-channel
flags when running the fleetctl package command
.
Channel | Versions |
---|---|
4 |
4.x.x |
4.6 |
4.6.x |
4.6.0 |
4.6.0 |
Additionally, stable
and edge
are special channel names. The stable
channel will provide the most recent osquery version that Fleet deems to be stable.
When a new version of osquery is released, it's added to the edge
channel for beta testing. Fleet then provides input to the osquery TSC based on testing. After the version is declared stable by the osquery TSC, Fleet will promote the version to stable
ASAP.
Fleet comes packaged with osqueryi
which is a tool for testing osquery queries locally.
With fleetd installed on your host, run orbit osqueryi
or orbit shell
to open the osqueryi
.
Fleetd will send stdout/stderr logs to the following directories:
/private/var/log/orbit/orbit.std{out|err}.log
.C:\Windows\system32\config\systemprofile\AppData\Local\FleetDM\Orbit\Logs\orbit-osquery.log
(the log file is rotated)./var/log/syslog
on Debian systems, /var/log/messages
on CentOS, and journalctl -u orbit
on Fedora).If the logger_path
agent configuration is set to filesystem
, fleetd will send osquery's "result" and "status" logs to the following directories:
On macOS and Windows, fleetd will add the enroll secret to the system keystore (Keychain on macOS, Credential Manager on Windows) on launch. Subsequent launches will retrieve the enroll secret from the keystore.
System keystore access can be disabled via --disable-keystore
flag for the fleetctl package
command. On macOS, subsequent installations of fleetd must be signed by the same organization as the original installation to access the enroll secret in the keychain.
Note: The keychain is not used on macOS when the enroll secret is provided via MDM profile. Keychain support when passing the enroll secret via MDM profile is coming soon.
Applies only to Fleet Premium
When generating Fleet's agent (fleetd) for Windows hosts (.msi) on a Windows or macOS machine, you can tell fleetctl package
to
use local installations of the 3 WiX v3 binaries used by this command (heat.exe
, candle.exe
, and
light.exe
) instead of those in a pre-configured container, which is the default behavior. To do
so:
fleetctl package
, and pass the absolute path above as the string argument to the
--local-wix-dir
flag. For example: fleetctl package --type msi --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLLMENT SECRET] --local-wix-dir "\Users\me\AppData\Local\Temp\wix311-binaries"
If the provided path doesn't contain all 3 binaries, the command will fail.Note: Creating a fleetd agent for Windows (.msi) on macOS also requires Wine. To install Wine see the script here.
Config-less deployment allows for Fleet's agent (fleetd) to be installed without embedding configuration settings directly into the package. This approach is ideal for environments requiring flexibility in managing enrollment secrets and server URLs. For detailed instructions, visit the Config-less fleetd agent deployment guide.
Warning: If you remove the configuration profile with the settings from macOS,
fleetd
won't work anymore until a similar profile is installed again. If the profile is delivered via MDM, and MDM is turned off, you might face this scenario.
Any features listed here are not recommended for use in production environments
Using fleetd
without enrolling Orbit
Only available in fleetd v1.15.1 on Linux and macOS
It is possible to generate a fleetd package that does not connect to Fleet by omitting the --fleet-url
and --enroll-secret
flags when building a package.
This can be useful in situations where you would like to test using fleetd
to manage osquery updates while still managing osquery command-line flags and extensions locally
but can result in a large volume of error logs. In fleetd v1.15.1, we added an experimental feature to reduce log chatter in this scenario.
Applying the environmental variable "FLEETD_SILENCE_ENROLL_ERROR"=1
on a host will silence fleetd enrollment errors if a --fleet-url
is not present.
This variable is read at launch and will require a restart of the Orbit service if it is not set before installing fleetd
v1.15.1.