Advanced deployment guidance for Microsoft Defender for Endpoint on Linux
Applies to:
This article provides advanced deployment guidance for Microsoft Defender for Endpoint on Linux. You get a brief summary of the deployment steps, learn about the system requirements, then be guided through the actual deployment steps. You'll also learn how to verify that the device has been correctly onboarded.
For information about Microsoft Defender for Endpoint capabilities, see Advanced Microsoft Defender for Endpoint capabilities.
To learn about other ways to deploy Microsoft Defender for Endpoint on Linux, see:
- Manual deployment
- Puppet based deployment
- Ansible based deployment
- Deploy Defender for Endpoint on Linux with Chef
Deployment summary
Learn about the general guidance on a typical Microsoft Defender for Endpoint on Linux deployment. The applicability of some steps is determined by the requirements of your Linux environment.
Capture performance data from the endpoint.
Note
Consider doing the following optional items, even though they are not Microsoft Defender for Endpoint specific, they tend to improve performance in Linux systems.
(Optional) Check for filesystem errors 'fsck' (akin to chkdsk).
Confirm system requirements and resource recommendations are met.
Add your existing solution to the exclusion list for Microsoft Defender Antivirus.
Configure Microsoft Defender for Endpoint on Linux antimalware settings.
Use Ansible, Puppet, or Chef to manage Microsoft Defender for Endpoint on Linux.
Troubleshoot installation issues for Microsoft Defender for Endpoint on Linux.
Verify communication with Microsoft Defender for Endpoint backend.
Verify that you're able to get "Platform Updates" (agent updates).
Verify that you're able to get "Security Intelligence Updates" (signatures/definition updates).
Troubleshoot missing events or alerts issues for Microsoft Defender for Endpoint on Linux.
Troubleshooting High CPU utilization by ISVs, Linux apps, or scripts.
1. Prepare your network environment
Add the Microsoft Defender for Endpoint URLs and/or IP addresses to the allowed list, and prevent traffic from being SSL inspected.
Network connectivity of Microsoft Defender for Endpoint
Use the following steps to check the network connectivity of Microsoft Defender for Endpoint:
See Step 1: Allow destinations for the Microsoft Defender for Endpoint traffic that are allowed for the Microsoft Defender for Endpoint traffic.
If the Linux servers are behind a proxy, then set the proxy settings. For more information, see Set up proxy settings.
Verify that the traffic isn't being inspected by SSL inspection (TLS inspection). This is the most common network related issue when setting up Microsoft Defender Endpoint, see Verify SSL inspection isn't being performed on the network traffic.
Note
- Traffic for Defender for Endpoint should NOT be inspected by SSL inspection (TLS inspection). This applies to all supported operating systems (Windows, Linux, and MacOS).
- To allow connectivity to the consolidated set of URLs or IP addresses, ensure your devices are running the latest component versions. See Onboarding devices using streamlined connectivity for Microsoft Defender for Endpoint for more information.
For more information see Troubleshoot cloud connectivity issues.
Step 1: Allow destinations for the Microsoft Defender for Endpoint traffic
- Go to STEP 1: Configure your network environment to ensure connectivity with Defender for Endpoint service to find the relevant destinations that need to be accessible to devices inside your network environment
- Configure your Firewall/Proxy/Network to allow the relevant URLs and/or IP addresses
Step 2: Set up proxy settings
If the Linux servers are behind a proxy, use the following settings guidance.
The following table lists the supported proxy settings:
Supported | Not supported |
---|---|
Transparent proxy | Proxy autoconfig (PAC, a type of authenticated proxy) |
Manual static proxy configuration | Web proxy autodiscovery protocol (WPAD, a type of authenticated proxy) |
- Network connections
- Full configuration profile
- Static proxy configuration
- Troubleshooting connectivity issues in static proxy scenario
Step 3: Verify SSL inspection isn't being performed on the network traffic
To prevent man-in-the-middle attacks, all Microsoft Azure hosted traffic uses certificate pinning. As a result, SSL inspections by major firewall systems aren't allowed. You have to bypass SSL inspection for Microsoft Defender for Endpoint URLs.
Troubleshoot cloud connectivity issues
For more information, see Troubleshooting cloud connectivity issues for Microsoft Defender for Endpoint on Linux.
2. Capture performance data from the endpoint
Capture performance data from the endpoints that have Defender for Endpoint installed. This includes disk space availability on all mounted partitions, memory usage, process list, and CPU usage (aggregate across all cores).
3. (Optional) Check for filesystem errors 'fsck' (akin to chkdsk)
Any filesystem could end-up getting corrupt, so before installing any new software, it would be good to install it on a healthy file system.
4. (Optional) Update storage subsystem drivers
Newer driver or firmware on a storage subsystem could help with performance and/or reliability.
5. (Optional) Update nic drivers
Newer driver/firmware on a NICs or NIC teaming software could help w/ performance and/or reliability.
6. Confirm system requirements and resource recommendations are met
The following section provides information on supported Linux versions and recommendations for resources.
For a detailed list of supported Linux distros, see System requirements.
Resource | Recommendation |
---|---|
Disk space | Minimum: 2 GB NOTE: More disk space might be needed if cloud diagnostics are enabled for crash collections. |
RAM | 1 GB 4 GB is preferred |
CPU | If the Linux system is running only one vcpu, we recommend it be increased to two vcpu's 4 cores are preferred |
OS version | Kernel filter driver | Comments |
---|---|---|
RHEL 7.x, RHEL 8.x, and RHEL 9.x | No kernel filter driver, the fanotify kernel option must be enabled | akin to Filter Manager (fltmgr, accessible via fltmc.exe ) in Windows |
RHEL 6.x | TALPA kernel driver |
7. Add your existing solution to the exclusion list for Microsoft Defender Antivirus
This step of the setup process involves adding Defender for Endpoint to the exclusion list for your existing endpoint protection solution and any other security products your organization is using. You can choose from several methods to add your exclusions to Microsoft Defender Antivirus.
Tip
To get help configuring exclusions, refer to your solution provider's documentation.
Your ability to run Microsoft Defender for Endpoint on Linux alongside a non-Microsoft antimalware product depends on the implementation details of that product. If the other antimalware product uses fanotify, it has to be uninstalled to eliminate performance and stability side effects resulting from running two conflicting agents.
To check if there's a non-Microsoft antimalware that is running FANotify, you can run
mdatp health
, then check the result:Under "conflicting_applications", if you see a result other than "unavailable", uninstall the non-Microsoft antimalware.
If you don't uninstall the non-Microsoft antimalware product, you might encounter unexpected behaviors such as performance issues, stability issues such as systems hanging, or kernel panics.
To identify the Microsoft Defender for Endpoint on Linux processes and paths that should be excluded in the non-Microsoft antimalware product, run
systemctl status -l mdatp
.Exclude the following processes from the non-Microsoft antimalware product:
wdavdaemon
crashpad_handler
mdatp_audis_plugin
telemetryd_v2
Exclude the following paths from the non-Microsoft antimalware product:
/opt/microsoft/mdatp/
/var/opt/microsoft/mdatp/
/etc/opt/microsoft/mdatp/
8. Keep the following points about exclusions in mind
When you add exclusions to Microsoft Defender Antivirus scans, you should add path and process exclusions.
Note
- Antivirus exclusions apply to the antivirus engine.
- Indicators allow/block apply to the antivirus engine.
Keep the following points in mind:
- Path exclusions exclude specific files and whatever those files access.
- Process exclusions exclude whatever a process touches, but doesn't exclude the process itself.
- List your process exclusions using their full path and not by their name only. (The name-only method is less secure.)
- If you list each executable as both a path exclusion and a process exclusion, the process and whatever it touches are excluded.
Tip
Review "Common mistakes to avoid when defining exclusions", specifically Folder locations and Processes the sections for Linux and macOS Platforms.
9. Create device groups
Set up your device groups, device collections, and organizational units Device groups, device collections, and organizational units enable your security team to manage and assign security policies efficiently and effectively. The following table describes each of these groups and how to configure them. Your organization might not use all three collection types.
Collection type | What to do |
---|---|
Device groups (formerly called machine groups) enable your security operations team to configure security capabilities, such as automated investigation and remediation. Device groups are also useful for assigning access to those devices so that your security operations team can take remediation actions if needed. Device groups are created while the attack was detected and stopped, alerts, such as an "initial access alert," were triggered and appeared in the Microsoft Defender portal. |
1. Go to the Microsoft Defender portal (https://security.microsoft.com). 2. In the navigation pane on the left, choose Settings > Endpoints > Permissions > Device groups. 3. Choose + Add device group. 4. Specify a name and description for the device group. 5. In the Automation level list, select an option. (We recommend Full - remediate threats automatically.) To learn more about the various automation levels, see How threats are remediated. 6. Specify conditions for a matching rule to determine which devices belong to the device group. For example, you can choose a domain, OS versions, or even use device tags. 7. On the User access tab, specify roles that should have access to the devices that are included in the device group. 8. Choose Done. |
Device collections enable your security operations team to manage applications, deploy compliance settings, or install software updates on the devices in your organization. Device collections are created by using Configuration Manager. |
Follow the steps in Create a collection. |
Organizational units enable you to logically group objects such as user accounts, service accounts, or computer accounts. You can then assign administrators to specific organizational units, and apply group policy to enforce targeted configuration settings. Organizational units are defined in Microsoft Entra Domain Services. |
Follow the steps in Create an Organizational Unit in a Microsoft Entra Domain Services managed domain. |
10. Configure Microsoft Defender for Endpoint on Linux antimalware settings
Before you begin:
If you're already using a non-Microsoft antimalware product for your Linux servers, consider that you might have to copy the existing exclusions to Microsoft Defender for Endpoint on Linux.
If you're not using a non-Microsoft antimalware product for your Linux servers, get a list of all your Linux applications and check the vendors website for exclusions.
If you're running a non-Microsoft antimalware product, add the processes/paths to the Microsoft Defender for Endpoint's antivirus exclusion list. For more information, check the non-Microsoft antimalware documentation or contact their support.
If you're testing on one machine, you can use a command line to set up the exclusions:
If you're testing on multiple machines, then use the following
mdatp_managed.json
file. If you're coming from Windows, this like a 'group policy' for Defender for Endpoint on Linux.You can consider modifying the file based on your needs:
{ "antivirusEngine":{ "enforcementLevel":"real_time", "scanAfterDefinitionUpdate":true, "scanArchives":true, "maximumOnDemandScanThreads":1, "exclusionsMergePolicy":"merge", "exclusions":[ { "$type":"excludedPath", "isDirectory":false, "path":"/var/log/system.log" }, { "$type":"excludedPath", "isDirectory":true, "path":"/home" }, { "$type":"excludedFileExtension", "extension":"pdf" }, { "$type":"excludedFileName", "name":"cat" } ], "allowedThreats":[ "<EXAMPLE DO NOT USE>EICAR-Test-File (not a virus)" ], "disallowedThreatActions":[ "allow", "restore" ], "threatTypeSettingsMergePolicy":"merge", "threatTypeSettings":[ { "key":"potentially_unwanted_application", "value":"block" }, { "key":"archive_bomb", "value":"audit" } ] }, "cloudService":{ "enabled":true, "diagnosticLevel":"optional", "automaticSampleSubmissionConsent":"safe", "automaticDefinitionUpdateEnabled":true "proxy": "<EXAMPLE DO NOT USE> http://proxy.server:port/" } }
Recommendations:
{ "antivirusEngine":{ "enforcementLevel":"real_time", "scanAfterDefinitionUpdate":true, "scanArchives":true, "maximumOnDemandScanThreads":1, "exclusionsMergePolicy":"merge", "exclusions":[ { "$type":"excludedPath", "isDirectory":false, "path":"/var/log/system.log" }, { "$type":"excludedPath", "isDirectory":true, "path":"/proc" }, { "$type":"excludedPath", "isDirectory":true, "path":"/sys" }, { "$type":"excludedPath", "isDirectory":true, "path":"/dev" }, { "$type":"excludedFileExtension", "extension":"" }, { "$type":"excludedFileName", "name":"" } ], "allowedThreats":[ "" ], "disallowedThreatActions":[ "allow", "restore" ], "threatTypeSettingsMergePolicy":"merge", "threatTypeSettings":[ { "key":"potentially_unwanted_application", "value":"block" }, { "key":"archive_bomb", "value":"audit" } ] }, "cloudService":{ "enabled":true, "diagnosticLevel":"optional", "automaticSampleSubmissionConsent":"safe", "automaticDefinitionUpdateEnabled":true "proxy": "<EXAMPLE DO NOT USE> http://proxy.server:port/" } }
Note
In Linux (and macOS) we support paths where it starts with a wildcard.
The following table describes the settings that are recommended as part of mdatp_managed.json
file:
Settings | Comments |
---|---|
exclusionsMergePolicy being set to admin_only |
Prevents the local admin from being able to add the local exclusions (via bash (the command prompt)). |
disallowedThreatActions being set to allow and restore |
Prevents the local admin from being able to restore a quarantined item (via bash (the command prompt)). |
threatTypeSettingsMergePolicy being set to admin_only |
Prevents the local admin from being able to add False Positives or True Positives that are benign to the threat types (via bash (the command prompt)). |
- Save the setting as
mdatp_managed.json
file. - Copy the setting to this path
/etc/opt/microsoft/mdatp/managed/
. For more information, see Set preferences for Microsoft Defender for Endpoint on Linux. - Add your non-Microsoft antimalware processes and paths to the exclusion list from the prior step.
- Verify that you've added your current exclusions from your non-Microsoft antimalware solution to the prior step.
Applications that Microsoft Defender for Endpoint can impact
High I/O workloads such as Postgres, OracleDB, Jira, and Jenkins might require other exclusions, depending on the amount of activity that is being processed (and monitored by Defender for Endpoint). It's best to follow guidance from non-Microsoft application providers for their exclusions if you experience performance degradation after installing Defender for Endpoint. Also keep in mind Common Exclusion Mistakes for Microsoft Defender Antivirus.
If you experience performance degradation, see the following resources:
- Troubleshoot performance issues for Microsoft Defender for Endpoint on Linux.
- Troubleshoot AuditD performance issues with Microsoft Defender for Endpoint on Linux.
11. Download the Microsoft Defender for Endpoint on Linux onboarding package
For more information, see download the onboarding package from Microsoft Defender portal.
Note
This download registers Microsoft Defender for Endpoint on Linux to send the data to your Microsoft Defender for Endpoint instance.
After downloading this package, you can follow the manual installation instructions or use a Linux management platform to deploy and manage Defender for Endpoint on Linux.
12. Ansible, Puppet, and Chef examples to manage Microsoft Defender for Endpoint on Linux
Defender for Endpoint on Linux is designed to allow almost any management solution to easily deploy and manage Defender for Endpoint settings on Linux. A few common Linux management platforms are Ansible, Puppet, and Chef. The following documents contain examples on how to configure these management platforms to deploy and configure Defender for Endpoint on Linux.
Deploy Microsoft Defender for Endpoint on Linux with Puppet
Deploy Microsoft Defender for Endpoint on Linux with Ansible
Deploy Microsoft Defender for Endpoint on Linux with Chef
Note
Reboots are NOT required after installing or updating Microsoft Defender for Endpoint on Linux except when you're running auditD in immutable mode.
Deliver the scheduled scans cronjob setting
Schedule an antivirus scan using Anacron in Microsoft Defender for Endpoint on Linux. For more information, see Schedule an antivirus scan using Anacron in Microsoft Defender for Endpoint on Linux.
Update Microsoft Defender for Endpoint on Linux agent cronjob settings
Schedule an update of the Microsoft Defender for Endpoint on Linux. For more information, see, Schedule an update of the Microsoft Defender for Endpoint on Linux.
13. Troubleshoot installation issues for Microsoft Defender for Endpoint on Linux
Learn how to troubleshoot issues that might occur during installation in Troubleshoot installation issues for Microsoft Defender for Endpoint on Linux.
14. Check resource utilization statistics
Check performance statistics and compare to predeployment utilization compared to post-deployment.
15. Verify communication with Microsoft Defender for Endpoint backend
To verify the Microsoft Defender for Endpoint on Linux communication to the cloud with the current network settings, run the following connectivity test from the command line:
mdatp connectivity test
The following image displays the expected output from the test:
For more information, see Connectivity validation.
16. Investigate agent health issues
Investigate agent health issues based on values returned when you run the mdatp health
command. For more information, see, Investigate agent health issues.
17. Verify that you're able to get platform updates (agent updates)
To verify Microsoft Defender for Endpoint on Linux platform updates, run the following command line:
sudo yum update mdatp
or
apt-get update mdatp
depending on your package manager.
For more information, see Device health and Microsoft Defender antimalware health report.
To find the latest Broad channel release, visit What's new in Microsoft Defender for Endpoint on Linux.
How to update Microsoft Defender for Endpoint on Linux
Microsoft regularly publishes software updates to improve performance, security, and to deliver new features. To update Microsoft Defender for Endpoint on Linux. For more information, see Deploy updates for Microsoft Defender for Endpoint on Linux.
Note
If you have Redhat's Satellite (akin to WSUS in Windows), you can get the updated packages from it.
Tip
Automate the agent update on a monthly (Recommended) schedule by using a Cron job. For more information, see schedule an update of the Microsoft Defender for Endpoint on Linux.
Non-Windows endpoints
With macOS and Linux, you could take a couple of systems and run in the Beta channel.
Note
Ideally you should include one of each type of Linux system you are running in the Preview channel so that you are able to find compatibility, performance and reliability issues before the build makes it into the Current channel.
The choice of the channel determines the type and frequency of updates that are offered to your device. Devices in Beta are the first ones to receive updates and new features, followed later by Preview and lastly by Current.
In order to preview new features and provide early feedback, it's recommended that you configure some devices in your enterprise to use either Beta or Preview.
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.
18. Verify that you're able to get security intelligence updates (signatures/definition updates)
To verify Microsoft Defender for Endpoint on Linux signatures/definition updates, run the following command line:
mdatp definitions update
For more information, see New device health reporting for Microsoft Defender antimalware.
19. Test detections
To ensure that the device is correctly onboarded and reported to the service, run the following detection test:
Open a Terminal window and execute the following command to run an antimalware detection test:
curl -o /tmp/eicar.com.txt https://secure.eicar.org/eicar.com.txt
You can run additional detection tests on zip files using either of the following commands:
curl -o /tmp/eicar_com.zip https://secure.eicar.org/eicar_com.zip curl -o /tmp/eicarcom2.zip https://secure.eicar.org/eicarcom2.zip
Note
If the detections do not show up, it could be that you have set "allowedThreats" to allow in preferences via Ansible or Puppet.
Endpoint detection and response (EDR) detections, see Experience Microsoft Defender for Endpoint through simulated attacks. If the detection doesn't show up, then it could be that we're missing event or alerts in portal. For more information, see Troubleshoot missing events or alerts issues for Microsoft Defender for Endpoint on Linux.
For more information about unified submissions in Microsoft Defender XDR and the ability to submit False Positives and False Negatives through the portal, see Unified submissions in Microsoft Defender XDR now Generally Available! - Microsoft Tech Community.
20. Troubleshoot missing events or alerts issues for Microsoft Defender for Endpoint on Linux
For more information, see, Troubleshoot missing events or alerts issues for Microsoft Defender for Endpoint on Linux.
21. Troubleshoot High CPU utilization by ISVs, Linux apps, or scripts
If you observe that third-party ISVs, internally developed Linux apps, or scripts run into high CPU utilization, you take the following steps to investigate the cause.
- Identify the thread or process that's causing the symptom.
- Apply further diagnostic steps based on the identified process to address the issue.
Step 1: Identify the Microsoft Defender for Endpoint on Linux thread causing the symptom
Use the following syntaxes to help identify the process that is causing CPU overhead:
To get Microsoft Defender for Endpoint process ID causing the issue, run:
sudo top -c
To get more details on Microsoft Defender for Endpoint process, run:
sudo ps ax --no-headings -T -o user,pid,thcount,%cpu,sched,%mem,vsz,rss,tname,stat,start_time,time,ucmd,command |sort -nrk 3|grep mdatp
To identify the specific Microsoft Defender for Endpoint thread ID causing the highest CPU utilization within the process, run:
sudo ps -T -p <PID> >> Thread_with_highest_cpu_usage.log
The following table lists the processes that might cause a high CPU usage:
Process name | Component used | MDE engine used |
---|---|---|
wdavdaemon | FANotify | Antivirus & EDR |
wdavdaemon unprivileged | Antivirus engine | |
wdavdaemon edr | EDR engine | |
mdatp_audisp_plugin | audit framework (auditd) | Audit log ingestion |
Step 2: Apply further diagnostic steps based on the identified process
Now that you've identified the process that is causing the high CPU usage, use the corresponding diagnostic guidance in the following section.
For example, in the previous step, wdavdaemon unprivileged
was identified as the process that was causing high CPU usage. Based on the result, you can apply the guidance to check the wdavdaemon unprivileged process.
Use the following table to troubleshoot high CPU utilization:
Process name | Component used | Microsoft Defender for Endpoint engine used | Steps |
---|---|---|---|
wdavdaemon | FANotify | Antivirus & EDR | - Download and run Microsoft Defender for Endpoint Client Analyzer. For more information, see Run the client analyzer on macOS or Linux. - Collect diagnostic data using the Client analyzer tool. - Open a CSS support case with Microsoft. For more information, see CSS security support case. |
wdavdaemon unprivileged | N/A | Antivirus engine | The following diagram shows the workflow and steps required in order to add Antivirus exclusions. ![]() General troubleshooting guidance - If you have in-house apps/scripts or a legitimate third-party app/script getting flagged, Microsoft security researchers analyze suspicious files to determine if they're threats, unwanted applications, or normal files. Submit files you think are malware or files that you believe have been incorrectly classified as malware by using the unified submissions experience (for more information, see Unified submissions experience) or File submissions. - See troubleshoot performance issues for Microsoft Defender for Endpoint on Linux. - Download and run Microsoft Defender for Endpoint Client Analyzer. For more information, see Run the client analyzer on macOS or Linux. - Collect diagnostic data using the Client analyzer tool. - Open a CSS support case with Microsoft. For more information, see CSS security support case. |
wdavdaemon edr | N/A | EDR engine | The following diagram shows the workflow and steps to troubleshoot wdavedaemon_edr process issues. ![]() General troubleshooting guidance - If you have in-house apps/scripts or a legitimate third-party app/script getting flagged, Microsoft security researchers analyze suspicious files to determine if they're threats, unwanted applications, or normal files. Submit files you think are malware or files that you believe are incorrectly classified as malware by using the unified submissions experience (for more information, see Unified submissions experience) or File submissions. - See troubleshoot performance issues for Microsoft Defender for Endpoint on Linux. - Download and run Microsoft Defender for Endpoint Client Analyzer. For more information, see Run the client analyzer on macOS or Linux. - Collect diagnostic data using the Client analyzer tool. - Open a CSS support case with Microsoft. For more information, see CSS security support case. |
mdatp_audisp_plugin | Audit framework | Audit log ingestion | See Troubleshoot AuditD performance issues with Microsoft Defender for Endpoint on Linux. |
22. Uninstall your non-Microsoft solution
If at this point you have:
- Onboarded your organization's devices to Defender for Endpoint, and
- Microsoft Defender Antivirus is installed and enabled,
Then your next step is to uninstall your non-Microsoft antivirus, antimalware, and endpoint protection solution. When you uninstall your non-Microsoft solution, make sure to update your configuration to switch from Passive Mode to Active if you set Defender for Endpoint to Passive mode during the installation or configuration.
Diagnostic and troubleshooting resources
- Troubleshoot Microsoft Defender for Endpoint on Linux installation issues.
- Identify where to find detailed logs for installation issues.
- Troubleshooting steps for environments without proxy or with transparent proxy.
- Troubleshooting steps for environments with static proxy.
- Collect diagnostic information.
- Uninstall Defender for Endpoint on Linux.
- Troubleshoot performance issues for Microsoft Defender for Endpoint on Linux.
- Troubleshoot AuditD performance issues with Microsoft Defender for Endpoint on Linux.
Advanced Microsoft Defender for Endpoint capabilities
Boost protection of Linux estate with behavior monitoring
Note
The behavior monitoring functionality complements existing strong content-based capabilities, however you should carefully evaluate this feature in your environment before deploying it broadly since enabling behavioral monitoring consumes more resources and may cause performance issues.
References
Tip
Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.