Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 8 Packages Projects Releases Wiki Activity

Update "Learn how to use Fleet" for Fleet Sandbox (#7142)

Browse Source 
- Update "Learn how to use Fleet" docs page to walk a Fleet Sandbox user through adding their device and running a query
- Add a "Get operating system information" query to standard query library for the "Learn how to use Fleet" walkthrough
- Update Fleet's top level README to point users who want to try Fleet to Fleet Sandbox
- Update "How to install osquery..." (macOS, Windows, Linux) blog posts to point users who want to try Fleet to Fleet Sandbox
- Move `fleetctl preview` questions to "Contributing" FAQ section in docs. This is because `fleetctl preview` is now a testing tool for Fleet contributors
- Update "Deploying" docs to point users who want to try Fleet to Fleet Sandbox
This commit is contained in:
Noah Talerman
2022-08-19 14:13:15 -04:00
committed by GitHub
parent 009a8eea69
commit b0e37accc9
14 changed files with 99 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/smoke-tests.md
+1 -1
View File
@@ -15,7 +15,7 @@ assignees: ''
# Important reference data
1. [fleetctl preview setup](https://fleetdm.com/get-started)
1. [fleetctl preview setup](https://fleetdm.com/fleetctl-preview)
2. [permissions documentation](https://fleetdm.com/docs/using-fleet/permissions)
3. premium tests require license key (needs renewal) `fleetctl preview --license-key=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJGbGVldCBEZXZpY2UgTWFuYWdlbWVudCBJbmMuIiwiZXhwIjoxNjQwOTk1MjAwLCJzdWIiOiJkZXZlbG9wbWVudCIsImRldmljZXMiOjEwMCwibm90ZSI6ImZvciBkZXZlbG9wbWVudCBvbmx5IiwidGllciI6ImJhc2ljIiwiaWF0IjoxNjIyNDI2NTg2fQ.WmZ0kG4seW3IrNvULCHUPBSfFdqj38A_eiXdV_DFunMHechjHbkwtfkf1J6JQJoDyqn8raXpgbdhafDwv3rmDw`
4. premium tests require license key (active - Expires Sunday, January 1, 2023 12:00:00 AM) `fleetctl preview --license-key=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJGbGVldCBEZXZpY2UgTWFuYWdlbWVudCBJbmMuIiwiZXhwIjoxNjcyNTMxMjAwLCJzdWIiOiJGbGVldCBEZXZpY2UgTWFuYWdlbWVudCIsImRldmljZXMiOjEwMCwibm90ZSI6ImZvciBkZXZlbG9wbWVudCBvbmx5IiwidGllciI6InByZW1pdW0iLCJpYXQiOjE2NDI1MjIxODF9.EGHQjIzM73YyMbnCruswzg360DEYCsDi9uz48YcDwQHq90BabGT5PIXRiculw79emGj5sk2aKgccTd2hU5J7Jw`
README.md
+3 -13
View File
@@ -8,22 +8,12 @@ Fleet is the lightweight, open source telemetry platform for servers and worksta
## Try Fleet
#### With [Node.js](https://nodejs.org/en/download/) and [Docker](https://docs.docker.com/get-docker/) installed:
```bash
# Install the Fleet command-line tool
sudo npm install -g fleetctl
# Run a local demo of the Fleet server
sudo fleetctl preview
```
> Windows users can omit `sudo`, and should run the command in `Cmd`/`PowerShell` as administrators.
The Fleet UI is now available at http://localhost:1337.
Head to [fleetdm.com/try-fleet](https://fleetdm.com/try-fleet/register) to fire up a one-off cloud instance for quickly trying out Fleet.
#### Now what?
Check out the [Ask questions about your devices tutorial](./docs/Using-Fleet/Learn-how-to-use-Fleet.md#how-to-ask-questions-about-your-devices) to learn where to see your devices in Fleet, how to add Fleet's standard query library, and how to ask questions about your devices by running queries.
Check out the [Learn how to use Fleet doc](https://fleetdm.com/docs/using-fleet/learn-how-to-use-fleet)
to learn how to add your device to Fleet and how to ask questions about your devices by running queries.
## Team
Fleet is [independently backed](https://linkedin.com/company/fleetdm) and actively maintained with the help of many amazing [contributors](https://github.com/fleetdm/fleet/graphs/contributors).
articles/how-to-install-osquery-and-enroll-linux-devices-into-fleet.md
+5 -1
View File
@@ -1,8 +1,12 @@
# How to install osquery and enroll Linux devices into Fleet
Here, we will cover enrolling Linux devices to an existing Fleet server. If you don’t have a Fleet server configured already, check out the [Server Installation docs](https://fleetdm.com/docs/deploying/server-installation). If you’re still getting to know Fleet and would like to skip the server setup process and check out a preview, you can [Get Started](https://fleetdm.com/get-started) using `fleetctl preview` instead.
Here, we will cover enrolling Linux devices to an existing Fleet server. If you don’t have a Fleet
server configured already, check out [Deploying Fleet on Render](https://fleetdm.com/deploy/deploying-fleet-on-render). If you’re still getting to know
Fleet
and would like to skip the server setup process and try Fleet, you can [try Fleet in a temporary cloud instance](https://fleetdm.com/try-fleet/register).
## Prerequisites
1. Access to an existing Fleet server
2. The `fleetctl` command line tool
articles/how-to-install-osquery-and-enroll-macos-devices-into-fleet.md
+7 -5
View File
@@ -1,14 +1,16 @@
# How to install osquery and enroll macOS devices into Fleet
The easiest way to install osquery and enroll macOS devices into your Fleet instance is to use the Fleet osquery installer.
Alternatively, you can run a preview environment of Fleet locally (which automatically adds your device to the locally running Fleet server). Check out the [Getting Started](https://fleetdm.com/get-started) guide for instructions on setting that up.
Here, we will cover enrolling macOS devices to an existing Fleet server. If you don’t have a Fleet
server configured already, check out [Deploying Fleet on Render](https://fleetdm.com/deploy/deploying-fleet-on-render). If you’re still getting to know
Fleet
and would like to skip the server setup process and try Fleet, you can [try Fleet in a temporary cloud instance](https://fleetdm.com/try-fleet/register).
## Prerequisites
Before installing osquery on macOS and enrolling that macOS device, you will need to have access to a Fleet server (see [Deploying Fleet on Render](https://fleetdm.com/deploy/deploying-fleet-on-render) for an example.)
1. Access to an existing Fleet server
2. The `fleetctl` command line tool
You will also need to install the `fleetctl` CLI tool if you don’t have it already. `fleetctl` can be installed via `npm` by running the command below:
If you don’t already have it, `fleetctl` can be installed via npm by running the following command:
```
npm i -g fleetctl
articles/how-to-install-osquery-and-enroll-windows-devices-into-fleet.md
+7 -5
View File
@@ -1,14 +1,16 @@
# How to install osquery and enroll Windows devices into Fleet
The easiest way to install osquery and enroll Windows devices into your Fleet instance is to use the Fleet osquery installer.
Alternatively, you can run a preview environment of Fleet locally (which automatically adds your device to the locally running Fleet server). Check out the [Getting Started](https://fleetdm.com/get-started) guide for instructions on setting that up.
Here, we will cover enrolling Windows devices to an existing Fleet server. If you don’t have a Fleet
server configured already, check out [Deploying Fleet on Render](https://fleetdm.com/deploy/deploying-fleet-on-render). If you’re still getting to know
Fleet
and would like to skip the server setup process and try Fleet, you can [try Fleet in a temporary cloud instance](https://fleetdm.com/try-fleet/register).
## Prerequisites
Before installing osquery on Windows and enrolling that Windows device, you will need access to a Fleet server (see [Deploying Fleet on Render](https://fleetdm.com/deploy/deploying-fleet-on-render) for an example.)
1. Access to an existing Fleet server
2. The `fleetctl` command line tool
If you don’t already have it, you will also need to install the `fleetctl` CLI tool. `fleetctl` can be installed via `npm` by running the following command:
If you don’t already have it, `fleetctl` can be installed via npm by running the following command:
```
npm i -g fleetctl
articles/osquery-a-tool-to-easily-ask-questions-about-operating-systems.md
+1 -1
View File
@@ -57,7 +57,7 @@ To deploy osquery at scale across your organization’s devices, an osquery mana
![A screenshot of the Fleet UI](../website/assets/images/articles/osquery-a-tool-to-easily-ask-questions-about-operating-systems-1-800x450@2x.png)
Ready to give Fleet a try? Head over to our [get started page](https://fleetdm.com/get-started), and you can be up and running with a sandbox environment in less than 5 minutes. Alternatively, check out the [docs](https://fleetdm.com/docs) to learn how to deploy Fleet across your organization.
Ready to give Fleet a try? Head over to our [get started page](https://fleetdm.com/try-fleet/register), and you can be up and running with a sandbox environment in less than 5 minutes. Or you can check out the [docs](https://fleetdm.com/docs) to learn how to deploy Fleet across your organization.
<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="dominuskelvin">
docs/01-Using-Fleet/standard-query-library/standard-query-library.yml
+11
View File
@@ -474,6 +474,17 @@ spec:
contributors: DominusKelvin
---
apiVersion: v1
kind: query
spec:
name: Get operating system information
platforms: macOS, Windows, Linux
description: Returns the operating system name and version on the device.
query: SELECT name, version FROM os_version;
purpose: Informational
tags: inventory, built-in
contributors: noahtalerman
---
apiVersion: v1
kind: policy
spec:
name: Gatekeeper enabled (macOS)
docs/Contributing/FAQ.md
+31
View File
@@ -5,6 +5,8 @@
- [`undefined: Asset`](#undefined-asset)
- [How do I connect to the MailHog simulated mail server?](#how-do-i-connect-to-the-mailhog-simulated-mail-server)
- [Adding hosts for testing](#adding-hosts-for-testing)
- [Why am I getting an error about self-signed certificates when running `fleetctl preview`?](#why-am-i-getting-an-error-about-self-signed-certificates-when-running-fleetctl-preview)
- [Will updating fleetctl lead to loss of data in fleetctl preview?](will-updating-fleetctl-lead-to-loss-of-data-in-fleetctl-preview?)
## Enrolling in multiple Fleet servers
@@ -41,3 +43,32 @@ To start osquery, first retrieve the "Enroll secret" from Fleet (by clicking the
cd tools/osquery
ENROLL_SECRET=<copy from fleet> docker-compose up
```
## Why am I getting an error about self-signed certificates when running `fleetctl preview`?
If you are trying to run `fleetctl preview` and seeing errors about self-signed certificates, the
most likely culprit is that you're behind a corporate proxy server and need to [add the proxy
settings to Docker](https://docs.docker.com/network/proxy/) so that the container created by
`fleetctl preview` is able to connect properly.
## Will updating fleetctl lead to loss of data in fleetctl preview?
No, you won't experience data loss when you update fleetctl. Note that you can run `fleetctl preview --tag v#.#.#` if you want to run Preview on a previous version. Just replace # with the version numbers of interest.
## Can I disable usage statistics via the config file or a CLI flag?
Apart from an admin [disabling usage](https://fleetdm.com/docs/using-fleet/usage-statistics#disable-usage-statistics) statistics on the Fleet UI, you can edit your `fleet.yml` config file to disable usage statistics. Look for the `server_settings` in your `fleet.yml` and set `enable_analytics: false`. Do note there is no CLI flag option to disable usage statistics at this time.
## Fleet preview fails with Invalid interpolation. What should I do?
If you tried running `fleetctl preview` and you get the following error:
```
fleetctl preview
Downloading dependencies into /root/.fleet/preview...
Pulling Docker dependencies...
Invalid interpolation format for "fleet01" option in service "services": "fleetdm/fleet:${FLEET_VERSION:-latest}"
Failed to run docker-compose
```
You are probably running an old version of Docker. You should download the installer for your platform from https://docs.docker.com/compose/install/
docs/Deploying/Configuration.md
+1 -1
View File
@@ -2527,7 +2527,7 @@ If not set then the Prometheus `/metrics` endpoint is disabled.
Configurations used to control how Fleet interacts with the (coming soon)
packaging server. These features are currently only intended to be used within
Fleet Sandbox, but this is subject to change.
Fleet sandbox, but this is subject to change.
##### packaging_global_enroll_secret
docs/Deploying/Introduction.md
+3 -3
View File
@@ -16,11 +16,11 @@ The `fleetctl` binary is the CLI interface which allows management of your deplo
Both binaries are available for download from our [repo](https://github.com/fleetdm/fleet/releases).
## Fleet vs Fleet Preview
## Fleet vs Fleet Sandbox
If you'd like to try Fleet on your laptop we recommend [Fleet Preview](https://fleetdm.com/get-started): a convenient Docker instance that includes all infrastructure dependencies, sample virtual hosts, and the option to enroll your laptop for testing included.
If you'd like to try Fleet on your laptop, we recommend [Fleet Sandbox](https://fleetdm.com/try-fleet/register).
If you want to enroll real hosts or deploy to a more scalable environment we recommend [deploying Fleet to a server](./Server-Installation.md).
If you want to enroll real hosts or deploy to a more scalable environment, we recommend [deploying Fleet to a server](./Server-Installation.md).
## Infrastructure dependencies
docs/Using-Fleet/Adding-hosts.md
+1 -1
View File
@@ -5,7 +5,7 @@
The recommended way to add your host to Fleet is with an osquery installer. Fleet provides the tools to generate an osquery installer with the `fleetctl package` command.
To use the `fleetctl package` command, you must first install the `fleetctl` command-line tool. Instructions for installing `fleetctl` can be found on [here](https://fleetdm.com/get-started)
To use the `fleetctl package` command, you must first install the `fleetctl` command-line tool. Instructions for installing `fleetctl` can be found [here](https://fleetdm.com/fleetctl-preview)
## Osquery installer
docs/Using-Fleet/FAQ.md
-30
View File
@@ -26,11 +26,9 @@
- [Can I hide known vulnerabilities that I feel are insignificant?](#can-i-hide-known-vulnerabilities-that-i-feel-are-insignificant)
- [Can I create reports based on historical data in Fleet?](#can-i-create-reports-based-on-historical-data-in-fleet)
- [Why can't I run queries with `fleetctl` using a new API-only user?](#why-cant-i-run-queries-with-fleetctl-using-a-new-api-only-user)
- [Why am I getting an error about self-signed certificates when running `fleetctl preview`?](#why-am-i-getting-an-error-about-self-signed-certificates-when-running-fleetctl-preview)
- [Can I audit actions taken in Fleet?](#can-i-audit-actions-taken-in-fleet)
- [How often is the software inventory updated?](#how-often-is-the-software-inventory-updated)
- [Can I group results from multiple hosts?](#can-i-group-results-from-multiple-hosts)
- [Will updating fleetctl lead to loss of data in fleetctl preview?](will-updating-fleetctl-lead-to-loss-of-data-in-fleetctl-preview?)
- [How do I downgrade from Fleet Premium to Fleet Free?](how-do-i-downgrade-from-fleet-premium-to-fleet-free)
## How can I switch to Fleet from Kolide Fleet?
@@ -170,23 +168,6 @@ The following are reasons why a host may not be updating a policy's response:
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:
* Try un-enrolling and re-enrolling the host. You can do this by uninstalling osquery on the host and then enrolling your device again using one of the [recommended methods](./Adding-hosts.md).
* Restart the `fleetctl preview` docker containers.
* Uninstall and reinstall Docker.
## Fleet preview fails with Invalid interpolation. What should I do?
If you tried running `fleetctl preview` and you get the following error:
```
fleetctl preview
Downloading dependencies into /root/.fleet/preview...
Pulling Docker dependencies...
Invalid interpolation format for "fleet01" option in service "services": "fleetdm/fleet:${FLEET_VERSION:-latest}"
Failed to run docker-compose
```
You are probably running an old version of Docker. You should download the installer for your platform from https://docs.docker.com/compose/install/
## How does Fleet deal with IP duplication?
@@ -252,10 +233,6 @@ The [Fleet UI](https://fleetdm.com/docs/using-fleet/fleet-ui) is built for human
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](https://github.com/fleetdm/fleet/blob/a1eba3d5b945cb3339004dd1181526c137dc901c/docs/Using-Fleet/fleetctl-CLI.md#reset-the-password).
## Why am I getting an error about self-signed certificates when running `fleetctl preview`?
If you are trying to run `fleetctl preview` and seeing errors about self-signed certificates, the most likely culprit is that you're behind a corporate proxy server and need to [add the proxy settings to Docker](https://docs.docker.com/network/proxy/) so that the container created by `fleetctl preview` is able to connect properly.
## Can I audit actions taken in Fleet?
The [REST API `activities` endpoint](./REST-API.md#activities) provides a full breakdown of actions taken on packs, queries, policies, and teams (Available in Fleet Premium) through the UI, the REST API, or `fleetctl`.
@@ -281,13 +258,6 @@ $ fleetctl get hosts --json | jq '.spec .os_version' | sort | uniq -c
6 "macOS 12.3.1"
```
## Will updating fleetctl lead to loss of data in fleetctl preview?
No, you won't experience data loss when you update fleetctl. Note that you can run `fleetctl preview --tag v#.#.#` if you want to run Preview on a previous version. Just replace # with the version numbers of interest.
## Can I disable usage statistics via the config file or a CLI flag?
Apart from an admin [disabling usage](https://fleetdm.com/docs/using-fleet/usage-statistics#disable-usage-statistics) statistics on the Fleet UI, you can edit your `fleet.yml` config file to disable usage statistics. Look for the `server_settings` in your `fleet.yml` and set `enable_analytics: false`. Do note there is no CLI flag option to disable usage statistics at this time.
## How do I downgrade from Fleet Premium to Fleet Free?
If you'd like to renew your Fleet Premium license key, please contact us [here](https://fleetdm.com/company/contact).
docs/Using-Fleet/Learn-how-to-use-Fleet.md
+27 -21
View File
@@ -1,41 +1,47 @@
# Learn how to use Fleet
> This guide assumes that you have a preview environment of Fleet up and running. If you haven't already done so, check out our [Get started](https://fleetdm.com/get-started) guide for instructions on how to start a preview environment of Fleet.
- [How to add your device to Fleet](#how-to-add-your-device-to-fleet)
- [How to ask questions about your device](#how-to-ask-questions-about-your-device)
### Overview
In this guide, we'll cover the following concepts:
- How to add your device to Fleet
- How to ask questions about your device
- [Where to see your device in Fleet](#where-to-see-your-device-in-fleet)
- [How to ask questions about your device](#how-to-ask-questions-about-your-devices)
You can also follow along with our video guide on previewing Fleet and osquery locally:
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/nE3npSKP0Ek" allowfullscreen></iframe>
</div>
### Where to see your devices in Fleet
### How to add your device to Fleet
Once you log into Fleet, you are presented with the **Home** page.
On this page you'll see that your own device has been added to Fleet.
To add your device:
>In Fleet, devices are referred to as "hosts."
1. Select **Add hosts**. In Fleet, devices are referred to as "hosts."
2. Select your device's platform.
3. Select **Download** to download your Fleet osquery installer. The download may take several seconds.
4. Open the Fleet osquery installer and follow the installation steps.
> It may take several seconds for Fleet osquery to send your device's data to Fleet.
In the background, Fleet ran several checks to assess the security hygiene of your device.
>In Fleet, these checks are referred to as "policies."
> In Fleet, these checks are referred to as "policies."
### How to ask questions about your devices
### How to ask questions about your device
With osquery and Fleet, you can ask a multitude of questions to help you manage, monitor, and identify threats on your devices, but if you are just starting out, and unsure of what to ask, Fleet comes baked in with a [query library](https://fleetdm.com/queries) of common questions.
With Fleet, you can ask a multitude of questions to help you manage, monitor, and identify threats on your devices, but if you are just starting out, and unsure of what to ask, Fleet comes baked in with a [query library](https://fleetdm.com/queries) of common questions.
So, let's start by asking the following question about your device:
* What is the operating system installed on my device and what is its version?
* What operating system is installed on my device and what is its version?
This question can easily be answered, by running this simple query: "Get the version of the resident operating system."
This question can easily be answered by running this simple query: "Get operating system information."
On the **Queries** page, enter the query name, "Get the version of the resident operating system," in the search box, and select it to enter the **query console**. Then from the **query console**, hit "Run query", and from the "Select targets" page, select "All hosts," to run this query against all hosts enrolled in your Fleet. Then hit the "Run" button to execute the query.
To run this query on your device:
1. Select **Queries** in the top navigation.
2. Enter "Get operating system information" in the search bar.
3. Select **Get operating system information** to enter the **query console**.
4. Select **Run query**, then select **All hosts** (your device may be the only host added to Fleet), and finally select **Run** to execute the query.
The query may take several seconds to complete, because Fleet has to wait for the osquery agents to respond with results.
@@ -43,8 +49,8 @@ The query may take several seconds to complete, because Fleet has to wait for th
When the query has finished, you should see several columns in the "Results" table:
- The "name" column answers: which operating system is installed on my device?
- The "name" column answers: "What operating system is installed on my device?"
- The "version" column answers: which version of the installed operating system is my device running?"
- The "version" column answers: "What version of the installed operating system is on my device?"
<meta name="pageOrderInSection" value="100">
handbook/product/README.md
+1 -1
View File
@@ -244,7 +244,7 @@ For all following flows, please refer to the [permissions documentation](https:/
#### Set up flow
Successfully set up `fleetctl preview` using the preview steps outlined [here](https://fleetdm.com/get-started)
Successfully set up `fleetctl preview` using the preview steps outlined [here](https://fleetdm.com/fleetctl-preview)
#### Log in and log out flow