Deploy Microsoft Defender ATP for Linux with Ansible

Applies to:

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

Prerequisites and system requirements

Before you get started, see the main Microsoft Defender ATP for 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 (we will call it the primary computer).

  • SSH must be configured for an administrator account between the primary computer and all clients, and it is recommended be configured with public key authentication.

  • The following software must be installed on all clients:

    • curl
    • python-apt
  • All hosts 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 Security Center:

  1. In Microsoft Defender Security Center, go to Settings > 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.

    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  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 an 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 Microsoft Defender ATP repository and key.

    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.

    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.

    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.

    Note

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

    - name: Add Microsoft APT key
        apt_key:
            keyserver: https://packages.microsoft.com/
            id: BC528686B50D79E339D3721CEB3E94ADBE1229CF
        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 [channel] main
            update_cache: yes
            state: present
            filename: microsoft-[channel].list
        when: ansible_os_family == "Debian"
    
    - name: Add  Microsoft yum repository for MDATP
        yum_repository:
            name: packages-microsoft-com-prod-[channel]
            description: Microsoft Defender ATP
            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:
              - include: ../roles/onboarding_setup.yml
              - include: ../roles/add_apt_repo.yml
              - apt:
                  name: mdatp
                  state: latest
                  update_cache: yes
      
      cat uninstall_mdatp.yml
      
      - hosts: servers
      tasks:
          - apt:
              name: mdatp
              state: absent
      
    • For yum-based distributions use the following YAML file:

      cat install_mdatp_yum.yml
      
      - hosts: servers
      tasks:
          - include: ../roles/onboarding_setup.yml
          - include: ../roles/add_yum_repo.yml
          - yum:
              name: mdatp
              state: latest
              enablerepo: packages-microsoft-com-prod-[channel]
      
      cat uninstall_mdatp_yum.yml
      
      - hosts: servers
      tasks:
          - yum:
              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 Microsoft Defender ATP for Linux, install the upgrade, and finally reconfigure Microsoft Defender ATP for Linux on your device.

References