Docs quick reference optimization (#21331)

This PR closes #21108 @noahtalerman, I double-checked all redirects, and they are working. Clicking through the URLs in [this spreadsheet](https://docs.google.com/spreadsheets/d/1djVynIMuJK4pT5ziJW12CluVqcaoxxnCLaBO3VXfAt4/edit?usp=sharing) is a pretty quick way to go through them all. Note that "Audit logs" and "Understanding host vitals" redirect to the contributor docs on GitHub, so they will throw a 404 until this is merged. Some new guides benefitted from a name change, so they make more sense as stand-alone guides, and also so that we don't have to mess around with more redirects later. Those name changes followed [this convention](https://fleetdm.com/handbook/company/communications#headings-and-titles), which was recently documented in the handbook. Have fun! --------- Co-authored-by: Eric <eashaw@sailsjs.com> Co-authored-by: Noah Talerman <noahtal@umich.edu>
fleetdm · Aug 16, 2024 · 2171544 · 2171544
1 parent 934c02a
commit 2171544
Show file tree

Hide file tree

Showing 39 changed files with 325 additions and 322 deletions.
diff --git a/docs/Using Fleet/Automations.md → articles/automations.md b/docs/Using Fleet/Automations.md → articles/automations.md
@@ -40,6 +40,9 @@ Host status automations send a webhook request if a configured percentage of hos
 
 Fleet sends these webhook requests once per day by default.
 
-<meta name="pageOrderInSection" value="1509">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-07-03">
+<meta name="articleTitle" value="Automations">
 <meta name="description" value="Configure Fleet automations to trigger webhooks or create tickets in Jira and Zendesk for vulnerability, policy, and host status events.">
-<meta name="navSection" value="Device management">
diff --git a/docs/Using Fleet/enroll-chromebooks.md → articles/chrome-os.md b/docs/Using Fleet/enroll-chromebooks.md → articles/chrome-os.md
@@ -1,8 +1,6 @@
 # ChromeOS
 For visibility on ChromeOS hosts, Fleet provides the fleetd Chrome extension which provides similar functionality as osquery on other operating systems.
 
-## Adding ChromeOS hosts to Fleet
-
 To learn how to add ChromeOS hosts to Fleet, visit [here](https://fleetdm.com/docs/using-fleet/adding-hosts#enroll-chromebooks).
 
 > The fleetd Chrome browser extension is supported on ChromeOS operating systems that are managed using [Google Admin](https://admin.google.com). It is not intended for non-ChromeOS hosts with the Chrome browser installed.
@@ -23,6 +21,10 @@ By default, the hostname for a Chromebook host will be blank. The hostname can b
 
 ## Debugging ChromeOS
 To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension).
-<meta name="title" value="Enroll Chromebooks">
-<meta name="pageOrderInSection" value="2000">
-<meta name="navSection" value="Dig deeper">
+
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="zhumo">
+<meta name="authorFullName" value="Mo Zhu">
+<meta name="publishedOn" value="2023-11-21">
+<meta name="articleTitle" value="ChromeOS">
+<meta name="description" value="Learn about ChromeOS and Fleet.">
diff --git a/docs/Using Fleet/CIS-Benchmarks.md → articles/cis-benchmarks.md b/docs/Using Fleet/CIS-Benchmarks.md → articles/cis-benchmarks.md
@@ -11,7 +11,7 @@ Fleet has implemented native support for CIS Benchmarks for the following platfo
 - Windows 10 Enterprise
 - Windows 11 Enterprise
 
-[Where possible](#limitations), each CIS Benchmark is implemented with a [policy query](./REST-API.md#policies) in Fleet. 
+[Where possible](#limitations), each CIS Benchmark is implemented with a [policy query](https://fleetdm.com/docs/rest-api/rest-api#policies) in Fleet. 
 
 These benchmarks are intended to gauge your organization's security posture, rather than the current state of a given host. A host may fail a CIS Benchmark policy despite having the correct settings enabled if there is no configuration profile or Group Policy Object (GPO) in place to enforce the setting. For example, this is the query for  **CIS - Ensure FileVault Is Enabled (MDM Required)**:
 
@@ -95,7 +95,7 @@ Following are the requirements to use the CIS Benchmarks in Fleet:
 
 - Devices must be running [`fleetd`](https://fleetdm.com/docs/using-fleet/orbit), Fleet's lightweight agent.
 - Some CIS Benchmarks explicitly involve verifying MDM-based controls, so devices must be enrolled to an MDM solution.
-- On macOS, the orbit component of fleetd must have "Full Disk Access", see [Grant Full Disk Access to Osquery on macOS](./Adding-hosts.md#grant-full-disk-access-to-osquery-on-macos).
+- On macOS, the orbit component of fleetd must have "Full Disk Access", see [Grant Full Disk Access to Osquery on macOS](https://fleetdm.com/guides/enroll-hosts#grant-full-disk-access-to-osquery-on-macos).
 
 ## Limitations
 
@@ -111,7 +111,9 @@ In August 2023, we completed scale testing on 10k Windows hosts and 70k macOS ho
 
 Detailed results are [here](https://docs.google.com/document/d/1OSpyzMkHjVhG_-EIBkLu7X3hj_XfVASGl3IXIYChpck/edit?usp=sharing).
 
-<meta name="pageOrderInSection" value="1700">
-<meta name="title" value="CIS Benchmarks">
-<meta name="description" value="Read about how Fleet's implementation of CIS Benchmarks offers consensus-based cybersecurity guidance, covering macOS 13.0 Ventura & Windows Enterprise.">
-<meta name="navSection" value="Security compliance">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="lucasmrod">
+<meta name="authorFullName" value="Lucas Rodriguez">
+<meta name="publishedOn" value="2024-04-02">
+<meta name="articleTitle" value="CIS Benchmarks">
+<meta name="description" value="Read about how Fleet's implementation of CIS Benchmarks offers consensus-based cybersecurity guidance.">
diff --git a/docs/Using Fleet/MDM-custom-OS-settings.md → articles/custom-os-settings.md b/docs/Using Fleet/MDM-custom-OS-settings.md → articles/custom-os-settings.md
@@ -1,6 +1,6 @@
 # Custom OS settings
 
-In Fleet you can enforce OS settings on your your macOS, iOS, iPadOS, and Windows hosts using configuration profiles.
+In Fleet you can enforce OS settings like security restrictions, screen lock, Wi-Fi etc., on your your macOS, iOS, iPadOS, and Windows hosts using configuration or device profiles.
 
 ## Enforce OS settings
 
@@ -36,7 +36,9 @@ In the top box, with "Verified," "Verifying," "Pending," and "Failed" statuses,
 
 In the list of hosts, click on an individual host and click the **OS settings** item to see the status for a specific setting.
 
-<meta name="pageOrderInSection" value="1505">
-<meta name="title" value="Custom OS settings">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-07-27">
+<meta name="articleTitle" value="Custom OS settings">
 <meta name="description" value="Learn how to enforce custom settings on macOS and Window hosts using Fleet's configuration profiles.">
-<meta name="navSection" value="Device management">
diff --git a/docs/Using Fleet/downgrading-fleet.md → articles/downgrade-fleet.md b/docs/Using Fleet/downgrading-fleet.md → articles/downgrade-fleet.md
@@ -1,4 +1,4 @@
-# Downgrading from Fleet Premium
+# Downgrade from Fleet Premium
 
 Follow these steps to downgrade your Fleet instance from Fleet Premium.
 
@@ -34,8 +34,9 @@ Follow these steps to downgrade your Fleet instance from Fleet Premium.
 1. Remove your license key from your Fleet configuration. Documentation on where the license key is located in your configuration is [here](https://fleetdm.com/docs/deploying/configuration#license).
 2. Restart your Fleet server.
 
-
-
-<meta name="title" value="Downgrading Fleet">
-<meta name="navSection" value="Dig deeper">
-<meta name="pageOrderInSection" value="2000">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="eashaw">
+<meta name="authorFullName" value="Eric Shaw">
+<meta name="publishedOn" value="2024-01-09">
+<meta name="articleTitle" value="Downgrade from Fleet Premium">
+<meta name="description" value="Learn how to downgrade from Fleet Premium.">
diff --git a/docs/Using Fleet/MDM-disk-encryption.md → articles/enforce-disk-encryption.md b/docs/Using Fleet/MDM-disk-encryption.md → articles/enforce-disk-encryption.md
@@ -1,4 +1,4 @@
-# Disk encryption
+# Enforce disk encryption
 
 _Available in Fleet Premium_
 
@@ -58,9 +58,11 @@ How to view the disk encryption key:
 
 When migrating macOS hosts from another MDM solution, in order to complete the process of encrypting the hard drive and escrowing the key in Fleet, your end users must log out or restart their device.
 
-Share [these guided instructions](./MDM-migration-guide.md#how-to-turn-on-disk-encryption) with your end users.
+Share [these guided instructions](https://fleetdm.com/guides/mdm-migration#how-to-turn-on-disk-encryption) with your end users.
 
-<meta name="pageOrderInSection" value="1504">
-<meta name="title" value="Disk encryption">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-08-14">
+<meta name="articleTitle" value="Enforce disk encryption">
 <meta name="description" value="Learn how to enforce disk encryption on macOS and Windows hosts and manage encryption keys with Fleet Premium.">
-<meta name="navSection" value="Device management">
diff --git a/docs/Using Fleet/MDM-OS-updates.md → articles/enforce-os-updates.md b/docs/Using Fleet/MDM-OS-updates.md → articles/enforce-os-updates.md
@@ -1,12 +1,8 @@
-# OS updates
+# Enforce OS updates
 
 _Available in Fleet Premium_
 
-In Fleet you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hosts remotely.
-
-## Enforce OS updates
-
-You can enforce OS updates using the Fleet UI, Fleet API, or [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops).
+In Fleet you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hosts remotely using the Fleet UI, Fleet API, or [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops).
 
 Fleet UI:
 
@@ -54,8 +50,9 @@ Fleet enforces OS updates for quality and feature updates. Read more about the t
 
 When a minimum version is enforced, end users will see a notification in their Notification Center after the deadline. They can’t use their iPhone or iPad until the OS update is installed.
 
-<meta name="pageOrderInSection" value="1503">
-<meta name="title" value="OS updates">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-08-10">
+<meta name="articleTitle" value="Enforce OS updates">
 <meta name="description" value="Learn how to manage OS updates on macOS, Windows, iOS, and iPadOS devices.">
-<meta name="navSection" value="Device management">
-
diff --git a/docs/Using Fleet/enroll-hosts.md → articles/enroll-hosts.md b/docs/Using Fleet/enroll-hosts.md → articles/enroll-hosts.md
@@ -1,7 +1,5 @@
 # Enroll hosts
 
-## Introduction
-
 Fleet gathers information from an [osquery](https://github.com/osquery/osquery) agent installed on each of your hosts. The recommended way to install osquery is using fleetd.
 
 You can enroll macOS, Windows or Linux hosts via the [CLI](#cli) or [UI](#ui). To learn how to enroll Chromebooks, see [Enroll Chromebooks](#enroll-chromebooks).
@@ -54,7 +52,7 @@ You can use your software management tool of choice to distribute Fleet's agent
 
 ### Fleet Desktop
 
-[Fleet Desktop](./Fleet-desktop.md) is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine.
+[Fleet Desktop](https://fleetdm.com/guides/fleet-desktop) is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine.
 
 You can include Fleet Desktop in Fleet's agent (fleetd) by including `--fleet-desktop` in the `fleetctl package` command.
 
@@ -379,6 +377,9 @@ but can result in a large volume of error logs. In fleetd v1.15.1, we added an e
 Applying the environmental variable `"FLEETD_SILENCE_ENROLL_ERROR"=1` on a host will silence fleetd enrollment errors if a `--fleet-url` is not present.
 This variable is read at launch and will require a restart of the Orbit service if it is not set before installing `fleetd` v1.15.1.
 
-<meta name="pageOrderInSection" value="500">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-08-08">
+<meta name="articleTitle" value="Enroll hosts">
 <meta name="description" value="Learn how to enroll hosts to Fleet.">
-<meta name="navSection" value="The basics">
diff --git a/docs/Using Fleet/Fleet-desktop.md → articles/fleet-desktop.md b/docs/Using Fleet/Fleet-desktop.md → articles/fleet-desktop.md
@@ -1,12 +1,7 @@
 # Fleet Desktop
-- [Installing Fleet Desktop](#installing-fleet-desktop)
-- [Upgrading Fleet Desktop](#upgrading-fleet-desktop)
-- [Custom Transparency Link](#custom-transparency-link)
-- [Securing Fleet Desktop](#securing-fleet-desktop)
 
-Fleet Desktop is a menu bar icon available on macOS, Windows, and Linux.
+Fleet Desktop is a menu bar icon available on macOS, Windows, and Linux that gives your end users visibility into the security posture of their machine. This unlocks two key benefits:
 
-At its core, Fleet Desktop gives your end users visibility into the security posture of their machine. This unlocks two key benefits:
 * Self-remediation: end users can see which policies they are failing and resolution steps, reducing the need for IT and security teams to intervene
 * Scope transparency: end users can see what the Fleet agent can do on their machines, eliminating ambiguity between end users and their IT and security teams
 
@@ -16,10 +11,10 @@ At its core, Fleet Desktop gives your end users visibility into the security pos
    <iframe src="https://www.youtube.com/embed/cI2vDG3PbVo" allowfullscreen></iframe>
 </div>
 
-## Installing Fleet Desktop
+## Install Fleet Desktop
 For information on how to install Fleet Desktop, visit: [Adding Hosts](https://fleetdm.com/docs/using-fleet/adding-hosts#fleet-desktop).
 
-## Upgrading Fleet Desktop
+## Upgrade Fleet Desktop
 Once installed, Fleet Desktop will be automatically updated via Fleetd. To learn more, visit: [Self-managed agent updates](https://fleetdm.com/docs/deploying/fleetctl-agent-updates#self-managed-agent-updates).
 
 ## Custom transparency link
@@ -32,7 +27,7 @@ On the settings page, go to "Organization Settings" and select "Fleet Desktop."
 
 For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/configuration/fleet-server-configuration#fleet-desktop-settings) documentation.
 
-## Securing Fleet Desktop
+## Secure Fleet Desktop
 
 Requests sent by Fleet Desktop and the web page that opens when clicking on the "My Device" tray item use a [Random (Version 4) UUID](https://www.rfc-editor.org/rfc/rfc4122.html#section-4.4) token to uniquely identify each host.
 
@@ -57,7 +52,9 @@ As a consequence, Fleet Desktop will issue a new token if the current token is:
 
 This change is imperceptible to users, as clicking on the "My device" tray item always uses a valid token. If a user visits an address with an expired token, they will get a message instructing them to click on the tray item again.
 
-<meta name="title" value="Fleet Desktop">
-<meta name="pageOrderInSection" value="450">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="zhumo">
+<meta name="authorFullName" value="Mo Zhu">
+<meta name="publishedOn" value="2024-04-19">
+<meta name="articleTitle" value="Fleet Desktop">
 <meta name="description" value="Learn about Fleet Desktop's features for self-remediation and transparency.">
-<meta name="navSection" value="The basics">
diff --git a/docs/Using Fleet/Usage-statistics.md → articles/fleet-usage-statistics.md b/docs/Using Fleet/Usage-statistics.md → articles/fleet-usage-statistics.md
@@ -1,7 +1,9 @@
-# Usage statistics
+# Fleet usage statistics
 
 Fleet Device Management Inc. periodically collects information about your instance.
 
+> To disable usage statistics, [see here](#disable-usage-statistics).
+
 ## What is included in usage statistics in Fleet?
 
 Below is the JSON payload that is sent to Fleet Device Management Inc:
@@ -138,6 +140,9 @@ To disable usage statistics:
 
 3. Uncheck the "Enable usage statistics" checkbox and then select "Update settings."
 
-<meta name="pageOrderInSection" value="1100">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-08-13">
+<meta name="articleTitle" value="Fleet usage statistics">
 <meta name="description" value="Learn about Fleet's usage statistics and what information is collected.">
-<meta name="navSection" value="Dig deeper">
diff --git a/docs/Using Fleet/fleetctl-CLI.md → articles/fleetctl.md b/docs/Using Fleet/fleetctl-CLI.md → articles/fleetctl.md
@@ -1,6 +1,6 @@
-# fleetctl CLI
+# fleetctl
 
-fleetctl (pronounced "Fleet control") is a CLI tool for managing Fleet from the command line. fleetctl enables a GitOps workflow with Fleet.
+fleetctl (pronounced "Fleet control") is a command line interface (CLI) tool for managing Fleet from the command line. fleetctl enables a GitOps workflow with Fleet.
 
 fleetctl also provides a quick way to work with all the data exposed by Fleet without having to use the Fleet UI or work directly with the Fleet API.
 
@@ -197,6 +197,9 @@ This will generate a `tar.gz` file with:
 - A file containing a set of all the errors that happened in the server during the interval of time defined by the [logging_error_retention_period](https://fleetdm.com/docs/deploying/configuration#logging-error-retention-period) configuration.
 - Files containing database-specific information.
 
-<meta name="pageOrderInSection" value="300">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-07-04">
+<meta name="articleTitle" value="fleetctl">
 <meta name="description" value="Read about fleetctl, a CLI tool for managing Fleet and osquery configurations, running queries, generating Fleet's agent (fleetd) and more.">
-<meta name="navSection" value="The basics">
diff --git a/docs/Using Fleet/update-agents.md → articles/fleetd-updates.md b/docs/Using Fleet/update-agents.md → articles/fleetd-updates.md
@@ -1,7 +1,6 @@
-# Self-managed agent updates 
+# Fleetd updates 
 
-The fleetd agent will periodically check the public Fleet update repository and update Orbit, Fleet Desktop, and/or osquery 
-if it detects a later version.
+The fleetd agent will periodically check the public Fleet update repository and update Orbit, Fleet Desktop, and/or osquery if it detects a later version.
 
 To override this behavior, users can set a channel for each component or disable updates altogether. Visit [Adding Hosts](https://fleetdm.com/docs/using-fleet/adding-hosts#fleet-desktop) to learn more.
 Alternatively, users with a Fleet Premium subscription can self-manage an update server.
@@ -160,6 +159,9 @@ fleetctl updates rotate targets
 
 After the key(s) have been rotated, publish the repository in the same fashion as any other update.
 
-<meta name="pageOrderInSection" value="400">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="noahtalerman">
+<meta name="authorFullName" value="Noah Talerman">
+<meta name="publishedOn" value="2024-04-30">
+<meta name="articleTitle" value="Fleetd updates">
 <meta name="description" value="Information on how to manage and secure Fleet agent updates.">
-<meta name="navSection" value="Dig deeper">
diff --git a/docs/Using Fleet/Log-destinations.md → articles/log-destinations.md b/docs/Using Fleet/Log-destinations.md → articles/log-destinations.md
@@ -1,19 +1,5 @@
 # Log destinations
 
-- [Log destinations](#log-destinations)
-  - [Amazon Kinesis Data Firehose](#amazon-kinesis-data-firehose)
-  - [Snowflake](#snowflake)
-  - [Splunk](#splunk)
-  - [Amazon Kinesis Data Streams](#amazon-kinesis-data-streams)
-  - [AWS Lambda](#aws-lambda)
-  - [Google Cloud Pub/Sub](#google-cloud-pubsub)
-  - [Apache Kafka](#apache-kafka)
-  - [Stdout](#stdout)
-  - [Filesystem](#filesystem)
-  - [Sending logs outside of Fleet](#sending-logs-outside-of-fleet)
-
-This document provides a list of the supported log destinations in Fleet.
-
 Log destinations can be used in Fleet to log:
 - Osquery [status logs](https://osquery.readthedocs.io/en/stable/deployment/logging/#status-logs).
 
@@ -23,11 +9,27 @@ Log destinations can be used in Fleet to log:
 
 
 To configure each log destination, you must set the correct logging configuration options in Fleet.
+
 Check out the reference documentation for:
   - [Osquery status logging configuration options](https://fleetdm.com/docs/deploying/configuration#osquery-status-log-plugin).
   - [Osquery result logging configuration options](https://fleetdm.com/docs/deploying/configuration#osquery-result-log-plugin).
   - [Activity audit logging configuration options](https://fleetdm.com/docs/deploying/configuration#activity_audit_log_plugin).
 
+This guide provides a list of the supported log destinations in Fleet.
+
+### In this guide:
+
+- [Amazon Kinesis Data Firehose](#amazon-kinesis-data-firehose)
+- [Snowflake](#snowflake)
+- [Splunk](#splunk)
+- [Amazon Kinesis Data Streams](#amazon-kinesis-data-streams)
+- [AWS Lambda](#aws-lambda)
+- [Google Cloud Pub/Sub](#google-cloud-pubsub)
+- [Apache Kafka](#apache-kafka)
+- [Stdout](#stdout)
+- [Filesystem](#filesystem)
+- [Sending logs outside of Fleet](#sending-logs-outside-of-fleet)
+
 ## Amazon Kinesis Data Firehose
 
 Logs are written to [Amazon Kinesis Data Firehose (Firehose)](https://aws.amazon.com/kinesis/data-firehose/).
@@ -145,6 +147,9 @@ See the [osquery logging documentation](https://osquery.readthedocs.io/en/stable
 
 If `--logger_plugin=tls` is used with osquery clients, the following configuration can be applied on the Fleet server for handling the incoming logs.
 
-<meta name="pageOrderInSection" value="600">
+<meta name="category" value="guides">
+<meta name="authorGitHubUsername" value="rachaelshaw">
+<meta name="authorFullName" value="Rachael Shaw">
+<meta name="publishedOn" value="2023-11-02">
+<meta name="articleTitle" value="Log destinations">
 <meta name="description" value="Learn about supported log destinations in Fleet, including Amazon Kinesis, AWS Lambda Snowflake, Splunk, and more.">
-<meta name="navSection" value="Security compliance">