Docs v4.60.0 (#24197)

2024-11-27 15:21:16 -06:00
parent a5d06f70a9
commit 6fd3ebf4cf
9 changed files with 120 additions and 93 deletions
@@ -2,21 +2,19 @@

 _Available in Fleet Premium_

-In Fleet, you can enforce disk encryption for your macOS and Windows hosts. 
+In Fleet, you can enforce disk encryption for your macOS and Windows hosts, and verify disk encryption for Ubuntu Linux and Fedora Linux hosts.

-> Apple calls this [FileVault](https://support.apple.com/en-us/HT204837) and Microsoft calls this [BitLocker](https://learn.microsoft.com/en-us/windows/security/operating-system-security/data-protection/bitlocker/). 
+> Apple calls this [FileVault](https://support.apple.com/en-us/HT204837), Microsoft calls this [BitLocker](https://learn.microsoft.com/en-us/windows/security/operating-system-security/data-protection/bitlocker/), and Linux typically uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) (Linux Unified Key Setup).

-When disk encryption is enforced, hosts’ disk encryption keys will be stored in Fleet.
+When disk encryption is enforced, hosts' disk encryption keys will be stored in Fleet.

-For macOS hosts that automatically enroll, disk encryption is enforced during Setup Assistant.
-
-For Windows, disk encryption is enforced on the C: volume (default system/OS drive).
+For macOS hosts that automatically enroll, disk encryption is enforced during Setup Assistant. For Windows, disk encryption is enforced on the C: volume (default system/OS drive). On Linux, encryption requires user interaction to encrypt the device with LUKS.

 ## Enforce disk encryption

 You can enforce disk encryption using the Fleet UI, Fleet API, or [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops).

-Fleet UI:
+#### Fleet UI:

 1. In Fleet, head to the **Controls > OS settings > Disk encryption** page.

@@ -24,7 +22,9 @@ Fleet UI:

 3. Check the box next to **Turn on** and select **Save**.

-Fleet API: API documentation is [here](https://fleetdm.com/docs/rest-api/rest-api#update-disk-encryption-enforcement).
+#### Fleet API: 
+
+API documentation is [here](https://fleetdm.com/docs/rest-api/rest-api#update-disk-encryption-enforcement).

 ### Disk encryption status

@@ -42,10 +42,28 @@ In the Fleet UI, head to the **Controls > OS settings > Disk encryption** tab. Y

 * Removing enforcement (pending): the host will receive the MDM command to remove the disk encryption profile when the host comes online.

-* Failed: hosts that are failed to enforce disk encryption. 
+* Failed: hosts that failed to enforce disk encryption.

 You can click each status to view the list of hosts for that status.

+## Enforce disk encryption on Linux
+
+To enforce disk encryption on Ubuntu Linux and Fedora Linux devices, Fleet supports Linux Unified Key Setup (LUKS) for encrypting volumes.
+
+1. Share [this step-by-step guide](https://fleetdm.com/learn-more-about/encrypt-linux-device) with end users setting up a work computer running Ubuntu Linux or Fedora Linux.
+
+> Note that full disk encryption can only enabled during operating system setup. If the operating system has already been installed, the end user will be required to re-install the OS to enable disk encryption.
+
+2. Once the user encrypts the disk, Fleet will initiate a key escrow process through Fleet Desktop:
+   * Fleet Desktop prompts the user to enter their current encryption passphrase.
+   * A new encryption passphrase is generated and added as a LUKS keyslot for the encrypted volume.
+   * The new passphrase is securely stored in Fleet.
+
+3. Fleet verifies that the encryption is complete, and the key has been escrowed. Once successful, the host's status will be updated to "Verified" in the disk encryption status table.
+
+> Note: LUKS allows multiple passphrases for decrypting the volume. The original passphrase remains active along with the escrowed passphrase created by Fleet.
+
+
 ## View disk encryption key

 How to view the disk encryption key:
@@ -54,6 +72,8 @@ How to view the disk encryption key:

 2. On the **Host details** page, select **Actions > Show disk encryption key**.

+> This action is logged in the activity log for security auditing purposes.
+
 ## Migrate macOS hosts

 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.
@@ -65,4 +85,4 @@ Share [these guided instructions](https://fleetdm.com/guides/mdm-migration#how-t
 <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="description" value="Learn how to enforce disk encryption on macOS, Windows, and Linux hosts and manage encryption keys with Fleet Premium.">
@@ -0,0 +1,56 @@
+# Encrypt your Fleet-managed Linux device
+
+> This guide is intended for new device setup. If the operating system has already been installed without enabling disk encryption, you will need to re-install in order to turn on full disk encryption.
+
+
+LUKS (Linux Unified Key Setup) is a standard tool for encrypting Linux disks. It uses a "volume key" to encrypt your data, and this key is protected by passphrases. LUKS supports multiple passphrases, allowing you to securely share access or recover encrypted data. Fleet uses LUKS to ensure that only authorized users can access the data on your work computer. 
+
+Fleet securely stores a passphrase to ensure that the data on your work computer is always recoverable. To get your computer set up for key escrow, you will first need to enable disk encryption on your end, then provide your encryption passphrase to Fleet.
+
+Follow the steps below to get set up.
+
+
+## 1. Enable encryption during installation
+
+  #### Ubuntu Linux
+
+  - When installing Ubuntu, choose the option to "Use LVM with encryption."
+  - Set a strong passphrase when prompted. This passphrase will be used to encrypt your disk and is separate from your login password.
+
+  ![Ubuntu setup "How do you want to install Ubuntu?" screen](../website/assets/images/articles/ubuntu-1-1200x675@2x.png)
+  
+  ![Ubuntu setup: Advanced features > Use LVM and encryption](../website/assets/images/articles/ubuntu-2-1200x675@2x.png)
+
+  #### Fedora Linux
+
+  - During Fedora installation, under **Installation destination** > **Encryption** select the "Encrypt my data" checkbox.
+  - Enter a secure passphrase when prompted.
+
+  ![Fedora setup "Installation summary" screen](../website/assets/images/articles/fedora-1-1200x675@2x.png)
+  ![Fedora setup: Installation destination > Encryption > Encrypt my data](../website/assets/images/articles/fedora-2-1200x675@2x.png)
+
+## 2. Verify encryption
+
+  - Once installation is complete, verify that your disk is encrypted by running:
+    ```bash
+      lsblk -o NAME,MOUNTPOINT,TYPE,SIZE,FSUSED,FSTYPE,ENCRYPTED
+    ```
+  - **Ubuntu Linux**: Look for the root (`/`) partition, and confirm it is marked as encrypted.
+  - **Fedora Linux**: Ensure the `/` (root) and `/home` partitions are encrypted.
+
+## 3. Escrow your key with Fleet
+
+  - Open Fleet Desktop. If your device is encrypted, you'll see a banner prompting you to escrow the key.
+  - Click **Create key**. Enter your existing encryption passphrase when prompted.
+  - Fleet will generate and securely store a new passphrase for recovery.
+
+Now, your encryption status will update to "verified" in Fleet Desktop, meaning that your recovery key has been successfully stored.
+
+
+
+<meta name="articleTitle" value="Encrypt your Fleet-managed Linux device">
+<meta name="authorFullName" value="Rachael Shaw">
+<meta name="authorGitHubUsername" value="rachaelshaw">
+<meta name="category" value="guides">
+<meta name="publishedOn" value="2024-11-25">
+<meta name="description" value="Instructions for end users to encrypt Linux devices enrolled in Fleet.">
@@ -500,6 +500,19 @@ for pagination. For a comprehensive list of activity types and detailed informat
        "status": "failed_install"
      }
    },
+    {
+      "created_at": "2021-07-29T14:40:27Z",
+      "id": 21,
+      "actor_full_name": "name",
+      "actor_id": 1,
+      "actor_gravatar": "",
+      "actor_email": "name@example.com",
+      "type": "created_team",
+      "details": {
+        "team_id": 2,
+        "team_name": "Apples"
+      }
+    },
    {
      "created_at": "2021-07-30T13:41:07Z",
      "id": 24,
@@ -541,80 +554,6 @@ for pagination. For a comprehensive list of activity types and detailed informat
        "team_name": "Oranges"
      }
    },
-    {
-      "created_at": "2021-07-29T14:40:27Z",
-      "id": 21,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "created_team",
-      "details": {
-        "team_id": 2,
-        "team_name": "Apples"
-      }
-    },
-    {
-      "created_at": "2021-07-27T14:35:08Z",
-      "id": 20,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "created_pack",
-      "details": {
-        "pack_id": 2,
-        "pack_name": "New pack"
-      }
-    },
-    {
-      "created_at": "2021-07-27T13:25:21Z",
-      "id": 19,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "live_query",
-      "details": {
-        "targets_count": 14
-      }
-    },
-    {
-      "created_at": "2021-07-27T13:25:14Z",
-      "id": 18,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "live_query",
-      "details": {
-        "targets_count": 14
-      }
-    },
-    {
-      "created_at": "2021-07-26T19:28:24Z",
-      "id": 17,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "live_query",
-      "details": {
-        "target_counts": 1
-      }
-    },
-    {
-      "created_at": "2021-07-26T17:27:37Z",
-      "id": 16,
-      "actor_full_name": "name",
-      "actor_id": 1,
-      "actor_gravatar": "",
-      "actor_email": "name@example.com",
-      "type": "live_query",
-      "details": {
-        "target_counts": 14
-      }
-    },
    {
      "created_at": "2021-07-26T17:27:08Z",
      "id": 15,
@@ -2543,11 +2482,13 @@ the `software` table.
 | bootstrap_package       | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. |
 | os_settings          | string  | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** |
 | os_settings_disk_encryption | string | query | Filters the hosts by the status of the disk encryption setting applied to the hosts. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'.  **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** |
-| populate_software     | boolean | query | If `true`, the response will include a list of installed software for each host, including vulnerability data. (Note that software lists can be large, so this may cause significant CPU and RAM usage depending on page size and request concurrency.) |
+| populate_software     | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. |
 | populate_policies     | boolean | query | If `true`, the response will include policy data for each host. |

 > `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead.

+> `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host.
+
 If `software_title_id` is specified, an additional top-level key `"software_title"` is returned with the software title object corresponding to the `software_title_id`. See [List software](#list-software) response payload for details about this object.

 If `software_version_id` is specified, an additional top-level key `"software"` is returned with the software object corresponding to the `software_version_id`. See [List software versions](#list-software-versions) response payload for details about this object.
@@ -5729,12 +5670,12 @@ Get aggregate disk encryption status counts of macOS and Windows hosts enrolled

 ```json
 {
-  "verified": {"macos": 123, "windows": 123},
-  "verifying": {"macos": 123, "windows": 0},
-  "action_required": {"macos": 123, "windows": 0},
-  "enforcing": {"macos": 123, "windows": 123},
-  "failed": {"macos": 123, "windows": 123},
-  "removing_enforcement": {"macos": 123, "windows": 0},
+  "verified": {"macos": 123, "windows": 123, "linux": 13},
+  "verifying": {"macos": 123, "windows": 0, "linux": 0},
+  "action_required": {"macos": 123, "windows": 0, "linux": 37},
+  "enforcing": {"macos": 123, "windows": 123, "linux": 0},
+  "failed": {"macos": 123, "windows": 123, "linux": 0},
+  "removing_enforcement": {"macos": 123, "windows": 0, "linux": 0}
 }
 ```

@@ -7656,6 +7597,9 @@ Returns a list of global queries or team queries.
 | team_id         | integer | query | _Available in Fleet Premium_. The ID of the parent team for the queries to be listed. When omitted, returns global queries.                  |
 | query           | string  | query | Search query keywords. Searchable fields include `name`.                                                                      |
 | merge_inherited | boolean | query | _Available in Fleet Premium_. If `true`, will include global queries in addition to team queries when filtering by `team_id`. (If no `team_id` is provided, this parameter is ignored.) |
+| compatible_platform | string | query | Return queries that only reference tables compatible with this platform (not a strict compatibility check). One of: `"macos"`, `"windows"`, `"linux"`, `"chrome"` (case-insensitive). |
+| page                    | integer | query | Page number of the results to fetch. |
+| per_page                | integer | query | Results per page. |

 #### Example

@@ -7744,7 +7688,12 @@ Returns a list of global queries or team queries.
        "total_executions": null
      }
    }
-  ]
+  ],
+  "meta": {
+    "has_next_results": true,
+    "has_previous_results": false
+  },
+  "count": 200
 }
 ```

@@ -9367,6 +9316,7 @@ Returns information about the specified software. By default, `versions` are sor
      }
    },
    "app_store_app": null,
+    "counts_updated_at": "2024-11-03T22:39:36Z",
    "source": "apps",
    "browser": "",
    "hosts_count": 48,
@@ -377,7 +377,7 @@
 #  ║╣ ║║║╠╣ ║ ║╠╦╝║  ║╣    ║║║╚═╗╠╩╗  ║╣ ║║║║  ╠╦╝╚╦╝╠═╝ ║ ║║ ║║║║
 #  ╚═╝╝╚╝╚  ╚═╝╩╚═╚═╝╚═╝  ═╩╝╩╚═╝╩ ╩  ╚═╝╝╚╝╚═╝╩╚═ ╩ ╩   ╩ ╩╚═╝╝╚╝
 - industryName: Enforce disk encryption
-  description: Encrypt system drives on macOS, Windows, and Linux (coming soon) computers, manage escrowed encryption keys, and report on disk encryption status (FileVault, BitLocker, LUKS).
+  description: Encrypt system drives on macOS, Windows, and Linux, manage escrowed encryption keys, and report on disk encryption status (FileVault, BitLocker, LUKS).
  documentationUrl: https://fleetdm.com/docs/using-fleet/mdm-disk-encryption
  friendlyName: Ensure hard disks are encrypted
  productCategories: [Device management]
@@ -610,6 +610,7 @@ module.exports.routes = {
  'GET /learn-more-about/policy-automation-run-script': '/guides/policy-automation-run-script',
  'GET /learn-more-about/installing-fleetctl': '/guides/fleetctl#installing-fleetctl',
  'GET /learn-more-about/mdm-disk-encryption': '/guides/enforce-disk-encryption',
+  'GET /learn-more-about/encrypt-linux-device': '/guides/linux-disk-encryption-end-user',
  'GET /contribute-to/policies': 'https://github.com/fleetdm/fleet/edit/main/docs/01-Using-Fleet/standard-query-library/standard-query-library.yml',

  // Sitemap