Deploy Microsoft Defender ATP for Linux manually

Applies to:

This article describes how to deploy Microsoft Defender ATP for Linux manually. A successful deployment requires the completion of all of the following tasks:

Prerequisites and system requirements

Before you get started, see Microsoft Defender ATP for Linux for a description of prerequisites and system requirements for the current software version.

Configure the Linux software repository

Microsoft Defender ATP for Linux can be deployed from one of the following channels (denoted below as [channel]): insiders-fast, insiders-slow, or prod. Each of these channels corresponds to a Linux software repository. Instructions for configuring your device to use one of these repositories are provided below.

The choice of the channel determines the type and frequency of updates that are offered to your device. Devices in insiders-fast are the first ones to receive updates and new features, followed later by insiders-slow and lastly by prod.

In order to preview new features and provide early feedback, it is recommended that you configure some devices in your enterprise to use either insiders-fast or insiders-slow.

Warning

Switching the channel after the initial installation requires the product to be reinstalled. To switch the product channel: uninstall the existing package, re-configure your device to use the new channel, and follow the steps in this document to install the package from the new location.

RHEL and variants (CentOS and Oracle Linux)

  • Note your distribution and version, and identify the closest entry for it under https://packages.microsoft.com/config/.

    In the below commands, replace [distro] and [version] with the information you've identified:

    Note

    In case of Oracle Linux, replace [distro] with “rhel”.

    sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/[distro]/[version]/[channel].repo
    

    For example, if you are running CentOS 7 and wish to deploy MDATP for Linux from the insiders-fast channel:

    sudo yum-config-manager --add-repo=https://packages.microsoft.com/config/centos/7/insiders-fast.repo
    
  • Install the Microsoft GPG public key:

    curl https://packages.microsoft.com/keys/microsoft.asc > microsoft.asc
    
    sudo rpm --import microsoft.asc
    
  • Install yum-utils if it is not already installed:

    sudo yum install yum-utils
    
  • Download and make usable all the metadata for the currently enabled yum repositories:

    yum makecache
    

SLES and variants

  • Note your distribution and version, and identify the closest entry for it under https://packages.microsoft.com/config/.

    In the following commands, replace [distro] and [version] with the information you've identified:

    sudo zypper addrepo -c -f -n microsoft-[channel] https://packages.microsoft.com/config/[distro]/[version]/[channel].repo
    

    For example, if you are running SLES 12 and wish to deploy MDATP for Linux from the insiders-fast channel:

    sudo zypper addrepo -c -f -n microsoft-insiders-fast https://packages.microsoft.com/config/sles/12/insiders-fast.repo
    
  • Install the Microsoft GPG public key:

    curl https://packages.microsoft.com/keys/microsoft.asc > microsoft.asc
    
    rpm --import microsoft.asc
    

Ubuntu and Debian systems

  • Install curl if it is not already installed:

    sudo apt-get install curl
    
  • Install libplist-utils if it is not already installed:

    sudo apt-get install libplist-utils
    
  • Note your distribution and version, and identify the closest entry for it under https://packages.microsoft.com/config.

    In the below command, replace [distro] and [version] with the information you've identified:

    curl -o microsoft.list https://packages.microsoft.com/config/[distro]/[version]/[channel].list
    

    For example, if you are running Ubuntu 18.04 and wish to deploy MDATP for Linux from the insiders-fast channel:

    curl -o microsoft.list https://packages.microsoft.com/config/ubuntu/18.04/insiders-fast.list
    
  • Install the repository configuration:

    sudo mv ./microsoft.list /etc/apt/sources.list.d/microsoft-[channel].list
    
  • Install the gpg package if not already installed:

    sudo apt-get install gpg
    
  • Install the Microsoft GPG public key:

    curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
    
  • Install the https driver if it's not already present:

    sudo apt-get install apt-transport-https
    
  • Update the repository metadata:

    sudo apt-get update
    

Application installation

  • RHEL and variants (CentOS and Oracle Linux):

    sudo yum install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device.

    # list all repositories
    $ yum repolist
    ...
    packages-microsoft-com-prod               packages-microsoft-com-prod        316
    packages-microsoft-com-prod-insiders-fast packages-microsoft-com-prod-ins      2
    ...
    
    # install the package from the production repository
    $ sudo yum --enablerepo=packages-microsoft-com-prod install mdatp
    
  • SLES and variants:

    sudo zypper install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device.

    # list all repositories
    $ zypper repos
    ...
    #  | Alias | Name | ...
    XX | packages-microsoft-com-insiders-fast | microsoft-insiders-fast | ...
    XX | packages-microsoft-com-prod | microsoft-prod | ...
    ...
    
    # install the package from the production repository
    $ sudo zypper install packages-microsoft-com-prod:mdatp
    
  • Ubuntu and Debian system:

    sudo apt-get install mdatp
    

    If you have multiple Microsoft repositories configured on your device, you can be specific about which repository to install the package from. The following example shows how to install the package from the production channel if you also have the insiders-fast repository channel configured on this device. This situation can happen if you are using multiple Microsoft products on your device.

    # list all repositories
    $ cat /etc/apt/sources.list.d/*
    deb [arch=arm64,armhf,amd64] https://packages.microsoft.com/ubuntu/18.04/prod insiders-fast main
    deb [arch=amd64] https://packages.microsoft.com/ubuntu/18.04/prod bionic main
    
    # install the package from the production repository
    $ sudo apt -t bionic install mdatp
    

Download the onboarding package

Download the onboarding package from Microsoft Defender Security Center:

  1. In Microsoft Defender Security Center, go to Settings > Machine Management > Onboarding.

  2. In the first drop-down menu, select Linux Server as the operating system. In the second drop-down menu, select Local Script (for up to 10 machines) as the deployment method.

  3. Select Download onboarding package. Save the file as WindowsDefenderATPOnboardingPackage.zip.

    Microsoft Defender Security Center screenshot

  4. From a command prompt, verify that you have the file. Extract the contents of the archive:

    ls -l
    

    total 8 -rw-r--r-- 1 test staff 5752 Feb 18 11:22 WindowsDefenderATPOnboardingPackage.zip

    unzip WindowsDefenderATPOnboardingPackage.zip
    Archive:  WindowsDefenderATPOnboardingPackage.zip
    inflating: MicrosoftDefenderATPOnboardingLinuxServer.py
    

    Archive: WindowsDefenderATPOnboardingPackage.zip inflating: WindowsDefenderATPOnboarding.py

Client configuration

  1. Copy MicrosoftDefenderATPOnboardingLinuxServer.py to the target machine.

    Initially the client machine is not associated with an organization. Note that the orgId attribute is blank:

    mdatp --health orgId
    
  2. Run MicrosoftDefenderATPOnboardingLinuxServer.py, and note that, in order to run this command, you must have python installed on the device:

    python MicrosoftDefenderATPOnboardingLinuxServer.py
    
  3. Verify that the machine is now associated with your organization and reports a valid organization identifier:

    mdatp --health orgId
    
  4. A few minutes after you complete the installation, you can see the status by running the following command. A return value of 1 denotes that the product is functioning as expected:

    mdatp --health healthy
    

    Important

    When the product starts for the first time, it downloads the latest antimalware definitions. Depending on your Internet connection, this can take up to a few minutes. During this time the above command returns a value of 0.
    Please note that you may also need to configure a proxy after completing the initial installation. See Configure Microsoft Defender ATP for Linux for static proxy discovery: Post-installation configuration.

  5. Run a detection test to verify that the machine is properly onboarded and reporting to the service. Perform the following steps on the newly onboarded machine:

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

      mdatp --health realTimeProtectionEnabled
      
    • Open a Terminal window. Copy and execute the following command:

      curl -o ~/Downloads/eicar.com.txt https://www.eicar.org/download/eicar.com.txt
      
    • The file should have been quarantined by Microsoft Defender ATP for Linux. Use the following command to list all the detected threats:

      mdatp --threat --list --pretty
      

Log installation issues

See Log installation issues for more information on how to find the automatically generated log that is created by the installer when an error occurs.

Operating system upgrades

When upgrading your operating system to a new major version, you must first uninstall Microsoft Defender ATP for Linux, install the upgrade, and finally reconfigure Microsoft Defender ATP for Linux on your device.

Uninstallation

See Uninstall for details on how to remove Microsoft Defender ATP for Linux from client devices.