diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d9708c738f..47b21c0d92 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -3,7 +3,7 @@ If some of the following don't apply, delete the relevant line. - [ ] Changes file added (for user-visible changes) -- [ ] Documented any API changes (docs/01-Using-Fleet/03-REST-API.md) +- [ ] Documented any API changes (docs/Using-Fleet/REST-API.md) - [ ] Documented any permissions changes - [ ] Added/updated tests - [ ] Manual QA for all new/changed functionality diff --git a/CHANGELOG.md b/CHANGELOG.md index bc26539682..d3ecc4ff91 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -357,7 +357,7 @@ Fleet server in non-debug mode. * Running an "Excessive" query, even infrequently, can have a significant impact on your host’s performance. -* Add the ability to see a list of hosts that have a specific software version installed by selecting a software version on a specific host's **Host details** page. Software inventory is currently under a feature flag. To enable this feature flag, check out the [feature flag documentation](./docs/02-Deploying/03-Configuration.md#feature-flags). +* Add the ability to see a list of hosts that have a specific software version installed by selecting a software version on a specific host's **Host details** page. Software inventory is currently under a feature flag. To enable this feature flag, check out the [feature flag documentation](https://fleetdm.com/docs/deploying/configuration#feature-flags). * Add the ability to see all vulnerable software detected across all your hosts with the `GET /api/v1/fleet/software` API route. Documentation for this new API route can be found [here on fleetdm.com/docs](https://fleetdm.com/docs/using-fleet/rest-api#software). @@ -616,7 +616,7 @@ Fleet server in non-debug mode. * Add ability to create a Team schedule in Fleet. The Schedule feature was released in Fleet 4.1.0. For more information on the new Schedule feature, check out the [Fleet 4.1.0 release blog post](https://blog.fleetdm.com/fleet-4-1-0-57dfa25e89c1). *Available for Fleet Basic customers*. -* Add Beta Vulnerable software feature which surfaces vulnerable software on the **Host details** page and the `GET /api/v1/fleet/hosts/{id}` API route. For information on how to configure the Vulnerable software feature and how exactly Fleet processes vulnerabilities, check out the [Vulnerability processing documentation](https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/13-Vulnerability-Processing.md#vulnerability-processing). +* Add Beta Vulnerable software feature which surfaces vulnerable software on the **Host details** page and the `GET /api/v1/fleet/hosts/{id}` API route. For information on how to configure the Vulnerable software feature and how exactly Fleet processes vulnerabilities, check out the [Vulnerability processing documentation](https://fleetdm.com/docs/using-fleet/vulnerability-processing#vulnerability-processing). * Add ability to see which logging destination is configured for Fleet in the Fleet UI. To see this information, head to the **Schedule** page and then select "Schedule a query." Configured logging destination information is also available in the `GET api/v1/fleet/config` API route. @@ -626,9 +626,9 @@ Fleet server in non-debug mode. * Add ability to modify scheduled queries in your Schedule in Fleet. The Schedule feature was released in Fleet 4.1.0. For more information on the new Schedule feature, check out the [Fleet 4.1.0 release blog post](https://blog.fleetdm.com/fleet-4-1-0-57dfa25e89c1). -* Add ability to disable the Users feature in Fleet by setting the new `enable_host_users` key to `true` in the `config` yaml, configuration file. For documentation on using configuration files in yaml syntax, check out the [Using yaml files in Fleet](https://github.com/fleetdm/fleet/tree/main/docs/01-Using-Fleet/configuration-files#using-yaml-files-in-fleet) documentation. +* Add ability to disable the Users feature in Fleet by setting the new `enable_host_users` key to `true` in the `config` yaml, configuration file. For documentation on using configuration files in yaml syntax, check out the [Using yaml files in Fleet](https://fleetdm.com/docs/using-fleet/configuration-files#using-yaml-files-in-fleet) documentation. -* Improve performance of the Software inventory feature. Software inventory is currently under a feature flag. To enable this feature flag, check out the [feature flag documentation](./docs/02-Deploying/03-Configuration.md#feature-flags). +* Improve performance of the Software inventory feature. Software inventory is currently under a feature flag. To enable this feature flag, check out the [feature flag documentation](https://fleetdm.com/docs/deploying/configuration#feature-flags). * Improve performance of inserting `pack_stats` in the database. The `pack_stats` information is used to display "Frequency" and "Last run" information for a specific host's scheduled queries. You can find this information on the **Host details** page. @@ -807,9 +807,9 @@ There are currently no known issues in this release. However, we recommend only The primary additions in Fleet 4.0.0 are the new Role-based access control (RBAC) and Teams features. -RBAC adds the ability to define a user's access to information and features in Fleet. This way, more individuals in an organization can utilize Fleet with appropriate levels of access. Check out the [permissions documentation](https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/09-Permissions.md) for a breakdown of the new user roles and their respective capabilities. +RBAC adds the ability to define a user's access to information and features in Fleet. This way, more individuals in an organization can utilize Fleet with appropriate levels of access. Check out the [permissions documentation](https://fleetdm.com/docs/using-fleet/permissions) for a breakdown of the new user roles and their respective capabilities. -Teams adds the ability to separate hosts into exclusive groups. This way, users can easily observe and apply operations to consistent groups of hosts. Read more about the Teams feature in [the documentation here](https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/10-Teams.md). +Teams adds the ability to separate hosts into exclusive groups. This way, users can easily observe and apply operations to consistent groups of hosts. Read more about the Teams feature in [the documentation here](https://fleetdm.com/docs/using-fleet/teams). There are several known issues that will be fixed for the stable release of Fleet 4.0.0. Therefore, we recommend only upgrading to Fleet 4.0.0 RC1 for testing purposes. Please file a GitHub issue for any issues discovered when testing Fleet 4.0.0! @@ -877,7 +877,7 @@ Fleet 4.0.0 is a major release and introduces several breaking changes and datab * Improve Fleet performance by batch updating host seen time instead of updating synchronously. This improvement reduces MySQL CPU usage by ~33% with 4,000 simulated hosts and MySQL running in Docker. -* Add support for software inventory, introducing a list of installed software items on each host's respective _Host details_ page. This feature is flagged off by default (for now). Check out [the feature flag documentation for instructions on how to turn this feature on](./docs/02-Deploying/03-Configuration.md#software-inventory). +* Add support for software inventory, introducing a list of installed software items on each host's respective _Host details_ page. This feature is flagged off by default (for now). Check out [the feature flag documentation for instructions on how to turn this feature on](https://fleetdm.com/docs/deploying/configuration#software-inventory). * Add Windows support for `fleetctl` agent autoupdates. The `fleetctl updates` command provides the ability to self-manage an agent update server. Available for Fleet Basic customers. @@ -1345,7 +1345,7 @@ to 2.0.0. ## Kolide Fleet 2.0.0 (currently preparing for release) -The primary new addition in Fleet 2 is the new `fleetctl` CLI and file-format, which dramatically increases the flexibility and control that administrators have over their osquery deployment. The CLI and the file format are documented [in the Fleet documentation](https://github.com/fleetdm/fleet/blob/main/docs/01-Using-Fleet/02-fleetctl-CLI.md). +The primary new addition in Fleet 2 is the new `fleetctl` CLI and file-format, which dramatically increases the flexibility and control that administrators have over their osquery deployment. The CLI and the file format are documented [in the Fleet documentation](https://fleetdm.com/docs/using-fleet/fleetctl-cli). ### New Features diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61a98090c7..03a5af4768 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,7 +46,7 @@ Due to the structure of the Fleet documentation and GitHub's unique markdown fil When including a link to a different file in the Fleet documentation please use relative links when possible. -For example, let's say you're working on changes in the Contribution docs and you'd like to add a link to the REST API docs. The relative link would look something like `../01-Using-Fleet/03-REST-API.md`. +For example, let's say you're working on changes in the Contribution docs and you'd like to add a link to the REST API docs. The relative link would look something like `../Using-Fleet/REST-API.md`. #### Special characters in anchor links diff --git a/README.md b/README.md index 8f4889da8f..3498ef7f08 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ The Fleet UI is now available at http://localhost:1337. #### Now what? -Check out the [Ask questions about your devices tutorial](./docs/01-Using-Fleet/00-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 [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. ## 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). diff --git a/cypress/README.md b/cypress/README.md index ae6996780a..c3bc299a96 100644 --- a/cypress/README.md +++ b/cypress/README.md @@ -1,6 +1,6 @@ # Cypress Testing -Cypress tests are designed solely for end-to-end testing. If this is your first time developing or running end-to-end tests, [Fleet testing documentation](../docs/03-Contributing/02-Testing.md) includes git instructions for test preparation and running tests. +Cypress tests are designed solely for end-to-end testing. If this is your first time developing or running end-to-end tests, [Fleet testing documentation](../docs/Contributing/Testing.md) includes git instructions for test preparation and running tests. ## Fleet Cypress directories @@ -37,6 +37,6 @@ As much as possible, assert that the code is only selecting 1 item or that the f ## Resources -- [Fleet testing documentation](../docs/03-Contributing/02-Testing.md) +- [Fleet testing documentation](../docs/Contributing/Testing.md) - [Cypress documentation](https://docs.cypress.io/api/table-of-contents) - [React testing-library query documentation](https://testing-library.com/docs/queries/about/) diff --git a/docs/01-Using-Fleet/standard-query-library/README.md b/docs/01-Using-Fleet/standard-query-library/README.md index 2fd6495ad7..e4de589c7d 100644 --- a/docs/01-Using-Fleet/standard-query-library/README.md +++ b/docs/01-Using-Fleet/standard-query-library/README.md @@ -35,7 +35,7 @@ Want to add your own query? 3. If you want to contribute multiple queries, please open one pull request that includes all your queries. For instructions on submitting pull requests to Fleet check out [the Committing Changes -section](../../03-Contributing/04-Committing-Changes.md#committing-changes) in the Contributors +section](../../Contributing/Committing-Changes.md#committing-changes) in the Contributors documentation. diff --git a/docs/03-Contributing/08-API-Versioning.md b/docs/Contributing/API-Versioning.md similarity index 98% rename from docs/03-Contributing/08-API-Versioning.md rename to docs/Contributing/API-Versioning.md index f8fe583475..4eb1a19045 100644 --- a/docs/03-Contributing/08-API-Versioning.md +++ b/docs/Contributing/API-Versioning.md @@ -102,3 +102,5 @@ This will mean that the following are the only valid paths after this point: ``` And the code doesn't have to specify `.StartingAtVersion("2021-12")` anymore. + + diff --git a/docs/03-Contributing/07-API-for-contributors.md b/docs/Contributing/API-for-contributors.md similarity index 99% rename from docs/03-Contributing/07-API-for-contributors.md rename to docs/Contributing/API-for-contributors.md index 0004ef9442..75d9a0144c 100644 --- a/docs/03-Contributing/07-API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -2,7 +2,7 @@ This document includes the Fleet API routes that are helpful when developing or contributing to Fleet. -Unlike the [Fleet REST API documentation](../01-Using-Fleet/03-REST-API.md), the API routes in this document are only intended for use by the Fleet UI and fleetctl clients. +Unlike the [Fleet REST API documentation](../Using-Fleet/REST-API.md), the API routes in this document are only intended for use by the Fleet UI and fleetctl clients. - [Get queries spec](#get-queries-spec) - [Get query spec](#get-query-spec) @@ -1275,3 +1275,5 @@ NOTE: when updating a policy, team and platform will be ignored. ##### Default response `Status: 200` + + diff --git a/docs/03-Contributing/01-Building-Fleet.md b/docs/Contributing/Building-Fleet.md similarity index 99% rename from docs/03-Contributing/01-Building-Fleet.md rename to docs/Contributing/Building-Fleet.md index 27053600f3..f458674eb8 100644 --- a/docs/03-Contributing/01-Building-Fleet.md +++ b/docs/Contributing/Building-Fleet.md @@ -174,3 +174,5 @@ dlv debug --build-flags '-tags=full' ./cmd/fleet -- serve --dev ``` It is important to pass the `-tags=full` build flag, otherwise the server will not have access to the asset files. + + \ No newline at end of file diff --git a/docs/03-Contributing/04-Committing-Changes.md b/docs/Contributing/Committing-Changes.md similarity index 98% rename from docs/03-Contributing/04-Committing-Changes.md rename to docs/Contributing/Committing-Changes.md index 509d2d8e79..9ece85ee33 100644 --- a/docs/03-Contributing/04-Committing-Changes.md +++ b/docs/Contributing/Committing-Changes.md @@ -20,7 +20,7 @@ Fleet Device Management team members may not copy queries from external sources Each developer (internal or external) creates a fork of the Fleet repository, committing changes to a branch within their fork. Changes are submitted by PR to be merged into Fleet. -GitHub Actions automatically runs testers and linters on each PR. Please ensure that these checks pass. Checks can be run locally as described in [02-Testing.md](./02-Testing.md). +GitHub Actions automatically runs testers and linters on each PR. Please ensure that these checks pass. Checks can be run locally as described in [Testing.md](./Testing.md). For features that are still in-progress, the Pull Request can be marked as a "Draft". This helps make it clear which PRs are ready for review and merge. @@ -100,3 +100,5 @@ GitHub will automatically generate a commit title and description based on the c Keep in mind that the commit title and description are what developers see when running `git log` locally. Try to make this information helpful! Keeping to around 80 character line lengths helps with rendering when folks have narrow, tiled terminal windows. + + \ No newline at end of file diff --git a/docs/03-Contributing/FAQ.md b/docs/Contributing/FAQ.md similarity index 95% rename from docs/03-Contributing/FAQ.md rename to docs/Contributing/FAQ.md index 2f8f252fe7..01e9b009c7 100644 --- a/docs/03-Contributing/FAQ.md +++ b/docs/Contributing/FAQ.md @@ -30,7 +30,7 @@ server/fleet/emails.go:90:23: undefined: Asset make: *** [fleet] Error 2 ``` -If you get an `undefined: Asset` error it is likely because you did not run `make generate` before `make build`. See [Building Fleet](./01-Building-Fleet.md) for additional documentation on compiling the `fleet` binary. +If you get an `undefined: Asset` error it is likely because you did not run `make generate` before `make build`. See [Building Fleet](./Building-Fleet.md) for additional documentation on compiling the `fleet` binary. ## Adding hosts for testing diff --git a/docs/03-Contributing/03-Migrations.md b/docs/Contributing/Migrations.md similarity index 98% rename from docs/03-Contributing/03-Migrations.md rename to docs/Contributing/Migrations.md index 68208913cb..2523754e9f 100644 --- a/docs/03-Contributing/03-Migrations.md +++ b/docs/Contributing/Migrations.md @@ -45,4 +45,4 @@ Move the migration file from [server/datastore/mysql/migrations/tables/](../../s Proceed as for table migrations, editing and running the newly created migration file. - + \ No newline at end of file diff --git a/docs/03-Contributing/README.md b/docs/Contributing/README.md similarity index 67% rename from docs/03-Contributing/README.md rename to docs/Contributing/README.md index c1d34962ba..b8184d742a 100644 --- a/docs/03-Contributing/README.md +++ b/docs/Contributing/README.md @@ -1,24 +1,24 @@ # Contribution -### [Building Fleet](./01-Building-Fleet.md) +### [Building Fleet](./Building-Fleet.md) Provides documentation about building the code, development infrastructure, and database migrations -### [Testing](./02-Testing.md) +### [Testing](./Testing.md) Includes documentation about Fleet's full test suite and integration tests -### [Migrations](./03-Migrations.md) +### [Migrations](./Migrations.md) Information about creating and updating database migrations -### [Committing Changes](./04-Committing-Changes.md) +### [Committing Changes](./Committing-Changes.md) Contains information about how to merge changes into the codebase -### [Releasing Fleet](./05-Releasing-Fleet.md) +### [Releasing Fleet](./Releasing-Fleet.md) Provides a guide for Fleet's release process -### [Seeding Data](./06-Seeding-Data.md) +### [Seeding Data](./Seeding-Data.md) Provides a guide for adding fake data to your development instance -### [API for contributors](./07-API-for-contributors.md) +### [API for contributors](./API-for-contributors.md) Provides documentation for Fleet API routes that are helpful when developing or contributing to Fleet ### [FAQ](./FAQ.md) diff --git a/docs/03-Contributing/05-Releasing-Fleet.md b/docs/Contributing/Releasing-Fleet.md similarity index 99% rename from docs/03-Contributing/05-Releasing-Fleet.md rename to docs/Contributing/Releasing-Fleet.md index 5afa86e1d1..ae34b35ce9 100644 --- a/docs/03-Contributing/05-Releasing-Fleet.md +++ b/docs/Contributing/Releasing-Fleet.md @@ -144,3 +144,5 @@ must be created and relevant changes cherry-picked onto that branch: migrations are run in the appropriate order. TODO [#2850](https://github.com/fleetdm/fleet/issues/2850): Improve docs/tooling for this. + + diff --git a/docs/03-Contributing/06-Seeding-Data.md b/docs/Contributing/Seeding-Data.md similarity index 97% rename from docs/03-Contributing/06-Seeding-Data.md rename to docs/Contributing/Seeding-Data.md index 0d46f80cee..25434a93eb 100644 --- a/docs/03-Contributing/06-Seeding-Data.md +++ b/docs/Contributing/Seeding-Data.md @@ -42,3 +42,5 @@ The `fleet/create_figma` script will generate an environment to reflect the mock ``` Each user generated by the script has their password set to `user123#`. + + diff --git a/docs/03-Contributing/02-Testing.md b/docs/Contributing/Testing.md similarity index 98% rename from docs/03-Contributing/02-Testing.md rename to docs/Contributing/Testing.md index a3ad8e5074..0166f177d1 100644 --- a/docs/03-Contributing/02-Testing.md +++ b/docs/Contributing/Testing.md @@ -7,7 +7,7 @@ - [Test hosts](#test-hosts) - [Email](#email) - [Database backup/restore](#database-backuprestore) -- [Seeding data](./06-Seeding-Data.md) +- [Seeding Data](./Seeding-Data.md) - [MySQL shell](#mysql-shell) - [Testing SSO](#testing-sso) @@ -154,7 +154,7 @@ E2E tests are constantly evolving and running them or examining CI results is th ### Preparation -Make sure dependencies are up to date and the [Fleet binaries are built locally](./01-Building-Fleet.md). +Make sure dependencies are up to date and the [Fleet binaries are built locally](./Building-Fleet.md). For Fleet Free tests: @@ -296,3 +296,5 @@ Password: user123# Use the Fleet UI to invite one of these users with the associated email. Be sure the "Enable single sign on" box is checked for that user. Now after accepting the invitation, you should be able to log in as that user by clicking "Sign On with SimpleSAML" on the login page. To add additional users, modify [tools/saml/users.php](https://github.com/fleetdm/fleet/tree/main/tools/saml/users.php) and restart the `simplesaml` container. + + \ No newline at end of file diff --git a/docs/02-Deploying/03-Configuration.md b/docs/Deploying/Configuration.md similarity index 99% rename from docs/02-Deploying/03-Configuration.md rename to docs/Deploying/Configuration.md index 52155f9d02..92ff796cd3 100644 --- a/docs/02-Deploying/03-Configuration.md +++ b/docs/Deploying/Configuration.md @@ -633,7 +633,7 @@ The address to serve the Fleet webserver. The TLS cert to use when terminating TLS. -See [TLS certificate considerations](./01-Introduction.md#tls-certificate) for more information about certificates and Fleet. +See [TLS certificate considerations](./Introduction.md#tls-certificate) for more information about certificates and Fleet. - Default value: `./tools/osquery/fleet.crt` - Environment variable: `FLEET_SERVER_CERT` @@ -929,7 +929,7 @@ Valid time units are `s`, `m`, `h`. ##### osquery_status_log_plugin -Which log output plugin should be used for osquery status logs received from clients. Check out the reference documentation for osquery logging options [here in the Fleet documentation](../01-Using-Fleet/05-Osquery-logs.md). +Which log output plugin should be used for osquery status logs received from clients. Check out the reference documentation for osquery logging options [here in the Fleet documentation](../Using-Fleet/Osquery-logs.md). Options are `filesystem`, `firehose`, `kinesis`, `lambda`, `pubsub`, `kafkarest`, and `stdout`. @@ -945,7 +945,7 @@ Options are `filesystem`, `firehose`, `kinesis`, `lambda`, `pubsub`, `kafkarest` ##### osquery_result_log_plugin -Which log output plugin should be used for osquery result logs received from clients. Check out the reference documentation for osquery logging options [here in the Fleet documentation](../01-Using-Fleet/05-Osquery-logs.md). +Which log output plugin should be used for osquery result logs received from clients. Check out the reference documentation for osquery logging options [here in the Fleet documentation](../Using-Fleet/Osquery-logs.md). Options are `filesystem`, `firehose`, `kinesis`, `lambda`, `pubsub`, `kafkarest`, and `stdout`. @@ -2144,3 +2144,5 @@ If set then `fleet serve` will capture errors and panics and push them to Sentry sentry: dsn: "https://somedsnprovidedby.sentry.com/" ``` + + \ No newline at end of file diff --git a/docs/02-Deploying/FAQ.md b/docs/Deploying/FAQ.md similarity index 94% rename from docs/02-Deploying/FAQ.md rename to docs/Deploying/FAQ.md index e875fe002c..8433aa12c2 100644 --- a/docs/02-Deploying/FAQ.md +++ b/docs/Deploying/FAQ.md @@ -33,7 +33,7 @@ Yes. Fleet scales horizontally out of the box as long as all of the Fleet server Note that osquery logs will be distributed across the Fleet servers. -Read the [performance documentation](../01-Using-Fleet/06-Monitoring-Fleet.md#fleet-server-performance) for more. +Read the [performance documentation](../Using-Fleet/Monitoring-Fleet.md#fleet-server-performance) for more. ## Why aren't my osquery agents connecting to Fleet? @@ -91,15 +91,15 @@ These configurations cannot be managed centrally from Fleet. ## What do I do about "too many open files" errors? -This error usually indicates that the Fleet server has run out of file descriptors. Fix this by increasing the `ulimit` on the Fleet process. See the `LimitNOFILE` setting in the [example systemd unit file](./03-Configuration.md#runing-with-systemd) for an example of how to do this with systemd. +This error usually indicates that the Fleet server has run out of file descriptors. Fix this by increasing the `ulimit` on the Fleet process. See the `LimitNOFILE` setting in the [example systemd unit file](./Configuration.md#runing-with-systemd) for an example of how to do this with systemd. -Some deployments may benefit by setting the [`--server_keepalive`](./03-Configuration.md#server-keepalive) flag to false. +Some deployments may benefit by setting the [`--server_keepalive`](./Configuration.md#server-keepalive) flag to false. This was also seen as a symptom of a different issue: if you're deploying on AWS on T type instances, there are different scenarios where the activity can increase and the instances will burst. If they run out of credits, then they'll stop processing leaving the file descriptors open. ## I upgraded my database, but Fleet is still running slowly. What could be going on? -This could be caused by a mismatched connection limit between the Fleet server and the MySQL server that prevents Fleet from fully utilizing the database. First [determine how many open connections your MySQL server supports](https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html). Now set the [`--mysql_max_open_conns`](./03-Configuration.md#mysql-max-open-conns) and [`--mysql_max_idle_conns`](./03-Configuration.md#mysql-max-idle-conns) flags appropriately. +This could be caused by a mismatched connection limit between the Fleet server and the MySQL server that prevents Fleet from fully utilizing the database. First [determine how many open connections your MySQL server supports](https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html). Now set the [`--mysql_max_open_conns`](./Configuration.md#mysql-max-open-conns) and [`--mysql_max_idle_conns`](./Configuration.md#mysql-max-idle-conns) flags appropriately. ## Why am I receiving a database connection error when attempting to "prepare" the database? @@ -131,7 +131,7 @@ The user `fleet prepare db` (via environment variable `FLEET_MYSQL_USERNAME` or ## Does Fleet support MySQL replication? -You can deploy MySQL or Maria any way you want. We recommend using managed/hosted mysql so you don't have to think about it, but you can think about it more if you want. Read replicas are supported. You can read more about MySQL configuration [here](./03-Configuration.md#my-sql). +You can deploy MySQL or Maria any way you want. We recommend using managed/hosted mysql so you don't have to think about it, but you can think about it more if you want. Read replicas are supported. You can read more about MySQL configuration [here](./Configuration.md#my-sql). ## What is duplicate enrollment and how do I fix it? @@ -148,8 +148,7 @@ using `--osquery_host_identifier=uuid` will not resolve the duplicate enrollment the problem can be resolved by setting `--osquery_host_identifier=instance` (which will use the osquery generated UUID), and then delete the associated host in the Fleet UI. -Find more information about -[host identifiers here](./03-Configuration.md#osquery-host-identifier). +Find more information about [host identifiers here](./Configuration.md#osquery-host-identifier). ## How long are osquery enroll secrets valid? @@ -226,7 +225,7 @@ are managed in the team yaml. The `unknown column` error typically occurs when the database migrations haven't been run during the upgrade process. -Check out the [documentation on running database migrations](./06-Upgrading-Fleet.md#running-database-migrations) to resolve this issue. +Check out the [documentation on running database migrations](./Upgrading-Fleet.md#running-database-migrations) to resolve this issue. ## What API endpoints should I expose to the public internet? diff --git a/docs/02-Deploying/01-Introduction.md b/docs/Deploying/Introduction.md similarity index 91% rename from docs/02-Deploying/01-Introduction.md rename to docs/Deploying/Introduction.md index 548fa06f47..0c9f4e82d2 100644 --- a/docs/02-Deploying/01-Introduction.md +++ b/docs/Deploying/Introduction.md @@ -16,7 +16,7 @@ The Fleet application contains two single static binaries which provide web base The `fleet` binary contains: - The Fleet TLS web server (no external webserver is required but it supports a proxy if desired) - The Fleet web interface -- The Fleet application management [REST API](../01-Using-Fleet/03-REST-API.md) +- The Fleet application management [REST API](../Using-Fleet/REST-API.md) - The Fleet osquery API endpoints The `fleetctl` binary is the CLI interface which allows management of your deployment, scriptable live queries, and easy integration into your existing logging, alerting, reporting, and management infrastructure. @@ -27,7 +27,7 @@ Both binaries are available for download from our [repo](https://github.com/flee 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 want to enroll real hosts or deploy to a more scalable environment we recommend [deploying Fleet to a server](./02-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 @@ -35,7 +35,7 @@ Fleet currently has three infrastructure dependencies: MySQL, Redis, and a TLS c ### MySQL -Fleet uses MySQL extensively as its main database. Many cloud providers (such as [AWS](https://aws.amazon.com/rds/mysql/) and [GCP](https://cloud.google.com/sql/)) host reliable MySQL services which you may consider for this purpose. A well supported MySQL [Docker image](https://hub.docker.com/_/mysql/) also exists if you would rather run MySQL in a container. For more information on how to configure the `fleet` binary to use the correct MySQL instance, see the [Configuration](./03-Configuration.md) document. +Fleet uses MySQL extensively as its main database. Many cloud providers (such as [AWS](https://aws.amazon.com/rds/mysql/) and [GCP](https://cloud.google.com/sql/)) host reliable MySQL services which you may consider for this purpose. A well supported MySQL [Docker image](https://hub.docker.com/_/mysql/) also exists if you would rather run MySQL in a container. For more information on how to configure the `fleet` binary to use the correct MySQL instance, see the [Configuration](./Configuration.md) document. Fleet requires at least MySQL version 5.7. @@ -43,7 +43,7 @@ For host expiry configuration, the [event scheduler](https://dev.mysql.com/doc/r ### Redis -Fleet uses Redis to ingest and queue the results of distributed queries, cache data, etc. Many cloud providers (such as [AWS](https://aws.amazon.com/elasticache/) and [GCP](https://console.cloud.google.com/launcher/details/click-to-deploy-images/redis)) host reliable Redis services which you may consider for this purpose. A well supported Redis [Docker image](https://hub.docker.com/_/redis/) also exists if you would rather run Redis in a container. For more information on how to configure the `fleet` binary to use the correct Redis instance, see the [Configuration](./03-Configuration.md) document. +Fleet uses Redis to ingest and queue the results of distributed queries, cache data, etc. Many cloud providers (such as [AWS](https://aws.amazon.com/elasticache/) and [GCP](https://console.cloud.google.com/launcher/details/click-to-deploy-images/redis)) host reliable Redis services which you may consider for this purpose. A well supported Redis [Docker image](https://hub.docker.com/_/redis/) also exists if you would rather run Redis in a container. For more information on how to configure the `fleet` binary to use the correct Redis instance, see the [Configuration](./Configuration.md) document. ## TLS certificate @@ -52,3 +52,5 @@ In order for osqueryd clients to connect, the connection to Fleet must use TLS. - The CNAME or one of the Subject Alternate Names (SANs) on the certificate must match the hostname that osquery clients use to connect to the server/proxy. - If self-signed certificates are used, the full certificate chain must be provided to osquery via the `--tls_server_certs` flag. - If Fleet terminates TLS, consider using an ECDSA (rather than RSA) certificate, as RSA certificates have been associated with [performance problems in Fleet due to Go's standard library TLS implementation](https://github.com/fleetdm/fleet/issues/655). + + \ No newline at end of file diff --git a/docs/02-Deploying/05-Load-testing.md b/docs/Deploying/Load-testing.md similarity index 98% rename from docs/02-Deploying/05-Load-testing.md rename to docs/Deploying/Load-testing.md index a763aed8f7..098b6608cf 100644 --- a/docs/02-Deploying/05-Load-testing.md +++ b/docs/Deploying/Load-testing.md @@ -72,3 +72,5 @@ terraform apply \ ## Limitations The [osquery-perf](https://github.com/fleetdm/fleet/tree/main/cmd/osquery-perf) tool doesn't simulate all data that's included when a real device communicates to a Fleet instance. For example, system users and software inventory data are not yet simulated by osquery-perf. + + \ No newline at end of file diff --git a/docs/02-Deploying/README.md b/docs/Deploying/README.md similarity index 67% rename from docs/02-Deploying/README.md rename to docs/Deploying/README.md index 97ed3305ba..331cd27664 100644 --- a/docs/02-Deploying/README.md +++ b/docs/Deploying/README.md @@ -1,21 +1,21 @@ # Deployment -### [Introduction](./01-Introduction.md) +### [Introduction](./Introduction.md) Provides an introduction to Fleet and its requirements and dependencies. -### [Server Installation](./02-Server-Installation.md) +### [Server Installation](./Server-Installation.md) Includes deployment walkthroughs for Fleet on CentOS, Ubuntu, Docker, Kubernetes, and building from source. -### [Configuration](./03-Configuration.md) +### [Configuration](./Configuration.md) Includes resources for configuring the Fleet binary, managing osquery configurations, and running with systemd -### [Self-managed agent updates](./04-fleetctl-agent-updates.md) +### [Self-managed agent updates](./fleetctl-agent-updates.md) Information about running an update server with fleetctl. -### [Load Testing](./05-Load-testing.md) +### [Load Testing](./Load-testing.md) Information about running an update server with fleetctl. -### [Upgrading Fleet](./06-Upgrading-Fleet.md) +### [Upgrading Fleet](./Upgrading-Fleet.md) Includes a guide for how to update and run new versions of Fleet ### [FAQ](./FAQ.md) diff --git a/docs/02-Deploying/06-Reference-Architectures.md b/docs/Deploying/Reference-Architectures.md similarity index 99% rename from docs/02-Deploying/06-Reference-Architectures.md rename to docs/Deploying/Reference-Architectures.md index 916eb9040e..9065635fd5 100644 --- a/docs/02-Deploying/06-Reference-Architectures.md +++ b/docs/Deploying/Reference-Architectures.md @@ -300,3 +300,6 @@ services: run_command: fleet serve source_dir: / ``` + + + \ No newline at end of file diff --git a/docs/02-Deploying/02-Server-Installation.md b/docs/Deploying/Server-Installation.md similarity index 95% rename from docs/02-Deploying/02-Server-Installation.md rename to docs/Deploying/Server-Installation.md index 894a4dbd74..4aacecf289 100644 --- a/docs/02-Deploying/02-Server-Installation.md +++ b/docs/Deploying/Server-Installation.md @@ -29,7 +29,7 @@ - [Configure DNS](#configure-dns) - [Fleet on AWS ECS](#deploying-fleet-on-aws-ecs) - [Fleet using Docker](#fleet-on-docker) -- [Building Fleet from Source](../03-Contributing/01-Building-Fleet.md) +- [Building Fleet from Source](../Contributing/Building-Fleet.md) - [Community projects](#community-projects) ## Fleet on CentOS @@ -192,11 +192,11 @@ Now, if you go to [https://localhost:8080](https://localhost:8080) in your local ### Running Fleet with systemd -See [Running with systemd](./03-Configuration.md#running-with-systemd) for documentation on running fleet as a background process and managing the fleet server logs. +See [Running with systemd](./Configuration.md#running-with-systemd) for documentation on running fleet as a background process and managing the fleet server logs. ### Installing and running osquery -> Note that this whole process is outlined in more detail in the [Adding Hosts To Fleet](../01-Using-Fleet/04-Adding-hosts.md) document. The steps are repeated here for the sake of a continuous tutorial. +> Note that this whole process is outlined in more detail in the [Adding Hosts To Fleet](../Using-Fleet/Adding-hosts.md) document. The steps are repeated here for the sake of a continuous tutorial. To install osquery on CentOS, you can run the following: @@ -360,11 +360,11 @@ Now, if you go to [https://localhost:8080](https://localhost:8080) in your local ### Running Fleet with systemd -See [Running with systemd](./03-Configuration.md#running-with-systemd) for documentation on running fleet as a background process and managing the fleet server logs. +See [Running with systemd](./Configuration.md#running-with-systemd) for documentation on running fleet as a background process and managing the fleet server logs. ### Installing and running osquery -> Note that this whole process is outlined in more detail in the [Adding Hosts To Fleet](../01-Using-Fleet/04-Adding-hosts.md) document. The steps are repeated here for the sake of a continuous tutorial. +> Note that this whole process is outlined in more detail in the [Adding Hosts To Fleet](../Using-Fleet/Adding-hosts.md) document. The steps are repeated here for the sake of a continuous tutorial. To install osquery on Ubuntu, you can run the following: @@ -459,14 +459,14 @@ We will use this address when we configure the Kubernetes deployment and databas The last step is to run the Fleet database migrations on your new MySQL server. To do this, run the following: ``` -kubectl create -f ./docs/01-Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml +kubectl create -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml ``` In Kubernetes, you can only run a job once. If you'd like to run it again (i.e.: you'd like to run the migrations again using the same file), you must delete the job before re-creating it. To delete the job and re-run it, you can run the following commands: ``` -kubectl delete -f ./docs/01-Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml -kubectl create -f ./docs/01-Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml +kubectl delete -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml +kubectl create -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml ``` #### Redis @@ -526,7 +526,7 @@ kubectl create secret tls fleet-tls --key=./tls.key --cert=./tls.crt First we must deploy the instances of the Fleet webserver. The Fleet webserver is described using a Kubernetes deployment object. To create this deployment, run the following: ``` -kubectl apply -f ./docs/01-Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml +kubectl apply -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml ``` You should be able to get an instance of the webserver running via `kubectl get pods` and you should see the following logs: @@ -542,7 +542,7 @@ ts=2017-11-16T02:48:38.441148166Z transport=https address=0.0.0.0:443 msg=listen Now that the Fleet server is running on our cluster, we have to expose the Fleet webservers to the internet via a load balancer. To create a Kubernetes `Service` of type `LoadBalancer`, run the following: ``` -kubectl apply -f ./docs/01-Using-Fleet/configuration-files/kubernetes/fleet-service.yml +kubectl apply -f ./docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml ``` #### Configure DNS @@ -600,3 +600,5 @@ docker pull fleetdm/fleet Below are some projects created by Fleet community members. These projects provide additional solutions for deploying Fleet. Please submit a pull request if you'd like your project featured. - [CptOfEvilMinions/FleetDM-Automation](https://github.com/CptOfEvilMinions/FleetDM-Automation) - Ansible and Docker code to set up Fleet + + \ No newline at end of file diff --git a/docs/02-Deploying/06-Upgrading-Fleet.md b/docs/Deploying/Upgrading-Fleet.md similarity index 96% rename from docs/02-Deploying/06-Upgrading-Fleet.md rename to docs/Deploying/Upgrading-Fleet.md index d5970d30ba..0875e41540 100644 --- a/docs/02-Deploying/06-Upgrading-Fleet.md +++ b/docs/Deploying/Upgrading-Fleet.md @@ -1,6 +1,6 @@ # Upgrading Fleet -This guide explains how to upgrade your Fleet instance to the latest version in order to get the latest features and bug fixes. For initial installation instructions, see [Installing Fleet](./02-Server-Installation.md#installing-fleet). +This guide explains how to upgrade your Fleet instance to the latest version in order to get the latest features and bug fixes. For initial installation instructions, see [Installing Fleet](./Server-Installation.md#installing-fleet). There are three steps to perform a typical Fleet upgrade: @@ -56,3 +56,5 @@ Once Fleet has been replaced with the newest version and the database migrations ``` fleet serve ``` + + \ No newline at end of file diff --git a/docs/02-Deploying/04-fleetctl-agent-updates.md b/docs/Deploying/fleetctl-agent-updates.md similarity index 99% rename from docs/02-Deploying/04-fleetctl-agent-updates.md rename to docs/Deploying/fleetctl-agent-updates.md index 8bcfa038d3..1165d8eb9a 100644 --- a/docs/02-Deploying/04-fleetctl-agent-updates.md +++ b/docs/Deploying/fleetctl-agent-updates.md @@ -157,3 +157,5 @@ fleetctl updates rotate targets ``` After the key(s) have been rotated, publish the repository in the same fashion as any other update. + + \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 5e29c0c967..b5384433fc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ Welcome to the documentation for the Fleet osquery fleet manager. -### [Using Fleet](./01-Using-Fleet/README.md) +### [Using Fleet](./Using-Fleet/README.md) Resources for using the Fleet UI, fleetctl CLI, and Fleet REST API. -### [Deploying](./02-Deploying/README.md) +### [Deploying](./Deploying/README.md) Resources for installing Fleet's infrastructure dependencies, configuring Fleet, deploying osquery to hosts, and viewing example deployment scenarios. -### [Contributing](./03-Contributing/README.md) +### [Contributing](./Contributing/README.md) If you're interested in interacting with the Fleet source code, you'll find information on modifying and building the code here. --- diff --git a/docs/01-Using-Fleet/04-Adding-hosts.md b/docs/Using-Fleet/Adding-hosts.md similarity index 98% rename from docs/01-Using-Fleet/04-Adding-hosts.md rename to docs/Using-Fleet/Adding-hosts.md index 19d9d35414..3eac126db4 100644 --- a/docs/01-Using-Fleet/04-Adding-hosts.md +++ b/docs/Using-Fleet/Adding-hosts.md @@ -59,7 +59,7 @@ You can distribute your osquery installer and add all your hosts to Fleet using 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](../01-Using-Fleet/10-Teams.md#transfer-hosts-to-a-team). +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](../Using-Fleet/Teams.md#transfer-hosts-to-a-team). To generate an osquery installer for a team: @@ -201,7 +201,9 @@ time, [uninstall the existing osquery](https://blog.fleetdm.com/how-to-uninstall-osquery-f01cc49a37b9). If the existing enrolled hosts use `--host_identifier=uuid` (or the `uuid` setting for Fleet's -[osquery_host_identifier](../02-Deploying/03-Configuration.md#osquery-host-identifier)), the new +[osquery_host_identifier](../Deploying/Configuration.md#osquery-host-identifier)), the new installation should appear as the same host in the Fleet UI. If other settings are used, duplicate entries will appear in the Fleet UI. The older entries can be automatically cleaned up with the host expiration functionality configured in the application settings (UI or fleetctl). + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/14-Automations.md b/docs/Using-Fleet/Automations.md similarity index 96% rename from docs/01-Using-Fleet/14-Automations.md rename to docs/Using-Fleet/Automations.md index 741991707e..ae032f49a5 100644 --- a/docs/01-Using-Fleet/14-Automations.md +++ b/docs/Using-Fleet/Automations.md @@ -21,7 +21,7 @@ found on at least one host. Fleet sends these webhook requests once every hour. If two new vulnerabilities are detected within the hour, two -webhook requests are sent. This interval can be updated with the [`vulnerabilities_periodicity` configuration option](../02-Deploying/03-Configuration.md#periodicity). +webhook requests are sent. This interval can be updated with the [`vulnerabilities_periodicity` configuration option](../Deploying/Configuration.md#periodicity). Example webhook payload: @@ -131,3 +131,5 @@ POST https://server.com/example To enable and configure host status automations, navigate to **Settings > Organization settings > Host status webhook** in the Fleet UI. + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/FAQ.md b/docs/Using-Fleet/FAQ.md similarity index 86% rename from docs/01-Using-Fleet/FAQ.md rename to docs/Using-Fleet/FAQ.md index d512f5ac3b..e2fdd775be 100644 --- a/docs/01-Using-Fleet/FAQ.md +++ b/docs/Using-Fleet/FAQ.md @@ -25,7 +25,7 @@ The upgrade from kolide/fleet to fleetdm/fleet works the same as any minor versi Minor version upgrades in Kolide Fleet often included database migrations and the recommendation to back up the database before migrating. The same goes for the new Fleet. -To migrate from `kolide/fleet` to the new Fleet, please follow the steps outlined in the [Upgrading Fleet section](../02-Deploying/06-Upgrading-Fleet.md) of the documentation. +To migrate from `kolide/fleet` to the new Fleet, please follow the steps outlined in the [Upgrading Fleet section](../Deploying/Upgrading-Fleet.md) of the documentation. ## Has anyone stress tested Fleet? How many clients can the Fleet server handle? @@ -37,13 +37,13 @@ It’s standard deployment practice to have multiple Fleet servers behind a load 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 a target for queries or query packs. -Typically folks will use some other unique identifier to create labels that distinguish each type of device. As a workaround, [Fleet's manual labels](./02-fleetctl-CLI.md#host-labels) provide a way to create groups of hosts without a query. These manual labels can then be used as targets for queries or query packs. +Typically folks will use some other unique identifier to create labels that distinguish each type of device. As a workaround, [Fleet's manual labels](./fleetctl-CLI.md#host-labels) provide a way to create groups of hosts without a query. These manual labels can then be used as targets for queries or query packs. 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. ## How often do labels refresh? Is the refresh frequency configurable? -The update frequency for labels is configurable with the [—osquery_label_update_interval](../02-Deploying/03-Configuration.md#osquery-label-update-interval) flag (default 1 hour). +The update frequency for labels is configurable with the [—osquery_label_update_interval](../Deploying/Configuration.md#osquery-label-update-interval) flag (default 1 hour). ## How do I revoke the authorization tokens for a user? @@ -55,7 +55,7 @@ Fleet can live query the `osquery_schedule` table. Performing this live query al ## How do I monitor a Fleet server? -Fleet provides standard interfaces for monitoring and alerting. See the [Monitoring Fleet](./06-Monitoring-Fleet.md) documentation for details. +Fleet provides standard interfaces for monitoring and alerting. See the [Monitoring Fleet](./Monitoring-Fleet.md) documentation for details. ## Why is the “Add User” button disabled? @@ -80,7 +80,7 @@ Live query results (executed in the web UI or `fleetctl query`) are pushed direc ### Scheduled queries -Scheduled query results (queries that are scheduled to run in Packs) are typically sent to the Fleet server, and will be available on the filesystem of the server at the path configurable by [`--osquery_result_log_file`](../02-Deploying/03-Configuration.md#osquery-result-log-file). This defaults to `/tmp/osquery_result`. +Scheduled query results (queries that are scheduled to run in Packs) are typically sent to the Fleet server, and will be available on the filesystem of the server at the path configurable by [`--osquery_result_log_file`](../Deploying/Configuration.md#osquery-result-log-file). This defaults to `/tmp/osquery_result`. It is possible to configure osqueryd to log query results outside of Fleet. For results to go to Fleet, the `--logger_plugin` flag must be set to `tls`. @@ -88,7 +88,7 @@ It is possible to configure osqueryd to log query results outside of Fleet. For Folks typically use Fleet to ship logs to data aggregation systems like Splunk, the ELK stack, and Graylog. -The [logger configuration options](../02-Deploying/03-Configuration.md#osquery-status-log-plugin) allow you to select the log output plugin. Using the log outputs you can route the logs to your chosen aggregation system. +The [logger configuration options](../Deploying/Configuration.md#osquery-status-log-plugin) allow you to select the log output plugin. Using the log outputs you can route the logs to your chosen aggregation system. ### Troubleshooting @@ -98,7 +98,7 @@ Expecting results, but not seeing anything in the logs? - Check whether the query is scheduled in differential mode. If so, new results will only be logged when the result set changes. - Ensure that the query is scheduled to run on the intended platforms, and that the tables queried are supported by those platforms. - Use live query to `SELECT * FROM osquery_schedule` to check whether the query has been scheduled on the host. -- Look at the status logs provided by osquery. In a standard configuration these are available on the filesystem of the Fleet server at the path configurable by [`--filesystem_status_log_file`](../02-Deploying/03-Configuration.md#filesystem-status-log-file). This defaults to `/tmp/osquery_status`. The host will output a status log each time it executes the query. +- Look at the status logs provided by osquery. In a standard configuration these are available on the filesystem of the Fleet server at the path configurable by [`--filesystem_status_log_file`](../Deploying/Configuration.md#filesystem-status-log-file). This defaults to `/tmp/osquery_status`. The host will output a status log each time it executes the query. ## Why does the same query come back faster sometimes? @@ -119,17 +119,17 @@ Live query results are never logged to the filesystem of the Fleet server. See [ 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`](./03-REST-API.md#list-hosts) and the [`api/v1/fleet/hosts/{id}`](./03-REST-API.md#get-host) API endpoints. The `api/v1/fleet/hosts` [can even be configured to return additional host information](https://github.com/fleetdm/fleet/blob/9fb9da31f5462fa7dda4819a114bbdbc0252c347/docs/1-Using-Fleet/2-fleetctl-CLI.md#fleet-configuration-options). +However, the Fleet API exposes a significant amount of host information via the [`api/v1/fleet/hosts`](./REST-API.md#list-hosts) and the [`api/v1/fleet/hosts/{id}`](./REST-API.md#get-host) API endpoints. The `api/v1/fleet/hosts` [can even be configured to return additional host information](https://github.com/fleetdm/fleet/blob/9fb9da31f5462fa7dda4819a114bbdbc0252c347/docs/1-Using-Fleet/2-fleetctl-CLI.md#fleet-configuration-options). As an 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](./03-REST-API.md#list-hosts). +Each host’s OS version is available using the `api/v1/fleet/hosts` API endpoint. [Check out the API documentation for this endpoint](./REST-API.md#list-hosts). -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](../02-Deploying/03-Configuration.md#feature-flags). +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](../Deploying/Configuration.md#feature-flags). -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](./03-REST-API.md#get-host). +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](./REST-API.md#get-host). -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](./02-fleetctl-CLI.md#fleet-configuration-options). +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](./fleetctl-CLI.md#fleet-configuration-options). ## How do I automatically add hosts to packs when the hosts enroll to Fleet? @@ -137,11 +137,11 @@ You can accomplish this by adding specific labels as targets of your pack. First When your hosts enroll to Fleet, they will become a member of the label and, because the label is a target of your pack, these hosts will automatically become targets of the pack. -You can also do this by setting the `targets` field in the [YAML configuration file](./02-fleetctl-CLI.md#query-packs) that manages the packs that are added to your Fleet instance. +You can also do this by setting the `targets` field in the [YAML configuration file](./fleetctl-CLI.md#query-packs) that manages the packs that are added to your Fleet instance. ## How do I automatically assign a host to a team when it enrolls with Fleet? -[Team enroll secrets](./10-Teams.md#enroll-hosts-to-a-team) allow you to automatically assign a host to a team. +[Team enroll secrets](./Teams.md#enroll-hosts-to-a-team) allow you to automatically assign a host to a team. ## Why my host is not updating a policy's response. @@ -155,7 +155,7 @@ 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](./04-Adding-hosts.md). +* 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. @@ -176,7 +176,7 @@ You are probably running an old version of Docker. You should download the insta ## How does Fleet deal with IP duplication? -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](https://fleetdm.com/docs/using-fleet/teams) can be used to restrict queries to specific hosts. +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](./Teams.md) can be used to restrict queries to specific hosts. ## Can Orbit run alongside osquery? diff --git a/docs/01-Using-Fleet/01-Fleet-UI.md b/docs/Using-Fleet/Fleet-UI.md similarity index 96% rename from docs/01-Using-Fleet/01-Fleet-UI.md rename to docs/Using-Fleet/Fleet-UI.md index e2d8fd9b1b..fe04cd3426 100644 --- a/docs/01-Using-Fleet/01-Fleet-UI.md +++ b/docs/Using-Fleet/Fleet-UI.md @@ -27,7 +27,7 @@ To add queries to a pack, click on the "Add query +" link on the edit pack page. ![Schedule Query Modal](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/schedule-query-modal.png) -Once you've scheduled queries and curated your packs, you can read our guide to [Working With Osquery Logs](../01-Using-Fleet/05-Osquery-logs.md). +Once you've scheduled queries and curated your packs, you can read our guide to [Working With Osquery Logs](../Using-Fleet/Osquery-logs.md). ## Configuring agent options @@ -62,3 +62,5 @@ To configure team agent options, head to **Settings > Teams > `Team-name-here` > ![Team agent options](https://raw.githubusercontent.com/fleetdm/fleet/main/docs/images/team-agent-options.png) + + diff --git a/docs/01-Using-Fleet/00-Learn-how-to-use-Fleet.md b/docs/Using-Fleet/Learn-how-to-use-Fleet.md similarity index 98% rename from docs/01-Using-Fleet/00-Learn-how-to-use-Fleet.md rename to docs/Using-Fleet/Learn-how-to-use-Fleet.md index 9cd5acd7a2..27982fefd9 100644 --- a/docs/01-Using-Fleet/00-Learn-how-to-use-Fleet.md +++ b/docs/Using-Fleet/Learn-how-to-use-Fleet.md @@ -41,3 +41,4 @@ When the query has finished, you should see several columns in the "Results" tab - The "version" column answers: which version of the installed operating system is my device running?" + \ No newline at end of file diff --git a/docs/01-Using-Fleet/06-Monitoring-Fleet.md b/docs/Using-Fleet/Monitoring-Fleet.md similarity index 96% rename from docs/01-Using-Fleet/06-Monitoring-Fleet.md rename to docs/Using-Fleet/Monitoring-Fleet.md index cb152519ff..7539e4b790 100644 --- a/docs/01-Using-Fleet/06-Monitoring-Fleet.md +++ b/docs/Using-Fleet/Monitoring-Fleet.md @@ -66,7 +66,7 @@ Scaling Fleet horizontally is as simple as running more Fleet server processes c The Fleet/osquery system is resilient to loss of availability. Osquery agents will continue executing the existing configuration and buffering result logs during downtime due to lack of network connectivity, server maintenance, or any other reason. Buffering in osquery can be configured with the `--buffered_log_max` flag. -Note that short downtimes are expected during [Fleet server upgrades](../02-Deploying/06-Upgrading-Fleet.md) that require database migrations. +Note that short downtimes are expected during [Fleet server upgrades](../Deploying/Upgrading-Fleet.md) that require database migrations. ### Debugging performance issues @@ -80,7 +80,7 @@ For performance issues in the Fleet server process, please [file an issue](https ##### Generate debug archive (Fleet 3.4.0+) -Use the `fleetctl debug archive` command to generate an archive of Fleet's full suite of debug profiles. See the [fleetctl setup guide](./02-fleetctl-CLI.md)) for details on configuring `fleetctl`. +Use the `fleetctl debug archive` command to generate an archive of Fleet's full suite of debug profiles. See the [fleetctl setup guide](./fleetctl-CLI.md)) for details on configuring `fleetctl`. The generated `.tar.gz` archive will be available in the current directory. @@ -99,3 +99,5 @@ fleetctl debug archive --context server-a ##### Confidential information The `fleetctl debug archive` command retrieves information generated by Go's [`net/http/pprof`](https://golang.org/pkg/net/http/pprof/) package. In most scenarios this should not include sensitive information, however it does include command line arguments to the Fleet server. If the Fleet server receives sensitive credentials via CLI argument (not environment variables or config file), this information should be scrubbed from the archive in the `cmdline` file. + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/05-Osquery-logs.md b/docs/Using-Fleet/Osquery-logs.md similarity index 92% rename from docs/01-Using-Fleet/05-Osquery-logs.md rename to docs/Using-Fleet/Osquery-logs.md index 1e239ab210..2aefd4df88 100644 --- a/docs/01-Using-Fleet/05-Osquery-logs.md +++ b/docs/Using-Fleet/Osquery-logs.md @@ -2,7 +2,7 @@ This document provides instructions for working with each of the following log destinations in Fleet. -To configure each log destination, you must set the correct osquery logging configuration options in Fleet. Check out the reference documentation for osquery logging configuration options [here in the Fleet documentation](../02-Deploying/03-Configuration.md#osquery-status-log-plugin). +To configure each log destination, you must set the correct osquery logging configuration options in Fleet. Check out the reference documentation for osquery logging configuration options [here in the Fleet documentation](../Deploying/Configuration.md#osquery-status-log-plugin). - [Firehose](#firehose) - [Snowflake](#snowflake) @@ -19,7 +19,7 @@ To configure each log destination, you must set the correct osquery logging conf Logs are written to AWS Firehose streams. - Plugin name: `firehose` -- Flag namespace: [firehose](../02-Deploying/03-Configuration.md#firehose) +- Flag namespace: [firehose](../Deploying/Configuration.md#firehose) With the Firehose plugin, osquery result and/or status logs are written to [Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/). This is a very good method for aggregating osquery logs into AWS S3 storage. @@ -50,7 +50,7 @@ Splunk provides instructions on how to prepare the Splunk platform for Firehose Logs are written to AWS Kinesis streams. - Plugin name: `kinesis` -- Flag namespace: [kinesis](../02-Deploying/03-Configuration.md#kinesis) +- Flag namespace: [kinesis](../Deploying/Configuration.md#kinesis) With the Kinesis plugin, osquery result and/or status logs are written to [Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams). @@ -65,7 +65,7 @@ output in the Fleet logs and those logs _will not_ be sent to Kinesis. Logs are written to AWS Lambda functions. - Plugin name: `lambda` -- Flag namespace: [lambda](../02-Deploying/03-Configuration.md#lambda) +- Flag namespace: [lambda](../Deploying/Configuration.md#lambda) With the Lambda plugin, osquery result and/or status logs are written to [AWS Lambda](https://aws.amazon.com/lambda/) functions. @@ -88,7 +88,7 @@ Keep this in mind when using Lambda, as you're charged based on the number of re Logs are written to Google Cloud PubSub topics. - Plugin name: `pubsub` -- Flag namespace: [pubsub](../02-Deploying/03-Configuration.md#pubsub) +- Flag namespace: [pubsub](../Deploying/Configuration.md#pubsub) With the PubSub plugin, osquery result and/or status logs are written to [PubSub](https://cloud.google.com/pubsub/) topics. @@ -99,7 +99,7 @@ Note that messages over 10MB will be dropped, with a notification sent to the fl Logs are written to Apache Kafka topics. - Plugin name: `kafkarest` -- Flag namespace: [kafka](../02-Deploying/03-Configuration.md#kafka) +- Flag namespace: [kafka](../Deploying/Configuration.md#kafka) With the Kafka REST plugin, osquery result and/or status logs are written to [Kafka](https://kafka.apache.org/) topics using the [Kafka REST proxy](https://github.com/confluentinc/kafka-rest). @@ -110,7 +110,7 @@ Note that the REST proxy must be in place in order to send osquery logs to Kafka Logs are written to stdout. - Plugin name: `stdout` -- Flag namespace: [stdout](../02-Deploying/03-Configuration.md#stdout) +- Flag namespace: [stdout](../Deploying/Configuration.md#stdout) With the stdout plugin, osquery result and/or status logs are written to stdout on the Fleet server. This is typically used for debugging or with a log @@ -127,7 +127,7 @@ Logs are written to the local Fleet server filesystem. The default log destination. - Plugin name: `filesystem` -- Flag namespace: [filesystem](../02-Deploying/03-Configuration.md#filesystem) +- Flag namespace: [filesystem](../Deploying/Configuration.md#filesystem) With the filesystem plugin, osquery result and/or status logs are written to the local filesystem on the Fleet server. This is typically used with a log forwarding agent on the Fleet server that will push the logs into a logging pipeline. @@ -140,3 +140,5 @@ Osquery agents are typically configured to send logs to the Fleet server (`--log See the [osquery logging documentation](https://osquery.readthedocs.io/en/stable/deployment/logging/) for more about configuring logging on the agent. If `--logger_plugin=tls` is used with osquery clients, the following configuration can be applied on the Fleet server for handling the incoming logs. + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/09-Permissions.md b/docs/Using-Fleet/Permissions.md similarity index 99% rename from docs/01-Using-Fleet/09-Permissions.md rename to docs/Using-Fleet/Permissions.md index e9ba0713ed..94e19187dd 100644 --- a/docs/01-Using-Fleet/09-Permissions.md +++ b/docs/Using-Fleet/Permissions.md @@ -94,3 +94,5 @@ The following table depicts various permissions levels in a team. | Create team enroll secrets | | ✅ | ✅ | | Edit team enroll secrets | | ✅ | ✅ | | Edit agent options for hosts assigned to team | | | ✅ | + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/README.md b/docs/Using-Fleet/README.md similarity index 69% rename from docs/01-Using-Fleet/README.md rename to docs/Using-Fleet/README.md index b2bd4415de..e04af4f2d2 100644 --- a/docs/01-Using-Fleet/README.md +++ b/docs/Using-Fleet/README.md @@ -1,24 +1,24 @@ # Using Fleet -### [Fleet UI](./01-Fleet-UI.md) +### [Fleet UI](./Fleet-UI.md) Provides documentation about running and scheduling queries from within the Fleet UI -### [Fleetctl CLI](./02-fleetctl-CLI.md) +### [fleetctl CLI](./fleetctl-CLI.md) Includes resources for setting up and configuring Fleet via the fleetctl CLI -### [REST API](./03-REST-API.md) +### [REST API](./REST-API.md) Provides resources for working with Fleet's API and includes example code for endpoints -### [Adding hosts](./04-Adding-hosts.md) +### [Adding hosts](./Adding-hosts.md) Provides resources for enrolling your hosts to Fleet -### [Osquery logs](./05-Osquery-logs.md) +### [Osquery logs](./Osquery-logs.md) Includes documentation on the plugin options for working with osquery logs -### [Monitoring Fleet](./06-Monitoring-Fleet.md) +### [Monitoring Fleet](./Monitoring-Fleet.md) Provides documentation for load balancer health checks and working with Fleet server metrics and performance -### [Security best practices](./07-Security-best-practices.md) +### [Security best practices](./Security-best-practices.md) Includes resources for ways to mitigate against the OWASP top 10 issues ### [FAQ](./FAQ.md) diff --git a/docs/01-Using-Fleet/03-REST-API.md b/docs/Using-Fleet/REST-API.md similarity index 99% rename from docs/01-Using-Fleet/03-REST-API.md rename to docs/Using-Fleet/REST-API.md index ba9ce7006b..5a4c09fe39 100644 --- a/docs/01-Using-Fleet/03-REST-API.md +++ b/docs/Using-Fleet/REST-API.md @@ -30,7 +30,7 @@ Fleet is powered by a Go API server which serves three types of endpoints: ### fleetctl -Many of the operations that a user may wish to perform with an API are currently best performed via the [fleetctl](./02-fleetctl-CLI.md) tooling. These CLI tools allow updating of the osquery configuration entities, as well as performing live queries. +Many of the operations that a user may wish to perform with an API are currently best performed via the [fleetctl](./fleetctl-CLI.md) tooling. These CLI tools allow updating of the osquery configuration entities, as well as performing live queries. ### Current API @@ -479,7 +479,7 @@ This is the callback endpoint that the identity provider will use to send securi | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | | status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `machine_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an `@`, no space, etc.). | -| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](../01-Using-Fleet/02-fleetctl-CLI.md#fleet-configuration-options) for an example configuration with hosts' additional information. Use `*` to get all stored fields. | +| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](../Using-Fleet/fleetctl-CLI.md#fleet-configuration-options) for an example configuration with hosts' additional information. Use `*` to get all stored fields. | | team_id | integer | query | _Available in Fleet Premium_ Filters the hosts to only include hosts in the specified team. | | policy_id | integer | query | The ID of the policy to filter hosts by. `policy_response` must also be specified with `policy_id`. | | policy_response | string | query | Valid options are `passing` or `failing`. `policy_id` must also be specified with `policy_response`. | @@ -569,7 +569,7 @@ If `additional_info_filters` is not specified, no `additional` information will | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | | status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `machine_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an `@`, no space, etc.). | -| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](../01-Using-Fleet/02-fleetctl-CLI.md#fleet-configuration-options) for an example configuration with hosts' additional information. Use `*` to get all stored fields. | +| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](../Using-Fleet/fleetctl-CLI.md#fleet-configuration-options) for an example configuration with hosts' additional information. Use `*` to get all stored fields. | | team_id | integer | query | _Available in Fleet Premium_ Filters the hosts to only include hosts in the specified team. | | policy_id | integer | query | The ID of the policy to filter hosts by. `policy_response` must also be specified with `policy_id`. | | policy_response | string | query | Valid options are `passing` or `failing`. `policy_id` must also be specified with `policy_response`. | @@ -648,7 +648,7 @@ Returns the count of all hosts organized by status. `online_count` includes all Returns the information of the specified host. -The endpoint returns the host's installed `software` if the software inventory feature flag is turned on. This feature flag is turned off by default. [Check out the feature flag documentation](../02-Deploying/03-Configuration.md#feature-flags) for instructions on how to turn on the software inventory feature. +The endpoint returns the host's installed `software` if the software inventory feature flag is turned on. This feature flag is turned off by default. [Check out the feature flag documentation](../Deploying/Configuration.md#feature-flags) for instructions on how to turn on the software inventory feature. All the scheduled queries that are configured to run on the host (and their stats) are returned in `pack_stats`. The `pack_stats[i].type` field can have the following values: @@ -5347,7 +5347,7 @@ Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allo To initiate a file carve using the Fleet API, you can use the [live query](#run-live-query) or [scheduled query](#add-scheduled-query-to-a-pack) endpoints to run a query against the `carves` table. -For more information on executing a file carve in Fleet, go to the [File carving with Fleet docs](../01-Using-Fleet/02-fleetctl-CLI.md#file-carving-with-fleet). +For more information on executing a file carve in Fleet, go to the [File carving with Fleet docs](../Using-Fleet/fleetctl-CLI.md#file-carving-with-fleet). ### List carves @@ -6104,3 +6104,5 @@ Transforms a host name into a host id. For example, the Fleet UI use this endpoi "count": 43 } ``` + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/07-Security-best-practices.md b/docs/Using-Fleet/Security-best-practices.md similarity index 96% rename from docs/01-Using-Fleet/07-Security-best-practices.md rename to docs/Using-Fleet/Security-best-practices.md index d5d2fd9787..75bf788780 100644 --- a/docs/01-Using-Fleet/07-Security-best-practices.md +++ b/docs/Using-Fleet/Security-best-practices.md @@ -33,7 +33,7 @@ Passwords are never stored in plaintext in the database. We store a `bcrypt`ed h #### Authentication tokens -The size and expiration time of session tokens is admin-configurable. See [The documentation on session duration](../02-Deploying/03-Configuration.md#session-duration). +The size and expiration time of session tokens is admin-configurable. See [The documentation on session duration](../Deploying/Configuration.md#session-duration). It is possible to revoke all session tokens for a user by forcing a password reset. @@ -52,3 +52,5 @@ We render the frontend with React and benefit from built-in XSS protection in Re ### Components with known vulnerabilities – prevent the use of libraries, frameworks, other software with existing vulnerabilities. We rely on Github's automated vulnerability checks, community news, and direct reports to discover vulnerabilities in our dependencies. We endeavor to fix these immediately and would almost always do so within a week of a report. + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/12-Supported-browsers.md b/docs/Using-Fleet/Supported-browsers.md similarity index 94% rename from docs/01-Using-Fleet/12-Supported-browsers.md rename to docs/Using-Fleet/Supported-browsers.md index 5fae7fb5ea..8323ec1d94 100644 --- a/docs/01-Using-Fleet/12-Supported-browsers.md +++ b/docs/Using-Fleet/Supported-browsers.md @@ -23,3 +23,4 @@ We test each browser on Windows whenever possible, because our engineering team > - Mobile web is not yet supported in the Fleet product. > - The Fleet user interface [may not be fully supported](https://github.com/fleetdm/fleet/issues/969) in Google Chrome when the browser is running on Chrome OS + \ No newline at end of file diff --git a/docs/01-Using-Fleet/10-Teams.md b/docs/Using-Fleet/Teams.md similarity index 91% rename from docs/01-Using-Fleet/10-Teams.md rename to docs/Using-Fleet/Teams.md index 0944035fa4..b25350e78f 100644 --- a/docs/01-Using-Fleet/10-Teams.md +++ b/docs/Using-Fleet/Teams.md @@ -56,7 +56,7 @@ Hosts can only belong to one team in Fleet. You can add hosts to a new team in Fleet by either enrolling the host with a team's enroll secret or by [transferring the host via the Fleet UI](#transfer-hosts-to-a-team) after the host has been enrolled to Fleet. -To automatically add hosts to a team in Fleet check out the ["Adding hosts" documentation](./04-Adding-hosts.md#automatically-adding-hosts-to-a-team). +To automatically add hosts to a team in Fleet check out the ["Adding hosts" documentation](./Adding-hosts.md#automatically-adding-hosts-to-a-team). ## Transfer hosts to a team @@ -86,7 +86,7 @@ To add users to a team: 4. Select one or more users by searching for their full name and confirm the action. -Users will be given the [Observer role](./09-Permissions.md#team-member-permissions) when added to the team. The [Edit a member's role](#edit-a-members-role) provides instructions on changing the permission level of users on a team. +Users will be given the [Observer role](./Permissions.md#team-member-permissions) when added to the team. The [Edit a member's role](#edit-a-members-role) provides instructions on changing the permission level of users on a team. ## Edit a member's role @@ -123,3 +123,5 @@ To delete a team: 2. Find your team and select it. 3. On the right side, select "Delete team" and confirm the action. + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/11-Usage-statistics.md b/docs/Using-Fleet/Usage-statistics.md similarity index 97% rename from docs/01-Using-Fleet/11-Usage-statistics.md rename to docs/Using-Fleet/Usage-statistics.md index 0b528610f1..30865ff436 100644 --- a/docs/01-Using-Fleet/11-Usage-statistics.md +++ b/docs/Using-Fleet/Usage-statistics.md @@ -57,4 +57,6 @@ To disabled usage statistics: 2. Scroll to the "Usage statistics" section. -3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings." \ No newline at end of file +3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings." + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/13-Vulnerability-Processing.md b/docs/Using-Fleet/Vulnerability-Processing.md similarity index 98% rename from docs/01-Using-Fleet/13-Vulnerability-Processing.md rename to docs/Using-Fleet/Vulnerability-Processing.md index a9a34fbb11..1e5bf482b1 100644 --- a/docs/01-Using-Fleet/13-Vulnerability-Processing.md +++ b/docs/Using-Fleet/Vulnerability-Processing.md @@ -62,7 +62,7 @@ FLEET_VULNERABILITIES_DATABASES_PATH=/some/path The path specified needs to exist and Fleet needs to be able to read and write to and from it. This is the only mandatory configuration needed for vulnerability processing to work. Additional options, like vulnerability check frequency, can be -found in the [configuration documentation](../02-Deploying/03-Configuration.md#vulnerabilities). +found in the [configuration documentation](../Deploying/Configuration.md#vulnerabilities). You'll need to restart the Fleet instances after changing these settings. @@ -85,6 +85,7 @@ For example, when running a development instance of Fleet on an Apple Macbook Pr The CPU and memory usages are in burst once every hour (or the configured periodicity) on the instance that does the processing. RAM spikes are expected to not exceed the 2GBs. + ## Detection pipeline There are several steps that go into the vulnerability detection process. In this section we'll dive into what they are and how it works. @@ -197,4 +198,6 @@ If there's a match, we remove the false positive from the list. #### Supported Linux distributions and versions -- CentOS 6, 7 and 8. \ No newline at end of file +- CentOS 6, 7 and 8. + + diff --git a/docs/01-Using-Fleet/configuration-files/README.md b/docs/Using-Fleet/configuration-files/README.md similarity index 100% rename from docs/01-Using-Fleet/configuration-files/README.md rename to docs/Using-Fleet/configuration-files/README.md diff --git a/docs/01-Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml b/docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml rename to docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml diff --git a/docs/01-Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml b/docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml rename to docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml diff --git a/docs/01-Using-Fleet/configuration-files/kubernetes/fleet-service.yml b/docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/kubernetes/fleet-service.yml rename to docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/enroll-secrets.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/enroll-secrets.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/enroll-secrets.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/enroll-secrets.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/labels.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/labels.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/labels.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/labels.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/pack.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/pack.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/pack.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/pack.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/queries.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/queries.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/queries.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/queries.yml diff --git a/docs/01-Using-Fleet/configuration-files/multi-file-configuration/team.yml b/docs/Using-Fleet/configuration-files/multi-file-configuration/team.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/multi-file-configuration/team.yml rename to docs/Using-Fleet/configuration-files/multi-file-configuration/team.yml diff --git a/docs/01-Using-Fleet/configuration-files/single-file-configuration.yml b/docs/Using-Fleet/configuration-files/single-file-configuration.yml similarity index 100% rename from docs/01-Using-Fleet/configuration-files/single-file-configuration.yml rename to docs/Using-Fleet/configuration-files/single-file-configuration.yml diff --git a/docs/01-Using-Fleet/02-fleetctl-CLI.md b/docs/Using-Fleet/fleetctl-CLI.md similarity index 96% rename from docs/01-Using-Fleet/02-fleetctl-CLI.md rename to docs/Using-Fleet/fleetctl-CLI.md index c7e740f5c3..5352a6286b 100644 --- a/docs/01-Using-Fleet/02-fleetctl-CLI.md +++ b/docs/Using-Fleet/fleetctl-CLI.md @@ -31,7 +31,7 @@ This guide illustrates: ### Running Fleet -For the sake of this tutorial, we will be using the local development Docker Compose infrastructure to run Fleet locally. This is documented in some detail in the [developer documentation](../03-Contributing/01-Building-Fleet.md#development-infrastructure), but the following are the minimal set of commands that you can run from the root of the repository (assuming that you have a working Go/JavaScript toolchain installed along with Docker Compose): +For the sake of this tutorial, we will be using the local development Docker Compose infrastructure to run Fleet locally. This is documented in some detail in the [developer documentation](../Contributing/Building-Fleet.md#development-infrastructure), but the following are the minimal set of commands that you can run from the root of the repository (assuming that you have a working Go/JavaScript toolchain installed along with Docker Compose): ``` docker-compose up -d @@ -193,7 +193,7 @@ spec: Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allows the Fleet server to request files (and sets of files) from osquery agents, returning the full contents to Fleet. -File carving data can be either stored in Fleet's database or to an external S3 bucket. For information on how to configure the latter, consult the [configuration docs](../02-Deploying/03-Configuration.md#s3-file-carving-backend). +File carving data can be either stored in Fleet's database or to an external S3 bucket. For information on how to configure the latter, consult the [configuration docs](../Deploying/Configuration.md#s3-file-carving-backend). ### Configuration @@ -313,3 +313,5 @@ parts to 10,000. The value must be small enough that HTTP requests do not time out. Start with a default of 2MiB for MySQL (2097152 bytes), and 5MiB for S3/Minio (5242880 bytes). + + diff --git a/frontend/README.md b/frontend/README.md index 59e7a7c317..e02f4fcf18 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -18,7 +18,7 @@ The Fleet front-end is a Single Page Application using React with Typescript and ## Running the Fleet web app For details instruction on building and serving the Fleet web application -consult the [Contributing documentation](../docs/03-Contributing/README.md). +consult the [Contributing documentation](../docs/Contributing/README.md). ## Storybook diff --git a/frontend/README_deprecated.md b/frontend/README_deprecated.md index 79ac72db76..7ac4381b0e 100644 --- a/frontend/README_deprecated.md +++ b/frontend/README_deprecated.md @@ -9,7 +9,7 @@ The Fleet front-end is a Single Page Application using React and Redux. ## Running the Fleet web app For details instruction on building and serving the Fleet web application -consult the [Contributing documentation](../docs/03-Contributing/README.md). +consult the [Contributing documentation](../docs/Contributing/README.md). ## Directory Structure diff --git a/handbook/brand.md b/handbook/brand.md index 79e2e80411..41fba3528b 100644 --- a/handbook/brand.md +++ b/handbook/brand.md @@ -83,7 +83,7 @@ If the action fails, please complete the following steps: ### Browser compatibility checking -A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be carried out monthly to verify that the website looks, and functions as expected across all [supported browsers](../docs/01-Using-Fleet/12-Supported-browsers.md). +A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be carried out monthly to verify that the website looks, and functions as expected across all [supported browsers](../docs/Using-Fleet/Supported-browsers.md). - We use [BrowserStack](https://www.browserstack.com/users/sign_in) (logins can be found in [1Password](https://start.1password.com/open/i?a=N3F7LHAKQ5G3JPFPX234EC4ZDQ&v=3ycqkai6naxhqsylmsos6vairu&i=nwnxrrbpcwkuzaazh3rywzoh6e&h=fleetdevicemanagement.1password.com)) for our cross-browser checks. - Check for issues against the latest version of Google Chrome (macOS). We use this as our baseline for quality assurance. diff --git a/handbook/community.md b/handbook/community.md index bc2dd0fec5..f435d0e7a0 100644 --- a/handbook/community.md +++ b/handbook/community.md @@ -43,12 +43,12 @@ Keep headings brief and organize them in a logical order: Try to stay within 3 or 4 heading levels. Complicated documents may use more, but pages with a simpler structure are easier to read. ### Adding a link to the Fleet docs -You can link documentation pages to each other using relative paths. For example, in `docs/01-Using-Fleet/01-Fleet-UI.md`, you can link to `docs/01-Using-Fleet/09-Permissions.md` by writing `[permissions](./09-Permissions.md)`. This will be automatically transformed into the appropriate URL for `fleetdm.com/docs`. +You can link documentation pages to each other using relative paths. For example, in `docs/Using-Fleet/Fleet-UI.md`, you can link to `docs/Using-Fleet/Permissions.md` by writing `[permissions](./Permissions.md)`. This will be automatically transformed into the appropriate URL for `fleetdm.com/docs`. However, the `fleetdm.com/docs` compilation process does not account for relative links to directories **outside** of `/docs`. Therefore, when adding a link to Fleet docs, it is important to always use the absolute file path. -When directly linking to a specific section within a page in the Fleet documentation, always format the spaces within a section name to use a hyphen `-` instead of an underscore `_`. For example, when linking to the `osquery_result_log_plugin` section of the configuration reference docs, use a relative link like the following: `./02-Configuration.md#osquery-result-log-plugin`. +When directly linking to a specific section within a page in the Fleet documentation, always format the spaces within a section name to use a hyphen `-` instead of an underscore `_`. For example, when linking to the `osquery_result_log_plugin` section of the configuration reference docs, use a relative link like the following: `./Configuration.md#osquery-result-log-plugin`. ### Linking to a location on GitHub When adding a link to a location on GitHub that is outside of `/docs`, be sure to use the canonical form of the URL. @@ -68,6 +68,14 @@ If the link lives outside `/docs`, head to the file's location on GitHub (in thi > Note that the instructions above also apply to adding links in the Fleet handbook. +### Ordering a page in the Fleet docs +The order we display documentation pages on fleetdm.com is determined by `pageOrderInSection` meta tags. These pages are sorted in their respective section by the `pageOrderInSection` value in **ascending** order. Every markdown file (except readme and faq pages) in the `docs/` folder must have a meta tag with a positive pageOrderInSection value. + + +We leave large gaps between values to make future changes easier. For example, the first page in the "Using Fleet" section of the docs has a `pageOrderInSection` value of 100, and the next page has a value of 200. The large difference between values allows us to add, remove and reorder pages without the need for changing the value of multiple pages at a time. + +When adding or reordering a page, try to leave as much room between values as possible. If you were adding a new page that would go between the two pages from the example above, you would add `` to the page. + ### Adding an image to the Fleet docs Try to keep images in the docs at a minimum. Images can be a quick way to help a user understand a concept or direct them towards a specific UI element, but too many can make the documentation feel cluttered and more difficult to maintain. diff --git a/handbook/engineering.md b/handbook/engineering.md index 57960579d6..cd0f3b4779 100644 --- a/handbook/engineering.md +++ b/handbook/engineering.md @@ -20,7 +20,7 @@ Non-release blocking bugs may include known issues that were not targeted for th ### Release day Documentation on completing the release process can be found -[here](../docs/03-Contributing/05-Releasing-Fleet.md). +[here](../docs/Contributing/Releasing-Fleet.md). ## On-call rotation @@ -113,7 +113,7 @@ There are four sources that the on-call engineer should monitor for activity: There are several locations in Fleet's public and internal documentation that can be helpful when answering questions raised by the community: -1. The frequently asked question (FAQ) documents in each section found in the `/docs` folder. These documents are the [Using Fleet FAQ](../docs/01-Using-Fleet/FAQ.md), [Deploying FAQ](../docs/02-Deploying/FAQ.md), and [Contributing FAQ](../docs/03-Contributing/FAQ.md). +1. The frequently asked question (FAQ) documents in each section found in the `/docs` folder. These documents are the [Using Fleet FAQ](../docs/Using-Fleet/FAQ.md), [Deploying FAQ](../docs/Deploying/FAQ.md), and [Contributing FAQ](../docs/Contributing/FAQ.md). 2. The [Internal FAQ](https://docs.google.com/document/d/1I6pJ3vz0EE-qE13VmpE2G3gd5zA1m3bb_u8Q2G3Gmp0/edit#heading=h.ltavvjy511qv) document. diff --git a/handbook/product.md b/handbook/product.md index c6b460271d..36e9a0e5f3 100644 --- a/handbook/product.md +++ b/handbook/product.md @@ -171,7 +171,7 @@ The goal of quality assurance is to catch unexpected behavior prior to release: ### Collecting bugs -All QA steps should be possible using `fleetctl preview`. Please refer to [docs/03-Contributing/02-Testing.md](https://fleetdm.com/docs/contributing/testing) for flows that cannot be completed using `fleetctl preview`. +All QA steps should be possible using `fleetctl preview`. Please refer to [docs/Contributing/Testing.md](https://fleetdm.com/docs/contributing/testing) for flows that cannot be completed using `fleetctl preview`. Please start the manual QA process by creating a blank GitHub issue. As you complete each of the flows, record a list of the bugs you encounter in this new issue. Each item in this list should @@ -269,9 +269,9 @@ Run the "Get the version of the resident operating system" query against your lo Apply a pack by running the following commands: -`fleetctl apply -f docs/01-Using-Fleet/configuration-files/multi-file-configuration/queries.yml` +`fleetctl apply -f docs/Using-Fleet/configuration-files/multi-file-configuration/queries.yml` -`fleetctl apply -f docs/01-Using-Fleet/configuration-files/multi-file-configuration/pack.yml` +`fleetctl apply -f docs/Using-Fleet/configuration-files/multi-file-configuration/pack.yml` Make sure the pack was successfully added by running the following command: @@ -281,7 +281,7 @@ Make sure the pack was successfully added by running the following command: Apply organization settings by running the following command: -`fleetctl apply -f docs/01-Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml` +`fleetctl apply -f docs/Using-Fleet/configuration-files/multi-file-configuration/organization-settings.yml` #### Manage users flow diff --git a/tools/backup_db/README.md b/tools/backup_db/README.md index 11d7ad61a8..b30bc29654 100644 --- a/tools/backup_db/README.md +++ b/tools/backup_db/README.md @@ -1,3 +1,3 @@ These scripts are for backing up and restore the Docker development MySQL database. -Usage is documented [here](../../docs/03-Contributing/02-Testing.md#database-backuprestore). +Usage is documented [here](../../docs/Contributing/Testing.md#database-backuprestore). diff --git a/website/assets/js/pages/docs/basic-documentation.page.js b/website/assets/js/pages/docs/basic-documentation.page.js index 85300fd578..e04f8245ce 100644 --- a/website/assets/js/pages/docs/basic-documentation.page.js +++ b/website/assets/js/pages/docs/basic-documentation.page.js @@ -45,27 +45,16 @@ parasails.registerPage('basic-documentation', { let pagesBySectionSlug = {}; for (let sectionSlug of sectionSlugs) { - pagesBySectionSlug[sectionSlug] = _ - .chain(this.pages) - .filter((page) => { - return sectionSlug === page.url.split(/\//).slice(-2)[0]; - }) - .sortBy((page) => { - // custom sort function is needed because simple sort of alphanumeric htmlIds strings - // does not appropriately handle double-digit strings - try { - // attempt to split htmlId and parse out its ordinal value (e.g., `docs--10-teams--xxxxxxxxxx`) - let sortValue = page.htmlId.split(/--/)[1].split(/-/)[0]; - return parseInt(sortValue) || sortValue; - } catch (error) { - // something unexpected happened so just return the htmlId and continue sort - console.log(error); - return page.htmlId; - } - }) - .value(); + pagesBySectionSlug[sectionSlug] = this.pages.filter((page) => { + return sectionSlug === page.url.split(/\//).slice(-2)[0]; + }); + // Sorting pages by pageOrderInSectionPath value, README files do not have a pageOrderInSectionPath, and FAQ pages are added to the end of the sorted array below. + pagesBySectionSlug[sectionSlug] = _.sortBy(pagesBySectionSlug[sectionSlug], (page) => { + if (!page.sectionRelativeRepoPath.match(/README\.md$/i) && !page.sectionRelativeRepoPath.match(/FAQ\.md$/i)) { + return page.pageOrderInSectionPath; + } + }); } - // We need to re-sort the top-level sections because their htmlIds do not reflect the correct order pagesBySectionSlug['docs'] = DOCS_SLUGS.map((slug) => { return pagesBySectionSlug['docs'].find((page) => slug === _.kebabCase(page.title)); diff --git a/website/scripts/build-static-content.js b/website/scripts/build-static-content.js index 0a75427424..5a30cf9c34 100644 --- a/website/scripts/build-static-content.js +++ b/website/scripts/build-static-content.js @@ -312,9 +312,32 @@ module.exports = { pageTitle = fallbackPageTitle; } + + // If the page has a pageOrderInSection meta tag, we'll use that to sort pages in their bottom level sections. + let pageOrderInSection; + if(sectionRepoPath === 'docs/') { + // Set a flag to determine if the page is a readme (e.g. /docs/Using-Fleet/configuration-files/readme.md) or a FAQ page. + // READMEs in subfolders and FAQ pages don't have pageOrderInSection values, they are always sorted at the end of sections. + let isPageAReadmeOrFAQ = (_.last(pageUnextensionedLowercasedRelPath.split(/\//)) === 'faq' || _.last(pageUnextensionedLowercasedRelPath.split(/\//)) === 'readme'); + if(embeddedMetadata.pageOrderInSection) { + if(isPageAReadmeOrFAQ) { + // Throwing an error if a FAQ or README page has a pageOrderInSection meta tag + throw new Error(`Failed compiling markdown content: A FAQ or README page has a pageOrderInSection meta tag () at "${path.join(topLvlRepoPath, pageSourcePath)}". To resolve, remove this meta tag from the markdown file.`); + } + // Checking if the meta tag's value is a number higher than 0 + if (embeddedMetadata.pageOrderInSection <= 0 || _.isNaN(parseInt(embeddedMetadata.pageOrderInSection)) ) { + throw new Error(`Failed compiling markdown content: Invalid page rank () embedded in "${path.join(topLvlRepoPath, sectionRepoPath)}". To resolve, try changing the rank to a number higher than 0, then rebuild.`); + } else { + pageOrderInSection = parseInt(embeddedMetadata.pageOrderInSection); + } + } else if(!embeddedMetadata.pageOrderInSection && !isPageAReadmeOrFAQ){ + // If the page is not a Readme or a FAQ, we'll throw an error if its missing a pageOrderInSection meta tag. + throw new Error(`Failed compiling markdown content: A Non FAQ or README Documentation page is missing a pageOrderInSection meta tag () at "${path.join(topLvlRepoPath, pageSourcePath)}". To resolve, add a meta tag with a number higher than 0.`); + } + } + // Determine unique HTML id // > • This will become the filename of the resulting HTML. - // > • And it will be attached to menu data for use in sorting pages within their bottom-level sections. let htmlId = ( sectionRepoPath.slice(0,10)+ '--'+ @@ -332,7 +355,7 @@ module.exports = { } // Determine the path of the file in the fleet repo so we can link to - // the file on github from fleetdm.com (e.g. 01-Using-Fleet/02-fleetctl-CLI.md) + // the file on github from fleetdm.com (e.g. Using-Fleet/fleetctl-CLI.md) let sectionRelativeRepoPath = path.relative(path.join(topLvlRepoPath, sectionRepoPath), path.resolve(pageSourcePath)); // Append to what will become configuration for the Sails app. @@ -341,8 +364,9 @@ module.exports = { title: pageTitle, lastModifiedAt: lastModifiedAt, htmlId: htmlId, + pageOrderInSectionPath: pageOrderInSection, sectionRelativeRepoPath: sectionRelativeRepoPath, - meta: _.omit(embeddedMetadata, 'title') + meta: _.omit(embeddedMetadata, ['title', 'pageOrderInSection']) }); } }//∞ diff --git a/website/views/pages/query-library.ejs b/website/views/pages/query-library.ejs index 5d1a148b50..2cb6fd4c16 100644 --- a/website/views/pages/query-library.ejs +++ b/website/views/pages/query-library.ejs @@ -152,7 +152,8 @@

Contributors

Want to add your own query? Please submit a pull request - over on GitHub. + over on GitHub + .