Instant deployment with Fleet Managed Cloud. Join the beta
Welcome to the documentation for Fleet, the lightweight telemetry platform for servers and workstations.
Install osquery and Fleet
Get startedCan't find what you need?
Supportfleetctl
using a new API-only user?after
key in api/v1/fleet/hosts
?To migrate to Fleet from Kolide Fleet, please follow the steps outlined in the Upgrading Fleet section of the documentation.
Fleet has been stress tested to 150,000 online hosts and 400,000 total enrolled hosts. Production deployments exist with over 100,000 hosts and numerous production deployments manage tens of thousands of hosts.
It’s standard deployment practice to have multiple Fleet servers behind a load balancer. However, typically the MySQL database is the performance bottleneck and a single Fleet server can handle tens of thousands of hosts.
No, currently, there’s no way to retrieve the name of the enroll secret with a query. This means that there's no way to create a label using your hosts' enroll secrets and then use this label as atarget for live queries or scheduled queries.
Typically folks will use some other unique identifier to create labels that distinguish each type of device. As a workaround, Fleet's manual labels provide a way to create groups of hosts without a query. These manual labels can then be used as targets for queries.
There is, however, a way to accomplish this even though the answer to the question remains "no": Teams. As of Fleet v4.0.0, you can group hosts in Teams either by enrolling them with a team specific secret, or by transferring hosts to a team. One the hosts you want to target are part of a team, you can create a query and target the team in question.
The update frequency for labels is configurable with the —osquery_label_update_interval flag (default 1 hour).
Authorization tokens are revoked when the “require password reset” action is selected for that user. User-initiated password resets do not expire the existing tokens.
Fleet can live query the osquery_schedule
table. Performing this live query allows you to get the performance data for your scheduled queries. Also consider scheduling a query to the osquery_schedule
table to get these logs into your logging pipeline.
Fleet provides standard interfaces for monitoring and alerting. See the Monitoring Fleet documentation for details.
The “Add User” button is disabled if SMTP (email) has not been configured for the Fleet server. Currently, there is no way to add new users without email capabilities.
One way to hack around this is to use a simulated mailserver like Mailhog. You can retrieve the email that was “sent” in the Mailhog UI, and provide users with the invite URL manually.
Some folks like to enforce users with SAML SSO enabled to login only via the SSO and not via password.
There is no option in the Fleet UI for disabling password-based authentication. However, users that have SSO enabled in Fleet will not be able to log in via password-based authentication.
If a user has SSO enabled, the Login page in the Fleet UI displays the “Email” and “Password” fields but on attempted password-based login, this user will receive an “Authentication failed” message.
Live query results (executed in the web UI or fleetctl query
) are pushed directly to the UI where the query is running. The results never go to a file unless you as the user manually save them.
Scheduled query results from enrolled hosts can be logged by Fleet.
For results to go to Fleet, the osquery --logger_plugin
flag must be set to tls
.
Folks typically use Fleet to ship logs to data aggregation systems like Splunk, the ELK stack, and Graylog.
Fleet supports multiple logging destinations for scheduled query results and status logs. The --osquery_result_log_plugin
and --osquery_status_log_plugin
can be set to:
filesystem
, firehose
, kinesis
, lambda
, pubsub
, kafkarest
, and stdout
.
See:
Expecting results, but not seeing anything in the logs?
SELECT * FROM time
).SELECT * FROM osquery_schedule
to check whether the query has been scheduled on the host.--filesystem_status_log_file
. This defaults to /tmp/osquery_status
. The host will output a status log each time it executes the query.Don't worry, this behavior is expected; it's part of how osquery works.
Fleet and osquery work together by communicating with heartbeats. Depending on how close the next heartbeat is, Fleet might return results a few seconds faster or slower.
By the way, to get around a phenomena called the "thundering herd problem", these heartbeats aren't exactly the same number of seconds apart each time. osquery implements a "splay", a few ± milliseconds that are added to or subtracted from the heartbeat interval to prevent these thundering herds. This helps prevent situations where many thousands of devices might unnecessarily attempt to communicate with the Fleet server at exactly the same time. (If you've ever used Socket.io, a similar phenomena can occur with that tool's automatic WebSocket reconnects.)
When a query executes in Fleet, the query is sent to all hosts at the same time, but results are returned from hosts at different times. In Fleet, results are shown as soon as Fleet receives a response from a host. Fleet does not sort the overall results across all hosts (the sort UI toggle is used for this). Instead, Fleet prioritizes speed when displaying the results. This means that if you use an ORDER BY
clause selection criteria in a query, the results may not initially appear with your desired order, however, the sort UI toggle allows you to sort by ascending or descending order for any of the displayed columns.
Both queries will run as scheduled on applicable hosts. If there are any hosts that both the scheduled run and the policy apply to, they will be queried twice.
Live query results are never logged to the filesystem of the Fleet server. See Where are my query results?.
If you're seeing query results using osqueryi
but not through Fleet, the most likely culprit is a permissions issue. Check out the osquery docs for more details and instructions for setting up Full Disk Access.
You cannot. Scheduled query results are logged to whatever logging plugin you have configured and are not stored in the Fleet DB.
However, the Fleet API exposes a significant amount of host information via the api/v1/fleet/hosts
and the api/v1/fleet/hosts/{id}
API endpoints. The api/v1/fleet/hosts
can even be configured to return additional host information.
For example, let's say you want to retrieve a host's OS version, installed software, and kernel version:
Each host’s OS version is available using the api/v1/fleet/hosts
API endpoint. Check out the API documentation for this endpoint.
The ability to view each host’s installed software was released behind a feature flag in Fleet 3.11.0 and called Software inventory. Check out the feature flag documentation for instructions on turning on Software inventory in Fleet.
Once the Software inventory feature is turned on, a list of a specific host’s installed software is available using the api/v1/fleet/hosts/{id}
endpoint. Check out the documentation for this endpoint.
It’s possible in Fleet to retrieve each host’s kernel version, using the Fleet API, through additional_queries
. The Fleet configuration options YAML file includes an additional_queries
property that allows you to append custom query results to the host details returned by the api/v1/fleet/hosts
endpoint. Check out an example configuration file with the additional_queries field.
Team enroll secrets allow you to automatically assign a host to a team.
The following are reasons why a host may not be updating a policy's response:
The policy's query includes tables that are not compatible with this host's platform. For example, if your policy's query contains the apps
table, which is only compatible on hosts running macOS, this policy will not update its response if this host is running Windows or Linux.
The policy's query includes invalid SQL syntax. If your policy's query includes invalid syntax, this policy will not update its response. You can check the syntax of your query by heading to the Queries page, selecting your query, and then selecting "Save."
If your device is showing up as an offline host in the Fleet instance, and you're sure that the computer has osquery running, we recommend trying the following:
Fleet relies on UUIDs so any overlap with host IP addresses should not cause a problem. The only time this might be an issue is if you are running a query that involves a specific IP address that exists in multiple locations as it might return multiple results - Fleet's teams feature can be used to restrict queries to specific hosts.
Yes, fleetd can be run alongside an existing, separately-installed osqueryd. If you have an existing osqueryd installed on a given host, you don't have to remove it prior to installing fleetd. The osquery instance provided by fleetd uses its own database directory that doesn't interfere with other osquery isntances installed on the host.
Yes, auto-updates can be disabled entirely by passing --disable-updates
as a flag when running fleetctl package
to generate your installer (easy) or by deploying a modified systemd file to your hosts (more complicated). We'd recommend the flag:
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --disable-updates
You can also indicate the channels you would like Orbit to watch for updates using the --orbit-channel
, --desktop-channel
, and --osqueryd-channel
flags:
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --orbit-channel=edge --desktop-channel=stable --osquery-channel=4
You can specify a major (4), minor (4.0) or patch (4.6.0) version as well as the stable
or edge
channels.
When a new osquery version is released, it is pushed to the edge
channel for beta testing. As soon as that version is deemed stable by the osquery project, it is moved to the stable
channel. Some versions may take a little longer than others to be tested and moved from edge
to stable
, especially when there are major changes.
Orbit checks for update metadata and downloads binaries at tuf.fleetctl.com
.
This isn't supported yet, but we're working on it!
If Fleet can't send logs to the destination, it will return an error to osquery. This causes osquery to retry sending the logs. The logs will then be stored in osquery's internal buffer until they are sent successfully, or they get expired if the buffered_log_max
(defaults to 1,000,000 logs) is exceeded. Check out the Remote logging buffering section on the osquery docs for more on this behavior.
Any extension table available in a host enrolled to Fleet can be queried by Fleet. Note that the "compatible with" message may show an error because it won't know your extension table, but the query will still work, and Fleet will gracefully ignore errors from any incompatible hosts.
If you are using a self-signed certificate on localhost
, add the --insecure
flag when building your installation packages:
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --insecure
This isn't currently supported, but we're working on it! You can track that issue here.
Currently, Fleet only stores the current state of your hosts (when they last communicated with Fleet). The best way at the moment to maintain historical data would be to use the REST API or the fleetctl
CLI to retrieve it manually. Then save the data you need to your schedule.
fleetctl is great for users that like to do things in a terminal (like iTerm on a Mac). Lots of tech folks are real power users of the terminal. It is also helpful for automating things like deployments.
The REST API is somewhat similar to fleetctl, but it tends to be used more by other computer programs rather than human users (although humans can use it too). For example, our Fleet UI talks to the server via the REST API. Folks can also use the REST API if they want to build their own programs that talk to the Fleet server.
The Fleet UI is built for human users to make interfacing with the Fleet server user-friendly and visually appealing. It also makes things simpler and more accessible to a broader range of users.
fleetctl
using a new API-only user?In versions prior to Fleet 4.13, a password reset is needed before a new API-only user can perform queries. You can find detailed instructions for setting that up here.
The REST API activities
endpoint provides a full breakdown of actions taken on queries, policies, and teams (Available in Fleet Premium) through the UI, the REST API, or fleetctl
.
By default, Fleet will query hosts for software inventory hourly. If you'd like to set a different interval, you can update the periodicity in your vulnerabilities configuration.
There are a few ways you can go about getting counts of hosts that meet specific criteria using the REST API. You can use GET /api/v1/fleet/hosts
or the fleetctl
CLI to gather a list of all hosts and then work with that data however you'd like. For example, you could retrieve all hosts using fleetctl get hosts
and then use jq
to pull out the data you need. The following example would give you a count of hosts by their OS version:
$ fleetctl get hosts --json | jq '.spec .os_version' | sort | uniq -c
1 "CentOS Stream 8.0.0"
2 "Ubuntu 20.4.0"
1 "macOS 11.5.2"
1 "macOS 11.6.3"
1 "macOS 12.1.0"
3 "macOS 12.2.1"
3 "macOS 12.3.0"
6 "macOS 12.3.1"
If you'd like to renew your Fleet Premium license key, please contact us here.
How to downgrade from Fleet Premium to Fleet Free:
First, back up your users and update all team-level users to global users:
fleetctl get user_roles > user_roles.yml
command. Save the user_roles.yml
file so
that, if you choose to upgrade later, you can restore user roles.Next, move all team-level scheduled queries to the global level:
Next, move all team level policies to the global level:
create your own policy, paste each item in the appropriate field, and select Save. 3. Delete each policy that belongs to a team because they will no longer run on any hosts following the downgrade process.
Next, back up your teams:
fleetctl get teams > teams.yml
command. Save the teams.yml
file so
that, if you choose to upgrade later, you can restore teams.Lastly, remove your Fleet Premium license key:
No. The agent options set using your software orchestration tool will override the default agent options that appear in the Settings > Organization settings > Agent options page. On this page, if you hit the Save button, the options that appear in the Fleet UI will override the agent options set using your software orchestration.
To uninstall the osquery agent, follow the below instructions for your operating system.
Run the Orbit cleanup script
Use the "Add or remove programs" dialog to remove Orbit.
Run sudo apt remove fleet-osquery -y
Run sudo rpm -e fleet-osquery-X.Y.Z.x86_64
Online hosts will respond to a live query.
A host is online if it has connected successfully in a window of time set by distributed_interval
(or config_tls_refresh
, whichever is smaller).
A buffer of 60 seconds is added to the calculation to avoid unnecessary flapping between online/offline status (in case hosts take a bit longer than expected to connect to Fleet).
The values for distributed_interval
and config_tls_refresh
can be found in the Settings > Organization settings > Agent options page for global hosts
and in the Settings > Teams > TEAM NAME > Agent options page for hosts that belong to a team.
For example:
distributed_interval=10, config_tls_refresh=30
A host is considered online if it has connected to Fleet in the last 70 (10+60) seconds.
distributed_interval=30, config_tls_refresh=20
A host is considered online if it has connected to Fleet in the last 80 (20+60) seconds.
Offline hosts won't respond to a live query. These hosts may be shut down, asleep, or not connected to the internet. A host could also be offline if there is a connection issue between the osquery agent running in the host and Fleet (see What should I do if my computer is showing up as an offline host?).
Changes were introduced in Fleet v4.20.0 that caused the features.additional_queries
set in at the global level to no longer apply to hosts assigned to a team. If you would like those queries to be applied to hosts assigned to a team, you will need to be include these queries under features.additional_queries
in each team's configuration.
after
key in api/v1/fleet/hosts
?There is a bug in MySQL validation in some versions of Fleet when using the created_at
and updated_at
columns as order_key
along with an after
filter. Adding h.
to the column in order_key
will return your results.
{{host}}/api/v1/fleet/hosts?order_key=h.created_at&order_direction=desc&after=2022-10-22T20:22:03Z
Depending on your infrastructure capabilities, and the number of hosts enrolled into your Fleet instance, Fleet might be slow or unresponsive after globally enabling a feature like software inventory.
In those cases, we recommend a slow rollout by partially enabling the feature by teams using the features
key of the teams configuration.
When updating agent options, you may see an error similar to this:
[...] unsupported key provided: "logger_plugin"
If you’re not using the latest osquery, use the fleetctl apply --force command to override validation.
This error indicates that you're providing a config option that isn't valid in the current version of osquery, typically because you're setting a command line flag through the configuration key. This has always been unsupported through the config plugin, but osquery has recently become more opinionated and Fleet now validates the configuration to make sure there aren't errors in the osquery agent.
If you are not using the latest version of osquery, you can create a config YAML file and apply it with fleetctl
using the --force
flag to override the validation:
fleetctl apply --force -f config.yaml
This feature is currently in development and is not ready for production use.
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, the token expires after a year or whenever the account that downloaded the token has their password changed.
When that happens, the token is rejected by Apple and must be renewed. The detailed steps are documented in the Apple documentation link above - in short, the Apple Business Manager Administrator or Content Manager must sign in to their account and download a new server token for the Fleet MDM server, and all Fleet instances must be restarted with that new token provided instead of the old one (see the MDM configuration documentation for details on how to do that).
There are many challenges to generating .msi packages on any OS but Windows. Errors will frequently resolve after multiple attempts and we've added retries by default in recent versions of fleetctl package
. Package creation is much more reliable on Intel Macs, Linux and Windows.
If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the Fleet repo.