diff --git a/defender-endpoint/linux-custom-path-installation.md b/defender-endpoint/linux-custom-path-installation.md new file mode 100644 index 0000000000..dd2d5666ca --- /dev/null +++ b/defender-endpoint/linux-custom-path-installation.md @@ -0,0 +1,130 @@ +--- +title: Enable deployment of MDE at custom installation path +description: Describes how to deploy Microsoft Defender for Endpoint on Linux to a custom installation path instead of the default location. +ms.service: defender-endpoint +ms.author: ewalsh +author: emmwalshh +ms.reviewer: gopkr +ms.localizationpriority: medium +manager: deniseb +audience: ITPro +ms.collection: +- m365-security +- tier3 +- mde-linux +ms.topic: install-set-up-deploy +ms.subservice: linux +search.appverid: met150 +ms.date: 08/05/2025 +--- + +# Enable deployment of MDE at custom installation path + +[!INCLUDE [Microsoft Defender XDR rebranding](../includes/microsoft-defender.md)] + +**Applies to:** + +- Microsoft Defender for Endpoint for servers + +> Want to experience Defender for Endpoint? [Sign up for a free trial.](https://go.microsoft.com/fwlink/p/?linkid=2225630&clcid=0x409&culture=&country=us) + +## Introduction + +Microsoft Defender for Endpoint (MDE) on Linux now supports installation to custom paths, allowing organizations to deploy the agent to non-standard locations based on their specific requirements. This feature is particularly useful for environments with: + +- Custom directory structures and organizational policies +- Limited space on the root filesystem +- Specific compliance requirements for application placement +- Multi-tenant environments requiring isolation +- Specialized storage configurations + +By default, MDE installs to the standard system path (`/opt/microsoft/mdatp`). With custom path installation, you can specify an alternative base directory while maintaining the same relative directory structure and functionality. + +## Prerequisites and System Requirements + +Before deploying MDE to a custom path, ensure the following requirements are met: + +### Prerequisites +- The custom installation directory and its entire tree must have at least `rwxr-xr-x` (755) permissions. +- Ensure adequate disk space in the target location (minimum 2 GB, more for high-performance workloads). +- The target file system must support standard Linux file operations and permissions. +- If SELinux is enabled, the `semanage` tool must be installed to set the correct file context for the custom installation path. + +### Supported Distributions and Feature Availability + +Custom path installation is supported on all [supported Linux distributions](mde-linux-prerequisites.md#supported-linux-distributions) for both x64 and ARM64 architectures. + +> **Note:** The custom installation path feature is available starting from version **101.25062.0003** of Microsoft Defender for Endpoint on Linux. + +## Steps for Installing to a Custom Path + +This section describes only the extra steps needed for custom path installation: + +- **Manual installation**: Perform the following additional setup steps before running the standard manual installation commands described in [linux-install-manually.md](linux-install-manually.md). +- **Installer script**: Add the `--install-path /your/custom/path` parameter. See [installer script deployment guide](linux-installer-script.md). + +### Manual Installation: Pre-Installation Setup + +If you need to manually install Microsoft Defender for Endpoint (MDE) to a custom (non-default) location, follow these additional steps before starting the standard installation process: + +1. **Set your custom path variable**: + + > [!NOTE] + > The custom path must be an absolute path (e.g., `/your/custom/path`). Relative paths are not supported. + + ```bash + export CUSTOM_PATH="/your/custom/path" + ``` + +2. **Create required directories and config file**: + ```bash + sudo mkdir -p "${CUSTOM_PATH}" + sudo mkdir -p /etc/opt/microsoft/mdatp + echo '{"install_path": "'${CUSTOM_PATH}'"}' | sudo tee /etc/opt/microsoft/mdatp/mde_path.json + ``` + +3. **Set permissions**: + ```bash + sudo chmod 755 "${CUSTOM_PATH}" + sudo chmod 644 /etc/opt/microsoft/mdatp/mde_path.json + ``` + +4. **Create symlink**: + ```bash + sudo ln -sf "${CUSTOM_PATH}/opt/microsoft/mdatp" /opt/microsoft/mdatp + ``` + +Then proceed with the standard installation steps for your distribution. + +## Upgrade and Maintenance + +Upgrades for MDE installed in a custom path work the same as standard installations—the installer automatically preserves your existing path and configuration. + +> [!IMPORTANT] +> Changing the installation path during an upgrade is not supported. If you need to change the installation path, you must first uninstall MDE and then reinstall it to the new location. + +## Frequently Asked Questions (FAQ) + +**Can I install MDE to any directory?** +Yes, as long as it’s an absolute path with at least 755 permissions and enough space (minimum 2 GB). + +**Can I change the MDE installation path after installation?** +No, you must uninstall and reinstall to use a different path. + +**How do I upgrade MDE in a custom path?** +Run the usual upgrade commands. Installation path stays unchanged. + +**Can I change the custom path during upgrade?** +No, installation path changes require a fresh install. + + +## See Also + +- [Prerequisites for Microsoft Defender for Endpoint on Linux](mde-linux-prerequisites.md) +- [Deploy Defender for Endpoint on Linux manually](linux-install-manually.md) +- [Use installer script based deployment to deploy Microsoft Defender for Endpoint on Linux](linux-installer-script.md) +- [Troubleshoot installation issues](linux-resources.md#log-installation-issues) +- [Configure Defender for Endpoint on Linux](linux-preferences.md) + +> [!TIP] +> Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: [Microsoft Defender for Endpoint Tech Community](https://techcommunity.microsoft.com/category/microsoft-defender-for-endpoint/discussions/microsoftdefenderatp) diff --git a/defender-endpoint/linux-deploy-defender-for-endpoint-with-chef.md b/defender-endpoint/linux-deploy-defender-for-endpoint-with-chef.md index e88d02aedc..e3ab31e9c3 100644 --- a/defender-endpoint/linux-deploy-defender-for-endpoint-with-chef.md +++ b/defender-endpoint/linux-deploy-defender-for-endpoint-with-chef.md @@ -123,7 +123,7 @@ A cookbook can be created through any of the following methods: ``` > [!NOTE] -> The installer script also supports other parameters such as channel, realtime protection, version, etc. To select from the list of available options, check help through the following command: +> The installer script also supports other parameters such as channel, realtime protection, version, custom path installation etc. To select from the list of available options, check help through the following command: >```./mde_installer.sh --help``` ### Create a cookbook by manually configuring repositories diff --git a/defender-endpoint/linux-install-manually.md b/defender-endpoint/linux-install-manually.md index d77f2d5175..c753a305bb 100644 --- a/defender-endpoint/linux-install-manually.md +++ b/defender-endpoint/linux-install-manually.md @@ -42,6 +42,7 @@ A successful deployment requires the completion of all of the following tasks: - [SLES and variants](#sles-and-variants-1) - [Ubuntu and Debian systems](#ubuntu-and-debian-systems) - [Mariner](#mariner) +- [Pre Install Setup for Custom Path Installation](#pre-install-setup-for-custom-path-installation) - [Application installation](#application-installation) - [RHEL and variants (CentOS, Fedora, Oracle Linux, Amazon Linux 2, Rocky, and Alma)](#rhel-and-variants-centos-fedora-oracle-linux-amazon-linux-2-rocky-and-alma) - [SLES and variants](#sles-and-variants) @@ -257,6 +258,13 @@ In order to preview new features and provide early feedback, it's recommended th sudo dnf config-manager --enable mariner-official-extras-preview ``` +## Pre Install Setup for Custom Path Installation + +These steps are applicable only if Defender is to be installed in a custom location. +For detailed instructions on installing Microsoft Defender for Endpoint to a custom path, see [Manual installation: Pre-installation setup](linux-custom-path-installation.md#manual-installation-pre-installation-setup). + +For details on installing to a custom path, refer: [Install Defender for Endpoint on Linux to a custom path](linux-custom-path-installation.md). + ## Application installation Use the commands in the following sections to install Defender for Endpoint on your Linux distribution. diff --git a/defender-endpoint/linux-install-with-ansible.md b/defender-endpoint/linux-install-with-ansible.md index 290419e0e8..ca1f220117 100644 --- a/defender-endpoint/linux-install-with-ansible.md +++ b/defender-endpoint/linux-install-with-ansible.md @@ -149,7 +149,7 @@ Create installation YAML file. You can also download the file directly from [Git ``` > [!NOTE] -> The installer script also supports other parameters such as channel, realtime protection, version, etc. To select from the list of available options, check help through the following command: `./mde_installer.sh --help` +> The installer script also supports other parameters such as channel, realtime protection, version, custom path installation etc. To select from the list of available options, check help through the following command: `./mde_installer.sh --help` ### Apply the playbook diff --git a/defender-endpoint/linux-install-with-puppet.md b/defender-endpoint/linux-install-with-puppet.md index d9ffe33be1..16efdfa432 100644 --- a/defender-endpoint/linux-install-with-puppet.md +++ b/defender-endpoint/linux-install-with-puppet.md @@ -154,7 +154,7 @@ There are two ways to create a manifest file: } ``` > [!NOTE] -> The installer script also supports other parameters such as channel, realtime protection, version, etc. To select from the list of available options, check help. +> The installer script also supports other parameters such as channel, realtime protection, version, custom path installation etc. To select from the list of available options, check help. >`./mde_installer.sh --help` #### Create a manifest to deploy Defender for Endpoint by configuring repositories manually diff --git a/defender-endpoint/linux-install-with-saltack.md b/defender-endpoint/linux-install-with-saltack.md index 8d32005050..0e0384a0ae 100644 --- a/defender-endpoint/linux-install-with-saltack.md +++ b/defender-endpoint/linux-install-with-saltack.md @@ -99,7 +99,7 @@ There are two ways you can create the Saltstack state files: ``` > [!NOTE] -> The installer script also supports other parameters such as channel (insiders-fast, insiders-slow, prod (default)), real-time protection, version, etc. To select from the list of available options, check help through the following command: +> The installer script also supports other parameters such as channel (insiders-fast, insiders-slow, prod (default)), real-time protection, version, custom path installation etc. To select from the list of available options, check help through the following command: >```./mde_installer.sh --help``` ### Create Saltstack state files by manually configuring repositories diff --git a/defender-endpoint/linux-installer-script.md b/defender-endpoint/linux-installer-script.md index 31194a8105..453a30c7b8 100644 --- a/defender-endpoint/linux-installer-script.md +++ b/defender-endpoint/linux-installer-script.md @@ -83,7 +83,7 @@ Before you get started, see [Prerequisites for Defender for Endpoint on Linux](m ```bash sudo ./mde_installer.sh --install --onboard ./MicrosoftDefenderATPOnboardingLinuxServer.py --channel prod --min_req ``` - + This command deploys the latest agent version to the production channel, check for min system requisites and onboard the device to Defender Portal. Additionally you can pass more parameter based on your requirements to modify the installation. Check help for all the available options: @@ -116,6 +116,7 @@ Before you get started, see [Prerequisites for Defender for Endpoint on Linux](m --https-proxy set https proxy --ftp-proxy set ftp proxy --mdatp specific version of mde to be installed. will use the latest if not provided + -b|--install-path specify the installation and configuration path for MDE. Default: / -h|--help display help ``` @@ -126,9 +127,15 @@ Before you get started, see [Prerequisites for Defender for Endpoint on Linux](m |Upgrade to a specific agent version | `sudo ./mde_installer.sh --upgrade –-mdatp 101.24082.0004` | |Downgrade to a specific agent version | `sudo ./mde_installer.sh --downgrade –-mdatp 101.24082.0004` | |Uninstall agent | `sudo ./mde_installer.sh --remove` | - + |Install to a custom path location | `sudo ./mde_installer.sh --install --onboard ./MicrosoftDefenderATPOnboardingLinuxServer.py --channel prod --min_req --install-path /custom/path/location` | + + For details on installing to a custom path, refer: [Install Defender for Endpoint on Linux to a custom path](linux-custom-path-installation.md). + > [!NOTE] - > Upgrading your operating system to a new major version after the product installation requires the product to be reinstalled. You need to uninstall the existing Defender for Endpoint on Linux, upgrade the operating system, and then reconfigure Defender for Endpoint on Linux. + > + > 1. Upgrading your operating system to a new major version after the product installation requires the product to be reinstalled. You need to uninstall the existing Defender for Endpoint on Linux, upgrade the operating system, and then reconfigure Defender for Endpoint on Linux. + > + > 2. The installation path can't be changed after Defender for Endpoint is installed. To use a different path, uninstall and reinstall the product at the new location. ## Verify deployment status diff --git a/defender-endpoint/mde-linux-prerequisites.md b/defender-endpoint/mde-linux-prerequisites.md index 1cf689f060..254dbef02b 100644 --- a/defender-endpoint/mde-linux-prerequisites.md +++ b/defender-endpoint/mde-linux-prerequisites.md @@ -51,6 +51,10 @@ For detailed licensing information, see [Product Terms: Microsoft Defender for E - **Disk Space**: 2 GB minimum. For high-performance workloads, more disk space might be needed. - **Memory**: 1 GB of RAM minimum. For high-performance workloads, more memory might be needed. +Additionally if installing MDE at a custom location +- **Permissions**: rwxr-xr-x minimum permissions for the entire custom installation directory tree +- **semanage**: For workloads with conflicting rules, SELinux equivalence rules might need to be set. + > [!NOTE] > Performance tuning might be needed based on workloads. For more information, see [Performance tuning for Microsoft Defender for Endpoint on Linux](/defender-endpoint/linux-support-perf)