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:
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:
All managed nodes must be listed in the following format in the
/etc/ansible/hostsor relevant file:
[servers] host1 ansible_ssh_host=10.171.134.39 host2 ansible_ssh_host=22.214.171.124
ansible -m ping all
Download the onboarding package
Download the onboarding package from Microsoft 365 Defender portal:
In Microsoft 365 Defender portal, go to Settings > Endpoints > Device management > Onboarding.
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.
Select Download onboarding package. Save the file as WindowsDefenderATPOnboardingPackage.zip.
From a command prompt, verify that you have the file. Extract the contents of the archive:
total 8 -rw-r--r-- 1 test staff 4984 Feb 18 11:22 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,
- 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,
Defender for Endpoint on 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.
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
In the following commands, replace [distro] and [version] with the information you've identified.
In case of Oracle Linux, replace [distro] with “rhel”.
- 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 [channel] 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-com-prod-[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:
- hosts: servers tasks: - include: ../roles/onboarding_setup.yml - include: ../roles/add_apt_repo.yml - name: Install MDATP apt: name: mdatp state: latest update_cache: yes
- hosts: servers tasks: - name: Uninstall MDATP apt: name: mdatp state: absent
For dnf-based distributions use the following YAML file:
- hosts: servers tasks: - include: ../roles/onboarding_setup.yml - include: ../roles/add_yum_repo.yml - name: Install MDATP dnf: name: mdatp state: latest enablerepo: packages-microsoft-com-prod-[channel]
- hosts: servers tasks: - name: Uninstall MDATP dnf: name: mdatp state: absent
Now run the tasks files under
/etc/ansible/playbooks/ or relevant directory.
ansible-playbook /etc/ansible/playbooks/install_mdatp.yml -i /etc/ansible/hosts
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.
ansible -m shell -a 'mdatp connectivity test' all
ansible -m shell -a 'mdatp health' all
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.