Deploy Microsoft Defender for Endpoint on Linux with Ansible

Want to experience Defender for Endpoint? Sign up for a free trial.

This article describes how to deploy Defender for Endpoint on Linux using Ansible. A successful deployment requires the completion of all of the following tasks:

• Download the onboarding package
• Create Ansible YAML files
• Deployment
• References

Important

This article contains information about third-party tools. This is provided to help complete integration scenarios, however, Microsoft does not provide troubleshooting support for third-party tools.
Contact the third-party vendor for support.

Prerequisites and system requirements

Before you get started, see the main Defender for Endpoint on Linux page for a description of prerequisites and system requirements for the current software version.

In addition, for Ansible deployment, you need to be familiar with Ansible administration tasks, have Ansible configured, and know how to deploy playbooks and tasks. Ansible has many ways to complete the same task. These instructions assume availability of supported Ansible modules, such as apt and unarchive to help deploy the package. Your organization might use a different workflow. Refer to the Ansible documentation for details.

• Ansible needs to be installed on at least one computer (Ansible calls this the control node).

• SSH must be configured for an administrator account between the control node and all managed nodes (devices that will have Defender for Endpoint installed on them), and it is recommended to be configured with public key authentication.

• The following software must be installed on all managed nodes:

  • curl
  • python-apt (if you are deploying on distributions using apt as a package manager)

• All managed nodes must be listed in the following format in the /etc/ansible/hosts or relevant file:

  [servers]
  host1 ansible_ssh_host=10.171.134.39
  host2 ansible_ssh_host=51.143.50.51
  

• Ping test:

  ansible -m ping all
  

Download the onboarding package

Download the onboarding package from Microsoft Defender portal.

Warning

Repackaging the Defender for Endpoint installation package is not a supported scenario. Doing so can negatively impact the integrity of the product and lead to adverse results, including but not limited to triggering tampering alerts and updates failing to apply.

1. In Microsoft Defender portal, go to Settings > Endpoints > Device management > Onboarding.

2. In the first drop-down menu, select Linux Server as the operating system. In the second drop-down menu, select Your preferred Linux configuration management tool as the deployment method.

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

   

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  4984 Feb 18 11:22 WindowsDefenderATPOnboardingPackage.zip
   

   unzip WindowsDefenderATPOnboardingPackage.zip
   

   Archive:  WindowsDefenderATPOnboardingPackage.zip
   inflating: mdatp_onboard.json
   

Create Ansible YAML files

Create a subtask or role files that contribute to a playbook or task.

• Create the onboarding task, onboarding_setup.yml:

  - name: Create MDATP directories
    file:
      path: /etc/opt/microsoft/mdatp/
      recurse: true
      state: directory
      mode: 0755
      owner: root
      group: root
  
  - name: Register mdatp_onboard.json
    stat:
      path: /etc/opt/microsoft/mdatp/mdatp_onboard.json
    register: mdatp_onboard
  
  - name: Extract WindowsDefenderATPOnboardingPackage.zip into /etc/opt/microsoft/mdatp
    unarchive:
      src: WindowsDefenderATPOnboardingPackage.zip
      dest: /etc/opt/microsoft/mdatp
      mode: 0600
      owner: root
      group: root
    when: not mdatp_onboard.stat.exists
  

• Add the Defender for Endpoint repository and key, add_apt_repo.yml:

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

  • insiders-fast, denoted as [channel]
  • insiders-slow, denoted as [channel]
  • prod, denoted as [channel] using the version name (see Linux Software Repository for Microsoft Products)

  Each channel corresponds to a Linux software repository.

  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's 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.

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

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

  Note

  In case of Oracle Linux and Amazon Linux 2, replace [distro] with "rhel". For Amazon Linux 2, replace [version] with "7". For Oracle Linux, replace [version] with the version of Oracle Linux.

  - name: Add Microsoft APT key
    apt_key:
      url: https://packages.microsoft.com/keys/microsoft.asc
      state: present
    when: ansible_os_family == "Debian"
  
  - name: Add Microsoft apt repository for MDATP
    apt_repository:
      repo: deb [arch=arm64,armhf,amd64] https://packages.microsoft.com/[distro]/[version]/prod [codename] main
      update_cache: yes
      state: present
      filename: microsoft-[channel]
    when: ansible_os_family == "Debian"
  
  - name: Add Microsoft DNF/YUM key
    rpm_key:
      state: present
      key: https://packages.microsoft.com/keys/microsoft.asc
    when: ansible_os_family == "RedHat"
  
  - name: Add  Microsoft yum repository for MDATP
    yum_repository:
      name: packages-microsoft-[channel]
      description: Microsoft Defender for Endpoint
      file: microsoft-[channel]
      baseurl: https://packages.microsoft.com/[distro]/[version]/[channel]/ 
      gpgcheck: yes
      enabled: Yes
    when: ansible_os_family == "RedHat"
  

• Create the Ansible install and uninstall YAML files.

  • For apt-based distributions use the following YAML file:

    cat install_mdatp.yml
    

    - hosts: servers
      tasks:
        - name: include onboarding tasks
          import_tasks:
            file: ../roles/onboarding_setup.yml
        - name: add apt repository
          import_tasks:
            file: ../roles/add_apt_repo.yml
        - name: Install MDATP
          apt:
            name: mdatp
            state: latest
            update_cache: yes
    

    cat uninstall_mdatp.yml
    

    - hosts: servers
      tasks:
        - name: Uninstall MDATP
          apt:
            name: mdatp
            state: absent
    

  • For dnf-based distributions use the following YAML file:

    cat install_mdatp_dnf.yml
    

    - hosts: servers
      tasks:
        - name: include onboarding tasks
          import_tasks:
            file: ../roles/onboarding_setup.yml
        - name: add apt repository
          import_tasks:
            file: ../roles/add_yum_repo.yml
        - name: Install MDATP
          dnf:
            name: mdatp
            state: latest
            enablerepo: packages-microsoft-[channel]
    

    cat uninstall_mdatp_dnf.yml
    

    - hosts: servers
      tasks:
        - name: Uninstall MDATP
          dnf:
            name: mdatp
            state: absent
    

Deployment

Now run the tasks files under /etc/ansible/playbooks/ or relevant directory.

• Installation:

  ansible-playbook /etc/ansible/playbooks/install_mdatp.yml -i /etc/ansible/hosts
  

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.

• Validation/configuration:

  ansible -m shell -a 'mdatp connectivity test' all
  

  ansible -m shell -a 'mdatp health' all
  

• Uninstallation:

  ansible-playbook /etc/ansible/playbooks/uninstall_mdatp.yml -i /etc/ansible/hosts
  

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 Defender for Endpoint on Linux, install the upgrade, and finally reconfigure Defender for Endpoint on Linux on your device.

References

• Add or remove YUM repositories

• Manage packages with the dnf package manager

• Add and remove APT repositories

• Manage apt-packages

See also

• Investigate agent health issues

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.