From 018e3340029a6f16d6460747beb55169dffb7c27 Mon Sep 17 00:00:00 2001 From: RachelElysia Date: Mon, 23 Dec 2024 10:45:35 -0500 Subject: [PATCH 1/2] Fleet docs: Update queries guides --- ...try-from-your-devices-with-live-queries.md | 25 +++++++++++-- articles/managing-labels-in-fleet.md | 4 +- articles/queries.md | 37 ++++++++++++++++--- 3 files changed, 54 insertions(+), 12 deletions(-) diff --git a/articles/get-current-telemetry-from-your-devices-with-live-queries.md b/articles/get-current-telemetry-from-your-devices-with-live-queries.md index 91eede226da1..0cbfbb4d30c1 100644 --- a/articles/get-current-telemetry-from-your-devices-with-live-queries.md +++ b/articles/get-current-telemetry-from-your-devices-with-live-queries.md @@ -13,15 +13,29 @@ Live queries enable administrators to ask near real-time questions of all online devices, such as checking the encryption status of SSH keys across endpoints, or obtaining the uptime of each server within their purview. This enables them to promptly identify and address any issues, thereby reducing downtime and maintaining operational efficiency. These tasks, which would be time-consuming and complex if done manually, are streamlined through live queries, offering real-time insights into the status and posture of the entire fleet of devices helping IT and security. -## Live queries under the hood +## How to run a live query + +Live queries can be run from the web UI, the REST API, or the command-line interface called `fleetctl`. + +For detailed instructions on creating and running queries in the web UI, refer to this [guide](https://fleetdm.com/guides/queries). + +Using the REST API, users can run a live query [using a saved query's id](https://fleetdm.com/docs/rest-api/rest-api#run-live-query) or with [custom SQL on a specific host](https://fleetdm.com/docs/rest-api/rest-api#live-query-one-host-ad-hoc). + +> Note: Users with the observer role do not have permission to run live queries. -Live queries can be run from the web UI, the command-line interface called `fleetctl`, or the REST API. The user creates a query and selects which devices will run that query. Here is an example using `fleetctl` to obtain the operating system name and version for all devices: +## Running a live query using fleetctl + +Here is an example using [fleetctl](https://fleetdm.com/guides/fleetctl) to obtain the operating system name and version for all devices: ``` -fleetctl query --query "select name, version from os_version;" --labels "All Hosts" +fleetctl query --query "select name, version from os_version;" --labels "All Hosts" > results.json ``` +The `--query` option specifies the Osquery query you want to run. The --labels "All Hosts" option ensures the query is executed on all hosts connected to your Fleet instance. The `--labels` option targets devices with the specified labels. If multiple labels are provided, the query runs on devices that match any of them. For example, `--labels "production,dev"` runs the query on devices labeled as either `production` or `dev`. As the query runs, the results will be displayed in real-time. `> results.json` option redirects the output to a JSON file. + + +## Live queries under the hood When a client initiates a live query, the server first creates a **Query Campaign** record in the MySQL database. A Fleet deployment consists of several servers behind a load balancer, so storing the record in the DB makes all servers aware of the new query campaign. @@ -49,6 +63,8 @@ Then, the osquery agents run the actual query on their host, and write the resul Only the one server communicating with the client subscribes to the results. It processes the data from the cache, keeps track of how many hosts reported back, and communicates results back to the client. The web UI and `fleetctl` interfaces use a [WebSockets API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), and results are reported as they come in. The REST API, on the other hand, only sends a response after all online hosts have reported their query results. +The query response time can vary due to osquery's heartbeat response time. This is because devices check in with the servers periodically, and the query is executed during these check-ins. + ## Discover more @@ -60,8 +76,9 @@ As you reflect on the capabilities of live queries with Fleet, consider your net We encourage you to explore the possibilities and share your thoughts or questions. Perhaps you’re facing a specific query challenge or an innovative use case you’ve discovered. Whatever it may be, the world of live queries is vast and ripe for exploration. Join us in [Fleet’s Slack forums](https://fleetdm.com/support) to engage with a community of like-minded professionals and deepen your understanding of what live queries can achieve in your environment. -API Documentation: +Documentation: +* [Run live query with the UI](https://fleetdm.com/guides/queries) * [Run live query with REST API](https://fleetdm.com/docs/rest-api/rest-api#run-live-query) * [Run live query with WebSockets](https://github.com/fleetdm/fleet/blob/6fd06d648601edd89c01e25426e2e35ff2a8a37b/docs/Contributing/API-for-contributors.md#run-live-query) diff --git a/articles/managing-labels-in-fleet.md b/articles/managing-labels-in-fleet.md index 7dcc5a3ede3d..4a258b70cc5e 100644 --- a/articles/managing-labels-in-fleet.md +++ b/articles/managing-labels-in-fleet.md @@ -12,7 +12,7 @@ To access and manage labels in Fleet: 1. **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. -2. **Filter by labels**: In the "Filter by…" drop-down menu, you will see options for "Platforms" (e.g., macOS, Windows, Linux) and "Labels." +2. **Filter by labels**: In the "Filter by platform or label" drop-down menu, you will see options for "Platforms" (e.g., macOS, Windows, Linux) and "Labels." You can add a new label, filter existing labels by name, or select a label from the list. Selecting a label filters the view only to show hosts with that label. @@ -24,7 +24,7 @@ To add a new label: 1. **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. -2. **Access labels**: Click the "Filter by…" drop-down. +2. **Access labels**: Click the "Filter by platform or label" drop-down. 3. **Select "Add Label +"**: This option allows you to create a new label. 4. **Choose label Type**: You will be prompted to choose between a "Dynamic" or "Manual" label. 1. **Dynamic**: Enter a name and description, then build your query and select the platforms to which this label applies. diff --git a/articles/queries.md b/articles/queries.md index 60c7b6eef5d6..f2790bb1b78d 100644 --- a/articles/queries.md +++ b/articles/queries.md @@ -9,6 +9,7 @@ Queries in Fleet allow you to ask questions to help you manage, monitor, and ide ### In this guide: - [Create a query](#create-a-query) +- [View a query report](#view-a-query-report) - [Run a query](#run-a-query) - [Schedule a query](#schedule-a-query) @@ -31,6 +32,24 @@ How to create a query: 4. Select **Save**, enter a name and description for your query, select the frequency that the query should run at, and select **Save query**. + +## View a query report + +Fleet will store up to 1000 results for each scheduled query to give users a snapshot of query results. If the number of results for a scheduled query is below 1000, then the results will continuously get updated every time the hosts send results to Fleet. + +As you enable query reports, it is advisable to monitor your database to determine if it needs to be scaled up. As an alternative, you can disable query reports. + +> To disable query reports globally, modify `server_settings.query_reports_disabled` field in the global configuration. To disable reports for individual queries, use the `discard_data` field. + +How to view a query report: + +1. In the top navigation, select **Queries**. + +2. In the **Queries** table, find the query you'd like to run and select the query's name to navigate to the query console. + +3. If you want to download the query report, select **Export results** to save it as a CSV. + + ## Run a query Run a live query to get answers for all of your online hosts. @@ -43,7 +62,11 @@ How to run a query: 2. In the **Queries** table, find the query you'd like to run and select the query's name to navigate to the query console. -3. Select **Run query** to navigate to the target picker. Select **All hosts** and select **Run**. This will run the query against all your hosts. +3. Select **Live query** to navigate to the target picker. Select **All hosts** and select **Run**. This will run the query against all your hosts. + +4. If you want to download the live query results, select **Export results** to save it as a CSV. + +> Fleet 4.24.0 and later versions provide notifications in the activity feed for live queries. The query may take several seconds to complete because Fleet has to wait for the hosts to respond with results. @@ -53,11 +76,11 @@ The query may take several seconds to complete because Fleet has to wait for the *In Fleet 4.35.0, the "Schedule" page was removed, and query automations are now configured on the "Queries" page. Instructions for scheduling queries in earlier versions of Fleet can be found [here](https://github.com/fleetdm/fleet/blob/ac797c8f81ede770853c25fd04102da9f5e109bf/docs/Using-Fleet/Fleet-UI.md#schedule-a-query).* -Fleet allows you to schedule queries to run at a set frequency. Scheduled queries will send data to Fleet and/or your [log destination](https://fleetdm.com/docs/using-fleet/log-destinations) automatically. +Fleet allows you to schedule queries to run at a set frequency. By default, queries that run on a schedule will only target platforms compatible with that query. This behavior can be overridden by setting the platforms in **Advanced options** when saving a query. -By default, queries that run on a schedule will only target platforms compatible with that query. This behavior can be overridden by setting the platforms in **Advanced options** when saving a query. +Scheduled queries will send data to Fleet and/or your [log destination](https://fleetdm.com/docs/using-fleet/log-destinations) automatically. Query automations can be turned off in **Advanced options** or using the bulk query automations UI. -**How to send data to your log destination:** +How to configure query automations in bulk: *Only users with the [admin role](https://fleetdm.com/docs/using-fleet/manage-access#admin) can manage query automations.* @@ -67,12 +90,14 @@ By default, queries that run on a schedule will only target platforms compatible 3. Check the box next to the queries you want to send data to your log destination, and select **Save**. (The frequency that queries run at is set when a query is created.) -> Note: When viewing a specific [team](https://fleetdm.com/docs/using-fleet/segment-hosts) in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed. +> Note: When viewing a specific [team](https://fleetdm.com/docs/using-fleet/segment-hosts) in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed.∂ ### Further reading +- [REST API documentation for queries](https://fleetdm.com/docs/rest-api/rest-api#queries) - [Import and export queries in Fleet](https://fleetdm.com/guides/import-and-export-queries-in-fleet) -- [Osquery: Consider joining against the users table](https://fleetdm.com/guides/osquery-consider-joining-against-the-users-table) +- [Using fleetctl to run a live query and how live queries work](https://fleetdm.com/guides/get-current-telemetry-from-your-devices-with-live-queries#basic-article) +- [Osquery: Consider joining against the users table](https://fleetdm.com/guides/osquery-consider-joining-against-the-users-table) From 8ae308ed501fe9fb064d4324e20d77ea02f30ca8 Mon Sep 17 00:00:00 2001 From: RachelElysia Date: Mon, 23 Dec 2024 10:49:22 -0500 Subject: [PATCH 2/2] Fix typo --- articles/queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/queries.md b/articles/queries.md index f2790bb1b78d..6ce2f53d0ed7 100644 --- a/articles/queries.md +++ b/articles/queries.md @@ -90,7 +90,7 @@ How to configure query automations in bulk: 3. Check the box next to the queries you want to send data to your log destination, and select **Save**. (The frequency that queries run at is set when a query is created.) -> Note: When viewing a specific [team](https://fleetdm.com/docs/using-fleet/segment-hosts) in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed.∂ +> Note: When viewing a specific [team](https://fleetdm.com/docs/using-fleet/segment-hosts) in Fleet Premium, only queries that belong to the selected team will be listed. When configuring query automations for all hosts, only global queries will be listed. ### Further reading