Edit

Share via

Deploy Microsoft Defender endpoint security to Linux devices using the Defender deployment tool (preview)

  • Applies to: Microsoft Defender for Business, Microsoft Defender for Endpoint Plan 1, Microsoft Defender for Endpoint Plan 2

The Defender deployment tool provides an efficient, user-friendly onboarding process for Microsoft Defender for Endpoint on Linux devices. It allows users to install and onboard Microsoft Defender for Endpoint using a single package that can be downloaded from the Microsoft Defender portal. This eliminates the need to install Defender using installer script/cli commands and then, separately, to onboard the device using the onboarding package from the portal.

The defender-deployment tool supports both manual and bulk onboarding through third-party tools such as Chef, Ansible, Puppet, and SaltStack. The tool supports several parameters you can use to customize large scale deployments, making it possible to have tailored installations across diverse environments.

Prerequisites and system requirements

Before you get started, see Prerequisites for Microsoft Defender for Endpoint on Linux for a description of prerequisites and system requirements. Additionally, the following requirements also need to be met:

  • Allow connection to the URL: msdefender.download.prss.microsoft.com. Before you begin deployment, make sure to run the connectivity test, which checks if the URLs Defender for Endpoint uses are accessible or not.
  • The endpoint must have either wget or curl installed.

The Defender deployment tool enforces the following set of prerequisites checks, which if not met will abort the deployment process:

  • Device memory: Greater than 1 GB
  • Available disk space on the device: Greater than 2GB
  • Glibc library version on the device: Newer than 2.17
  • mdatp version on the device: Must be a supported version and not expired. To check product expiration date, run the command -mdatp health.

Deployment: Step-by-step guide

  1. Download the Defender deployment tool from the Defender portal using the following steps.

    1. Go to Settings > Endpoints > Device management > Onboarding.

    2. In the Step 1 drop-down menu, select Linux Server (Preview) as the operating system.

    3. Under Download and apply onboarding packages or files, select the Download package button.

    Note

    Since this package installs and onboards the agent, it's a tenant specific package and must not be used across tenants.

    Screenshot showing the download package button.

  2. From a command prompt, extract the contents of the archive:

    unzip WindowsDefenderATPOnboardingPackage.zip

    Archive: WindowsDefenderATPOnboardingPackage.zip
inflating: defender_deployment_tool.sh

  3. Grant executable permissions to the script.

    chmod +x defender_deployment_tool.sh

  4. Run the script using the following command to install and onboard Microsoft Defender for Endpoint on your endpoint.

    sudo bash defender_deployment_tool.sh

    This command installs the latest agent version from the production channel and onboards the device to Defender portal. It might take 5-20 minutes for the device to show up in the Device Inventory.

    Note

    If you have set up a system-wide proxy to redirect Defender for Endpoint traffic, make sure you configure the proxy using the Defender deployment tool as well. Refer to the command-line help (--help) for available proxy options.

  5. You can further customize deployment by passing parameters to the tool based on your requirements. Use the option --help to see all the available options:

     ./defender_deployment_tool.sh --help

    Screenshot showing the help command output.

    The following table provides examples of commands for useful scenarios.

    Scenario Command
    Check for unmet non-blocking prerequisites sudo ./defender_deployment_tool.sh --pre-req-non-blocking
    Run the connectivity test sudo ./defender_deployment_tool.sh --connectivity-test
    Deploy to a custom location sudo ./defender_deployment_tool.sh --install-path /usr/microsoft/
    Deploy from the insider-slow channel sudo ./defender_deployment_tool.sh --channel insiders-slow
    Deploy using a proxy sudo ./defender_deployment_tool.sh --http-proxy <http://username:password@proxy_host:proxy_port>
    Deploy a specific agent version sudo ./defender_deployment_tool.sh --mdatp 101.25042.0003 --channel prod
    Upgrade to a specific agent version sudo ./defender_deployment_tool.sh --upgrade --mdatp 101.24082.0004
    Downgrade to a specific agent version sudo ./defender_deployment_tool.sh --downgrade --mdatp 101.24082.0004
    Uninstall Defender sudo ./defender_deployment_tool.sh --remove
    Only onboard if Defender is already installed sudo ./defender_deployment_tool.sh --only-onboard
    Offboard Defender sudo ./defender_deployment_tool.sh --offboard MicrosoftDefenderATPOffboardingLinuxServer.py
    (Note: The latest offboarding file can be downloaded from the Microsoft Defender portal)

Verify deployment status

  1. In the Microsoft Defender portal, open the device inventory. It might take 5-20 minutes for the device to show up in the portal.

  2. Run an antivirus detection test to verify that the device is properly onboarded and reporting to the service. Perform the following steps on the newly onboarded device:

    1. Ensure that real-time protection is enabled (denoted by a result of true from running the following command):

      mdatp health --field real_time_protection_enabled

      If it isn't enabled, execute the following command:

      mdatp config real-time-protection --value enabled

    2. Open a Terminal window and execute the following command to run a detection test:

      curl -o /tmp/eicar.com.txt https://secure.eicar.org/eicar.com.txt

    3. You can run more detection tests on zip files using either of the following commands:

      curl -o /tmp/eicar_com.zip https://secure.eicar.org/eicar_com.zip
curl -o /tmp/eicarcom2.zip https://secure.eicar.org/eicarcom2.zip

    4. The files should be quarantined by Defender for Endpoint on Linux. Use the following command to list all the detected threats:

      mdatp threat list

  3. Run an EDR detection test and simulate a detection to verify that the device is properly onboarded and reporting to the service. Perform the following steps on the newly onboarded device:

    1. Download and extract the script file to an onboarded Linux server.

    2. Grant executable permissions to the script:

      chmod +x mde_linux_edr_diy.sh

    3. Run the following command:

      ./mde_linux_edr_diy.sh

    4. After a few minutes, a detection should be raised in the Microsoft Defender XDR.

    5. Check the alert details, machine timeline, and perform your typical investigation steps.

Check connectivity issues

If you're experiencing any connectivity issues, run this command to perform a connectivity test:

sudo ./defender_deployment_tool.sh --connectivity-test

This test might take some time to run as it performs checks for every URL needed by mdatp and find any issues if present. If the issue persists, refer to the troubleshooting guide.

Troubleshoot the installation

Whenever you run the Defender deployment tool, the activity gets logged in this file:

/tmp/defender_deployment_tool.log

If you experience any installation issues, first check the log file. If that doesn't help you resolve the issue, try following these steps:

  1. For information on how to find the log that's generated automatically when an installation error occurs, see Log installation issues.

  2. For information about common installation issues, see Installation issues.

  3. If health of the device is false, see Defender for Endpoint agent health issues.

  4. For product performance issues, see Troubleshoot performance issues.

  5. For proxy and connectivity issues, see Troubleshoot cloud connectivity issues.

How to switch between channels after you have deployed from a channel

Defender for Endpoint on Linux can be deployed from one of the following channels:

  • insiders-fast
  • insiders-slow
  • prod (production)

Each of these channels corresponds to a Linux software repository. The channel determines the type and frequency of updates that are offered to your device. Devices in insiders-fast are the first to receive updates and new features, followed later by insiders-slow and lastly by prod.

By default, the deployment tool configures your device to use the prod channel. You can use the configuration options described in this document to deploy from a different channel.

To preview new features and provide early feedback, it's recommended that you configure some devices in your enterprise to use either insiders-fast or insiders-slow. If you've already deployed Defender for Endpoint on Linux from a channel and want to switch to a different channel (from prod to insiders-fast, for example), you must first remove the current channel, then delete the current channel repo, and then finally install Defender from the new channel, as illustrated in the following example, where the channel is changed from insiders-fast to prod:

  1. Remove the insiders-fast channel version of Defender for Endpoint on Linux..

    sudo ./defender_deployment_tool.sh --remove --channel insiders-fast

  2. Delete the Defender for Endpoint on the Linux insiders-fast repo.

    sudo ./defender_deployment_tool.sh --clean --channel insiders-fast

  3. Install Microsoft Defender for Endpoint on Linux using the production channel.

    sudo ./defender_deployment_tool.sh --channel prod

Related content

  • Last updated on