windows-itpro-docs/windows/security/threat-protection/microsoft-defender-atp/linux-install-with-ansible.md

title, ms.reviewer, description, keywords, search.product, search.appverid, ms.prod, ms.mktglfcycl, ms.sitesec, ms.pagetype, ms.author, author, ms.localizationpriority, manager, audience, ms.collection, ms.topic

title	ms.reviewer	description	keywords	search.product	search.appverid	ms.prod	ms.mktglfcycl	ms.sitesec	ms.pagetype	ms.author	author	ms.localizationpriority	manager	audience	ms.collection	ms.topic
Deploy Microsoft Defender ATP for Linux with Ansible		Describes how to deploy Microsoft Defender ATP for Linux using Ansible.	microsoft, defender, atp, linux, installation, deploy, uninstallation, puppet, ansible, linux, redhat, ubuntu, debian, sles, suse, centos	eADQiWindows 10XVcnh	met150	w10	deploy	library	security	dansimp	dansimp	medium	dansimp	ITPro	M365-security-compliance	conceptual

Deploy Microsoft Defender ATP for Linux with Ansible

Applies to:

• Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP) for Linux

This topic describes how to deploy Microsoft Defender ATP for 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

Prerequisites and system requirements

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

• Ansible needs to be installed on at least on one computer (we will call it the master).

• SSH must be configured for an administrator account between the master 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
  • unzip

• All hosts must be listed in the following format in the /etc/ansible/hosts 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 > Machine 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 subtask or role files that contribute to an actual task. First create the copy_onboarding_pkg.yml file under the /etc/ansible/roles directory:

• Copy the onboarding package to all client machines:

  - name: Copy the zip file
      copy:
          src:  /root/WindowsDefenderATPOnboardingPackage.zip
          dest: /root/WindowsDefenderATPOnboardingPackage.zip
          owner: root
          group: root
          mode: '0644'
  
  - name: Add Microsoft apt signing key
    apt_key:
      url: https://packages.microsoft.com/keys/microsoft.asc
      state: present
    when: ansible_os_family == "Debian"
  

• Create the setup.sh script that operates on the onboarding file, in this example located in the /root directory:

  #!/bin/bash
  # We assume WindowsDefenderATPOnboardingPackage.zip is stored in /root
  cd /root || exit 1
  # Unzip the archive and create the onboarding file
  mkdir -p /etc/opt/microsoft/mdatp/
  unzip WindowsDefenderATPOnboardingPackage.zip
  cp mdatp_onboard.json /etc/opt/microsoft/mdatp/mdatp_onboard.json
  

• Create the onboarding task, onboarding_setup.yml, under the /etc/ansible/roles directory:

  - name: Register mdatp_onboard.json
    stat: path=/etc/opt/microsoft/mdatp/mdatp_onboard.json
    register: mdatp_onboard
  
  - name: Copy the setup script file
      copy:
          src: /root/setup.sh
          dest: /root/setup.sh
          owner: root
          group: root
          mode: '0744'
  
  - name: Run a script to create the onboarding file
    script: /root/setup.sh
    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.

  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”.

    ```bash
    - 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 APT key
        apt_key:
            keyserver: https://packages.microsoft.com/
            id: BC528686B50D79E339D3721CEB3E94ADBE1229C
        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 actual install/uninstall YAML files under /etc/ansible/playbooks.

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

    $ cat install_mdatp.yml
    - hosts: servers
        tasks:
            - include: ../roles/download_copy_blob.yml
            - include: ../roles/setup_blob.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/download_copy_blob.yml
        - include: ../roles/setup_blob.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/.

• 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.

References

• Add or remove YUM repositories

• Manage packages with the yum package manager

• Add and remove APT repositories

• Manage apt-packages