From 67e178482cd0427fa6c8c4623834ac840d96277f Mon Sep 17 00:00:00 2001 From: spokanemac Date: Thu, 19 Sep 2024 11:11:42 -0700 Subject: [PATCH 1/8] Article deploy software packages --- articles/deploy-security-agents.md | 140 +++++++++++++++++++++-------- 1 file changed, 103 insertions(+), 37 deletions(-) diff --git a/articles/deploy-security-agents.md b/articles/deploy-security-agents.md index 20d6cd28abec..9baa09fd0a28 100644 --- a/articles/deploy-security-agents.md +++ b/articles/deploy-security-agents.md @@ -1,97 +1,163 @@ -# Deploy security agents +# Deploy software packages -![Deploy security agents](../website/assets/images/articles/deploy-security-agents-1600x900@2x.png) +![Deploy software](../website/assets/images/articles/deploy-security-agents-1600x900@2x.png) -Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) introduced the ability to upload and deploy security agents to your hosts. Beyond a [bootstrap package](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) at enrollment, deploying security agents allows you to specify and verify device configuration using a pre-enrollment osquery query and customization of the install and post-install scripts, allowing for key and license deployment and configuration. This guide will walk you through the steps to upload, configure, and install a security agent to hosts in your fleet. +Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) introduced the ability to upload and deploy software to your hosts. Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0) added the ability to include an uninstall script and edit software details. Beyond a [bootstrap package](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) at enrollment, deploying software allows you to specify and verify device configuration using a pre-install query and customization of the install, post-install, and uninstall scripts, allowing for key and license deployment and configuration. Admins can modify these options and settings after the initial upload. This guide will walk you through the steps to upload, configure, install, and uninstall a software package to hosts in your fleet. ## Prerequisites -* Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0). +* Fleet [v4.57.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.57.0). + * `fleetd` 1.25.0 deployed via MDM or built with the `--scripts-enabled` flag. + * An S3 bucket [configured](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket) to store the installers. + * Increase any load balancer timeouts to at least 5 minutes for the following endpoints: + * [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software). + * [Batch-apply software](https://fleetdm.com/docs/rest-api/rest-api#add-software). ## Step-by-step instructions -### Access security agent installers +### Access software packages -To access and manage security agents in Fleet: +To access and manage software in Fleet: * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. + * **Select a team**: Click on the dropdown at the top left of the page. + * **Find your software**: using the filters on the top of the table, you can choose between: + * “Available for install” filters software that can be installed on your hosts. + * “Self-service” filters software that end users can install from Fleet Desktop. -* **Select security agent installer**: Click on a software package to view details and access additional actions for the agent installer. -### Add a security agent to a team +* **Select software package**: Click on a software package to view details and access additional actions for the software. + +### Add a software package to a team * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a security agent. -> Security agents cannot be added to "All teams" +* **Select a team**: Select a team or the "No team" team to add a software package. + +> Software cannot be added to "All teams." * Click the “Add Software” button in the top right corner, and a modal will appear. + * Choose a file to upload. `.pkg`, `.msi`, `.exe`, or `.deb` files are supported. -* After selecting a file, a default install script will be pre-filled. If the security agent requires a custom installation process, this script can be edited. + * To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. + * To customize the conditions, click on “Advanced options”: - * **Pre-install condition**: A pre-install condition is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. - * **Post-install script** A post-install script will run after the installation is complete, allowing you to configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. -### Install a security agent on a host + * **Pre-install query**: A pre-install query is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. -After an installer is added to a team, it can be installed on hosts via the UI. + * **Install script**: After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process, this script can be edited. Learn more about [install scripts](https://fleetdm.com/learn-more-about/install-scripts). + + * **Post-install script** A post-install script will run after the installation, allowing you to configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. + + * **Uninstall script** An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. Learn more about [uninstall scripts](https://fleetdm.com/learn-more-about/uninstall-scripts). + +> After the initial package upload, all of these options, including the self-service setting, pre-install query, scripts, and even the software file, can be modified. + +### Install a software package on a host + +After a software package is added to a team, it can be installed on hosts via the UI. * **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. -* **Navigate to the Host details page**: Click the host you want to install the security agent. -* **Navigate to the Host software tab**: In the host details, search for the tab named “Software” -* **Find your security agent**: Use the search bar and filters to search for your security agent. -* **Install the security agent on the host**: In the leftmost row of the table, click on “Actions” > “Install.” + +* **Navigate to the Host details page**: Click the host you want to install the software package. + +* **Navigate to the Host software tab**: In the host details, search for the tab named “Software.” + +* **Find your software package**: Use the dropdown to select software “Available for install” or use the search bar to search for your software package by name. + +* **Install the software package on the host**: In the rightmost column of the table, click on “Actions” > “Install.” Installation will happen automatically or when the host comes online. + * **Track installation status**: by either - * Checking the “Install status” in the host software table. + + * Checking the status column in the host software table. + * Navigate to the “Details” tab on the host details page and check the activity log. -### Edit a security agent +### Edit a software package -Security agent installers can’t be edited via the UI. To modify an installer, remove it from the UI and add a new one. +* **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -### Remove a security agent from a team +* **Select a team**: Select a team or the "No team" team to add a software package. + +* **Find your software**: using the filters on the top of the table, you can choose between: + + * “Available for install” filters software can be installed on your hosts. + + * “Self-service” filters software that users can install from Fleet Desktop. + +* **Select software package**: Click on a software package to view details. + +* **Edit software package**: From the Actions menu, select "Edit." + +> If a new software package is uploaded, all software statuses and their respective counts will reset. Editing the pre-install query, install script, post-install script, or uninstall script will reset all pending installations and uninstallations. + +### Uninstall a software package on a host + +After a software package is installed on a host, it can be uninstalled on the host via the UI. + +* **Navigate to the Hosts page**: Click on the "Hosts" tab in the main navigation menu. + +* **Navigate to the Host details page**: Click the host you want to uninstall the software package. + +* **Navigate to the Host software tab**: In the host details, search for the tab named “Software.” + +* **Find your software package**: Use the dropdown to select software “Available for install” or use the search bar to search for your software package by name. + +* **Uninstall the software package from the host**: In the rightmost column of the table, click on “Actions” > “Uninstall.” Uninstallation will happen automatically or when the host comes online. + +* **Track uninstallation status**: by either + + * Checking the status column in the host software table. + + * Navigate to the “Details” tab on the host details page and check the activity log. + +### Remove a software package from a team * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a security agent. + +* **Select a team**: Select a team or the "No team" team to add a software package. + * **Find your software**: using the filters on the top of the table, you can choose between: + * “Available for install” filters software can be installed on your hosts. + * “Self-service” filters software that users can install from Fleet Desktop. -* **Select security agent installer**: Click on a software package to view details. -* **Remove security agent installer**: From the Actions menu, select "Delete." Click the "Delete" button on the modal. -> Removing a security agent from a team will not uninstall the agent from the existing host(s). +* **Select software package**: Click on a software package to view details. -### Manage security agents with the REST API +* **Remove software package**: From the Actions menu, select "Delete." Click the "Delete" button on the modal. -Fleet also provides a REST API for managing software programmatically. The API allows you to add, update, retrieve, list, and delete software. Detailed documentation on Fleet's [REST API is available](https://fleetdm.com/docs/rest-api/rest-api#software). +> Removing a software package from a team will not uninstall the software from the existing host(s). -### Manage security agents with GitOps +### Manage software with the REST API -Installers for security agents can be managed via `fleetctl` using [GitOps](https://fleetdm.com/docs/using-fleet/gitops). +Fleet also provides a REST API for managing software programmatically. The API allows you to add, update, retrieve, list, and delete software. Detailed documentation on Fleet's [REST API is available]([https://fleetdm.com/docs/rest-api/rest-api#software](https://fleetdm.com/docs/rest-api/rest-api#software)), including endpoints for installing and uninstalling packages. -Please refer to the documentation specific to [managing software with GitOps](https://fleetdm.com/docs/using-fleet/gitops#software). For a real-world example, [see how we manage software at Fleet](https://github.com/fleetdm/fleet/tree/main/it-and-security/teams). +### Manage software with GitOps +Software packages can be managed via `fleetctl` using [GitOps](https://fleetdm.com/docs/using-fleet/gitops). -## Conclusion +Please refer to the documentation for [managing software with GitOps](https://fleetdm.com/docs/using-fleet/gitops#software), for a real-world example, [see how we manage software at Fleet](https://github.com/fleetdm/fleet/tree/main/it-and-security/teams). -Deploying security agents with Fleet is straightforward and ensures your hosts are protected with the latest security measures. This guide has shown you how to access, add, and install security agents, as well as manage them using the REST API and `fleetctl`. Following these steps can effectively equip your fleet with the necessary security tools. +## Conclusion -See Fleet's [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides) for more details on advanced setups, software features, and vulnerability detection. +Managing software with Fleet is straightforward and ensures your hosts are equipped with the latest tools. This guide has outlined how to access, add, edit, and remove software packages from a team, install and uninstall from specific hosts, and use the REST API and `fleetctl` to manage software packages. You can effectively maintain software packages across your fleet by following these steps. +For more information on advanced setups and features, explore Fleet’s [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides). - + - + From b8fa2a64f69e9fc8849a185fe6f37df3bc2f249d Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Fri, 20 Sep 2024 17:40:26 -0500 Subject: [PATCH 2/8] Flesh out new software features * Added note about fleetd 1.33 for better uninstall-on-failed-install handling * Drop load balancer call-out for batch apply now that we handle that async * Call out that software packages are managed by team, and add example use cases on why * Misc. consistency/grammar fixes (incl. overlooked oblique references to security agents) * Clarify side effects on package edit/remove * Call out that when managing via GitOps the Fleet server, not the GitOps runner, is the one to pull packages, in case people need to set their firewalls accordingly * Bump publish date since this is basically a fresh guide with URL backward compat --- articles/deploy-security-agents.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/articles/deploy-security-agents.md b/articles/deploy-security-agents.md index 9baa09fd0a28..27e6a7b21ada 100644 --- a/articles/deploy-security-agents.md +++ b/articles/deploy-security-agents.md @@ -10,14 +10,14 @@ Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) int * `fleetd` 1.25.0 deployed via MDM or built with the `--scripts-enabled` flag. +> `fleetd` prior to 1.33.0 will use a hard-coded uninstall script to clean up from a failed install. As of 1.33.0, the (default or customized) uninstall script will be used to clean up failed installs. + * An S3 bucket [configured](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket) to store the installers. * Increase any load balancer timeouts to at least 5 minutes for the following endpoints: * [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software). - * [Batch-apply software](https://fleetdm.com/docs/rest-api/rest-api#add-software). - ## Step-by-step instructions ### Access software packages @@ -28,6 +28,8 @@ To access and manage software in Fleet: * **Select a team**: Click on the dropdown at the top left of the page. +> Software packages are tied to a specific team. This allows you to, for example, test a newer release of an application within your IT team before rolling it out to the rest of your organization, or deploy the appropriate architecture-specific installer to both Intel and Apple Silicon Macs. + * **Find your software**: using the filters on the top of the table, you can choose between: * “Available for install” filters software that can be installed on your hosts. @@ -44,9 +46,9 @@ To access and manage software in Fleet: > Software cannot be added to "All teams." -* Click the “Add Software” button in the top right corner, and a modal will appear. +* Click the “Add Software” button in the top right corner, and a dialog will appear. -* Choose a file to upload. `.pkg`, `.msi`, `.exe`, or `.deb` files are supported. +* Choose a file to upload. `.pkg`, `.msi`, `.exe`, and `.deb` files are supported. * To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. @@ -56,11 +58,11 @@ To access and manage software in Fleet: * **Install script**: After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process, this script can be edited. Learn more about [install scripts](https://fleetdm.com/learn-more-about/install-scripts). - * **Post-install script** A post-install script will run after the installation, allowing you to configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. + * **Post-install script** A post-install script will run after the installation, allowing you to, for example, configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. * **Uninstall script** An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. Learn more about [uninstall scripts](https://fleetdm.com/learn-more-about/uninstall-scripts). -> After the initial package upload, all of these options, including the self-service setting, pre-install query, scripts, and even the software file, can be modified. +> After the initial package upload, all of these options, including the self-service setting, pre-install query, scripts, and even the software package file, can be modified. ### Install a software package on a host @@ -86,7 +88,7 @@ After a software package is added to a team, it can be installed on hosts via th * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a software package. +* **Select a team**: Select a team (or "No team") to switch to the team whose software you want to edit. * **Find your software**: using the filters on the top of the table, you can choose between: @@ -98,7 +100,7 @@ After a software package is added to a team, it can be installed on hosts via th * **Edit software package**: From the Actions menu, select "Edit." -> If a new software package is uploaded, all software statuses and their respective counts will reset. Editing the pre-install query, install script, post-install script, or uninstall script will reset all pending installations and uninstallations. +> Editing the pre-install query, install script, post-install script, or uninstall script cancels all pending installations and uninstallations for that package, except for installs and uninstalls that are currently running on a host. If a new software package is uploaded, in addition to cancelling pending installs and uninstalls, host counts (for installs, as well as pending and failed installs and uninstalls) will be reset to zero, so counts reflect the currently uploaded version of the package. ### Uninstall a software package on a host @@ -124,7 +126,7 @@ After a software package is installed on a host, it can be uninstalled on the ho * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a software package. +* **Select a team**: Select a team (or "No team") to switch to the team whose software you want to remove. * **Find your software**: using the filters on the top of the table, you can choose between: @@ -134,9 +136,9 @@ After a software package is installed on a host, it can be uninstalled on the ho * **Select software package**: Click on a software package to view details. -* **Remove software package**: From the Actions menu, select "Delete." Click the "Delete" button on the modal. +* **Remove software package**: From the Actions menu, select "Delete." Click the "Delete" button on the dialog. -> Removing a software package from a team will not uninstall the software from the existing host(s). +> Removing a software package from a team will cancel pending installs for hosts that are not in the middle of installing the software, but will not uninstall the software from hosts where it is already installed. ### Manage software with the REST API @@ -148,6 +150,8 @@ Software packages can be managed via `fleetctl` using [GitOps](https://fleetdm.c Please refer to the documentation for [managing software with GitOps](https://fleetdm.com/docs/using-fleet/gitops#software), for a real-world example, [see how we manage software at Fleet](https://github.com/fleetdm/fleet/tree/main/it-and-security/teams). +> When managing software installers via GitOps, the Fleet server receiving GitOps requests (**not** the machine running fleetctl as part of the GitOps workflow) will download installers from the specified URLs directly. + ## Conclusion Managing software with Fleet is straightforward and ensures your hosts are equipped with the latest tools. This guide has outlined how to access, add, edit, and remove software packages from a team, install and uninstall from specific hosts, and use the REST API and `fleetctl` to manage software packages. You can effectively maintain software packages across your fleet by following these steps. @@ -158,6 +162,6 @@ For more information on advanced setups and features, explore Fleet’s [documen - + From 740b4536eb68e1d7293cb24a2284dccf2dd46f3f Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Sun, 22 Sep 2024 16:31:16 -0500 Subject: [PATCH 3/8] Add learn-more-about routes, rename article + add redirect from old name, expand install advanced options into headings --- ...-agents.md => deploy-software-packages.md} | 28 +++++++++++-------- website/config/routes.js | 4 +++ 2 files changed, 21 insertions(+), 11 deletions(-) rename articles/{deploy-security-agents.md => deploy-software-packages.md} (84%) diff --git a/articles/deploy-security-agents.md b/articles/deploy-software-packages.md similarity index 84% rename from articles/deploy-security-agents.md rename to articles/deploy-software-packages.md index 27e6a7b21ada..846903d8f45c 100644 --- a/articles/deploy-security-agents.md +++ b/articles/deploy-software-packages.md @@ -14,9 +14,7 @@ Fleet [v4.50.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.50.0) int * An S3 bucket [configured](https://fleetdm.com/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket) to store the installers. -* Increase any load balancer timeouts to at least 5 minutes for the following endpoints: - - * [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software). +* Increase any load balancer timeouts to at least 5 minutes for the [Add software](https://fleetdm.com/docs/rest-api/rest-api#add-software) endpoint. ## Step-by-step instructions @@ -42,7 +40,7 @@ To access and manage software in Fleet: * **Navigate to the Software page**: Click on the "Software" tab in the main navigation menu. -* **Select a team**: Select a team or the "No team" team to add a software package. +* **Select a team**: Select a team "No team" to add a software package. > Software cannot be added to "All teams." @@ -52,17 +50,25 @@ To access and manage software in Fleet: * To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. -* To customize the conditions, click on “Advanced options”: +* To customize installer behavior, click on “Advanced options.” + +> After the initial package upload, all options, including the self-service setting, pre-install query, scripts, and even the software package file, can be modified. When replacing an installer package, the replacement package must be the same type, and be for the same software, as the original package. + +#### Pre-install query + +A pre-install query is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. + +#### Install script - * **Pre-install query**: A pre-install query is a valid osquery SQL statement that will be evaluated on the host before installing the software. If provided, the installation will proceed only if the query returns any value. +After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process, this script can be edited. - * **Install script**: After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process, this script can be edited. Learn more about [install scripts](https://fleetdm.com/learn-more-about/install-scripts). +#### Post-install script - * **Post-install script** A post-install script will run after the installation, allowing you to, for example, configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. +A post-install script will run after the installation, allowing you to, for example, configure the security agent right after installation. If this script returns a non-zero exit code, the installation will fail, and `fleetd` will attempt to uninstall the software. - * **Uninstall script** An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. Learn more about [uninstall scripts](https://fleetdm.com/learn-more-about/uninstall-scripts). +#### Uninstall script -> After the initial package upload, all of these options, including the self-service setting, pre-install query, scripts, and even the software package file, can be modified. +An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page, or if an install fails for hosts running `fleetd` 1.33.0 or later. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. ### Install a software package on a host @@ -162,6 +168,6 @@ For more information on advanced setups and features, explore Fleet’s [documen - + diff --git a/website/config/routes.js b/website/config/routes.js index 2252a7072945..97e35b35ab10 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -324,6 +324,7 @@ module.exports.routes = { 'GET /use-cases/get-and-stay-compliant-across-your-devices-with-fleet': '/securing/get-and-stay-compliant-across-your-devices-with-fleet', 'GET /use-cases/import-and-export-queries-and-packs-in-fleet': '/guides/import-and-export-queries-and-packs-in-fleet', 'GET /guides/import-and-export-queries-and-packs-in-fleet': '/guides/import-and-export-queries-in-fleet', + 'GET /guides/deploy-security-agents': '/guides/deploy-software-packages', 'GET /use-cases/locate-assets-with-osquery': '/guides/locate-assets-with-osquery', 'GET /use-cases/osquery-a-tool-to-easily-ask-questions-about-operating-systems': '/guides/osquery-a-tool-to-easily-ask-questions-about-operating-systems', 'GET /use-cases/osquery-consider-joining-against-the-users-table': '/guides/osquery-consider-joining-against-the-users-table', @@ -560,6 +561,9 @@ module.exports.routes = { 'GET /learn-more-about/uninstall-fleetd': '/docs/using-fleet/faq#how-can-i-uninstall-fleetd', 'GET /learn-more-about/vulnerability-processing': '/docs/using-fleet/vulnerability-processing', 'GET /learn-more-about/s3-bootstrap-package': '/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket', + 'GET /learn-more-about/exe-install-scripts': 'https://github.com/fleetdm/fleet/issues/20000', + 'GET /learn-more-about/install-scripts': '/guides/deploy-software-packages#install-script', + 'GET /learn-more-about/uninstall-scripts': '/guides/deploy-software-packages#uninstall-script', // Sitemap // ============================================================================================================= From 54a07e384ca4adb7514ff47459bd5a7882a9e9d3 Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Sun, 22 Sep 2024 16:39:35 -0500 Subject: [PATCH 4/8] Mention EXE installers in install script doc --- articles/deploy-software-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md index 846903d8f45c..24449697c640 100644 --- a/articles/deploy-software-packages.md +++ b/articles/deploy-software-packages.md @@ -60,7 +60,7 @@ A pre-install query is a valid osquery SQL statement that will be evaluated on t #### Install script -After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process, this script can be edited. +After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. #### Post-install script From 92e3827a858b3dc8c876dec92791707e8826e7a9 Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Sun, 22 Sep 2024 17:31:23 -0500 Subject: [PATCH 5/8] Resolve learn-more-about version number extraction link to quick description in deploy-software-packages article --- articles/deploy-software-packages.md | 2 ++ website/config/routes.js | 1 + 2 files changed, 3 insertions(+) diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md index 24449697c640..29cafe63b282 100644 --- a/articles/deploy-software-packages.md +++ b/articles/deploy-software-packages.md @@ -48,6 +48,8 @@ To access and manage software in Fleet: * Choose a file to upload. `.pkg`, `.msi`, `.exe`, and `.deb` files are supported. +> Software installer uploads will fail if Fleet is unable to extract information from the installer package such bundle ID and version number. + * To allow users to install the software from Fleet Desktop, check the “Self-service” checkbox. * To customize installer behavior, click on “Advanced options.” diff --git a/website/config/routes.js b/website/config/routes.js index 97e35b35ab10..3a2010d51aae 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -564,6 +564,7 @@ module.exports.routes = { 'GET /learn-more-about/exe-install-scripts': 'https://github.com/fleetdm/fleet/issues/20000', 'GET /learn-more-about/install-scripts': '/guides/deploy-software-packages#install-script', 'GET /learn-more-about/uninstall-scripts': '/guides/deploy-software-packages#uninstall-script', + 'GET /learn-more-about/read-package-version': '/guides/deploy-software-packages##add-a-software-package-to-a-team', // Sitemap // ============================================================================================================= From 91f88e274d6ae3e0ba34a95391f40cd9c83a2d60 Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Mon, 23 Sep 2024 00:47:27 -0500 Subject: [PATCH 6/8] Add details on install/uninstall script environment variables/substitutions --- articles/deploy-software-packages.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md index 29cafe63b282..01c01b0a71a7 100644 --- a/articles/deploy-software-packages.md +++ b/articles/deploy-software-packages.md @@ -62,7 +62,7 @@ A pre-install query is a valid osquery SQL statement that will be evaluated on t #### Install script -After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. +After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. When the script is run, the `$INSTALLER_PATH` environment variable will be set by `fleetd` to where the installer is being run from. #### Post-install script @@ -72,6 +72,8 @@ A post-install script will run after the installation, allowing you to, for exam An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page, or if an install fails for hosts running `fleetd` 1.33.0 or later. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. +In addition to the `$INSTALLER_PATH` environment variable supported by install scripts, you can use `$PACKAGE_ID` in uninstall scripts as a placeholder for the package IDs (for .pkg files), package name (for Linux installers), product code (for MSIs), or software name (for EXE installers). `$PACKAGE_ID` will be substituted on upload by the Fleet server. + ### Install a software package on a host After a software package is added to a team, it can be installed on hosts via the UI. From 2eb23ae2b8f427291751556b1c91009a83c56dcc Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Mon, 23 Sep 2024 09:50:01 -0500 Subject: [PATCH 7/8] Update EXE install scripts redirect to hit the article in #22179 --- website/config/routes.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/config/routes.js b/website/config/routes.js index 3a2010d51aae..788fec39348f 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -561,7 +561,7 @@ module.exports.routes = { 'GET /learn-more-about/uninstall-fleetd': '/docs/using-fleet/faq#how-can-i-uninstall-fleetd', 'GET /learn-more-about/vulnerability-processing': '/docs/using-fleet/vulnerability-processing', 'GET /learn-more-about/s3-bootstrap-package': '/docs/configuration/fleet-server-configuration#s-3-software-installers-bucket', - 'GET /learn-more-about/exe-install-scripts': 'https://github.com/fleetdm/fleet/issues/20000', + 'GET /learn-more-about/exe-install-scripts': '/guides/exe-install-scripts', 'GET /learn-more-about/install-scripts': '/guides/deploy-software-packages#install-script', 'GET /learn-more-about/uninstall-scripts': '/guides/deploy-software-packages#uninstall-script', 'GET /learn-more-about/read-package-version': '/guides/deploy-software-packages##add-a-software-package-to-a-team', From 9854e48c7bcf9b9c2c95db781b5a15ecf43a390b Mon Sep 17 00:00:00 2001 From: JD Date: Mon, 23 Sep 2024 07:58:48 -0700 Subject: [PATCH 8/8] Minor grammar changes. --- articles/deploy-software-packages.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md index 01c01b0a71a7..92aa0901ccf1 100644 --- a/articles/deploy-software-packages.md +++ b/articles/deploy-software-packages.md @@ -54,7 +54,7 @@ To access and manage software in Fleet: * To customize installer behavior, click on “Advanced options.” -> After the initial package upload, all options, including the self-service setting, pre-install query, scripts, and even the software package file, can be modified. When replacing an installer package, the replacement package must be the same type, and be for the same software, as the original package. +> After the initial package upload, all options can be modified, including the self-service setting, pre-install query, scripts, and even the software package file. When replacing an installer package, the replacement package must be the same type and for the same software as the original package. #### Pre-install query @@ -62,7 +62,7 @@ A pre-install query is a valid osquery SQL statement that will be evaluated on t #### Install script -After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. When the script is run, the `$INSTALLER_PATH` environment variable will be set by `fleetd` to where the installer is being run from. +After selecting a file, a default install script will be pre-filled. If the software package requires a custom installation process (for example, if [an EXE-based Windows installer requires custom handling](https://fleetdm.com/learn-more-about/exe-install-scripts)), this script can be edited. When the script is run, the `$INSTALLER_PATH` environment variable will be set by `fleetd` to where the installer is being run. #### Post-install script @@ -72,7 +72,7 @@ A post-install script will run after the installation, allowing you to, for exam An uninstall script will run when an admin chooses to uninstall the software from the host on the host details page, or if an install fails for hosts running `fleetd` 1.33.0 or later. Like the install script, a default uninstall script will be pre-filled after selecting a file. This script can be edited if the software package requires a custom uninstallation process. -In addition to the `$INSTALLER_PATH` environment variable supported by install scripts, you can use `$PACKAGE_ID` in uninstall scripts as a placeholder for the package IDs (for .pkg files), package name (for Linux installers), product code (for MSIs), or software name (for EXE installers). `$PACKAGE_ID` will be substituted on upload by the Fleet server. +In addition to the `$INSTALLER_PATH` environment variable supported by install scripts, you can use `$PACKAGE_ID` in uninstall scripts as a placeholder for the package IDs (for .pkg files), package name (for Linux installers), product code (for MSIs), or software name (for EXE installers). The Fleet server will substitute `$PACKAGE_ID` on upload. ### Install a software package on a host @@ -110,7 +110,7 @@ After a software package is added to a team, it can be installed on hosts via th * **Edit software package**: From the Actions menu, select "Edit." -> Editing the pre-install query, install script, post-install script, or uninstall script cancels all pending installations and uninstallations for that package, except for installs and uninstalls that are currently running on a host. If a new software package is uploaded, in addition to cancelling pending installs and uninstalls, host counts (for installs, as well as pending and failed installs and uninstalls) will be reset to zero, so counts reflect the currently uploaded version of the package. +> Editing the pre-install query, install script, post-install script, or uninstall script cancels all pending installations and uninstallations for that package, except for installs and uninstalls that are currently running on a host. If a new software package is uploaded, in addition to canceling pending installs and uninstalls, host counts (for installs and pending and failed installs and uninstalls) will be reset to zero, so counts reflect the currently uploaded version of the package. ### Uninstall a software package on a host @@ -148,7 +148,7 @@ After a software package is installed on a host, it can be uninstalled on the ho * **Remove software package**: From the Actions menu, select "Delete." Click the "Delete" button on the dialog. -> Removing a software package from a team will cancel pending installs for hosts that are not in the middle of installing the software, but will not uninstall the software from hosts where it is already installed. +> Removing a software package from a team will cancel pending installs for hosts that are not in the middle of installing the software but will not uninstall the software from hosts where it is already installed. ### Manage software with the REST API @@ -164,7 +164,7 @@ Please refer to the documentation for [managing software with GitOps](https://fl ## Conclusion -Managing software with Fleet is straightforward and ensures your hosts are equipped with the latest tools. This guide has outlined how to access, add, edit, and remove software packages from a team, install and uninstall from specific hosts, and use the REST API and `fleetctl` to manage software packages. You can effectively maintain software packages across your fleet by following these steps. +Managing software with Fleet is straightforward and ensures your hosts are equipped with the latest tools. This guide has outlined how to access, add, edit, and remove software packages from a team, install and uninstall from specific hosts, and use the REST API and `fleetctl` to manage software packages. By following these steps, you can effectively maintain software packages across your fleet. For more information on advanced setups and features, explore Fleet’s [documentation](https://fleetdm.com/docs/using-fleet) and additional [guides](https://fleetdm.com/guides).