Credentials Microsoft Certified Trainer (MCT) 2026Microsoft Innovative Educator Expert 2025–2026Microsoft Elevate Educator Expert 2026–2027ISC2 Certified Information Systems Security Professional (CISSP)Microsoft 365 Certified: Enterprise Administrator Expert (MS-102)Microsoft Certified: Azure Solutions Architect Expert (AZ-305)PMI Project Management Professional (PMP) 28 certifications · see all Verify on Credly
Omer EltayebMicrosoft 365
LinkedIn
  1. Home
  2. Articles
  3. Defender
DefenderTroubleshooting

Defender for Endpoint on Linux: installation, onboarding and mdatp health errors

Fix Defender for Endpoint on Linux when the package, service or onboarding fails: read mdatp health, test cloud connectivity, handle real-time protection problems and verify.

Omer Eltayeb 4 min read Checked against Microsoft Learn

Defender for Endpoint on Linux is run from the command line, so problems show up in two places: the package manager during installation, and the mdatp health output afterwards. In this post I'll work through the checks in order (package, service, onboarding, cloud connectivity and real-time protection), with the commands to run and what good output looks like.

Errors this guide fixes

  • mdatp: command not foundTerminal
  • Failed to start mdatp.service: Unit mdatp.service not found.Terminal (systemctl)
  • healthy: falseTerminal (mdatp health)
  • licensed: falseTerminal (mdatp health)
  • org_id: unavailableTerminal (mdatp health)
  • engine_load_status: Engine not loadedTerminal (mdatp health)
  • definitions_status: unavailableTerminal (mdatp health)
  • real_time_protection_subsystem: unavailableTerminal (mdatp health)
Jump to the fix Browse the Microsoft 365 error library
How this guide is organized: Symptoms → Why it happens → How to fix it → Verify the fix → Prevent it next timeFlow diagram of the article's sections in reading order: 1. Symptoms. 2. Why it happens. 3. How to fix it (7 steps: Confirm the installation finished; Get the service running; Onboard and confirm the tenant; Test cloud connectivity; Read the health fields; and 2 more). 4. Verify the fix. 5. Prevent it next time. Toolbox: mdatp, Device management › Onboarding, /opt, org_id, [OK].1Symptoms2Why it happens3How to fix it4Verify the fix5Prevent it nexttime1Confirm theinstallation fin…2Get the servicerunning3Onboard andconfirm the t…4Test cloudconnectivity5Read thehealth fields+2 moreTOOLBOXmdatpDevice management › Onboarding/optorg_id[OK]How this guide is organized: Symptoms → Why it happens → How to fix it → Verify the fix → Prevent it next timeFlow diagram of the article's sections in reading order: 1. Symptoms. 2. Why it happens. 3. How to fix it (7 steps: Confirm the installation finished; Get the service running; Onboard and confirm the tenant; Test cloud connectivity; Read the health fields; and 2 more). 4. Verify the fix. 5. Prevent it next time. Toolbox: mdatp, Device management › Onboarding, /opt, org_id, [OK].1Symptoms2Why it happens3How to fix it1Confirm the installation finished2Get the service running3Onboard and confirm the tenant4Test cloud connectivity5Read the health fields+2 more4Verify the fix5Prevent it next timeTOOLBOXmdatpDevice management › Onboarding/optorg_id[OK]
At a glance: how this guide is organized · 7 fix steps · 5 key tools

Symptoms#

  • The package installs, but the tool doesn't run: mdatp: command not found.
  • The service won't start: Failed to start mdatp.service: Unit mdatp.service not found.
  • mdatp health reports one or more of these values (column spacing trimmed):
Text
healthy: false
licensed: false
org_id: unavailable
engine_load_status: Engine not loaded
definitions_status: unavailable
real_time_protection_subsystem: unavailable
  • The server never shows up in the Microsoft Defender portal, the EICAR test file isn't detected, or the workload slows down after deployment.

Why it happens#

Finding the failed check in Defender for Endpoint on LinuxDoes the install log show a postinstall end line? if No: Fix the package dependencies (Install the required versions, then run the package manager again.); if Yes: Does systemctl status mdatp show the service running? if No: Fix the service account or unit file (Then check SELinux, a /opt symlink and noexec mounts.); if Yes: Is licensed true, with your own tenant's org_id? if No: Run your tenant's onboarding script (Installing the package alone doesn't onboard the server.); if Yes: Run mdatp connectivity test (If a line isn't [OK], remove TLS inspection; use a static or transparent proxy.)Does the install log show apostinstall end line?FIXFix the packagedependenciesInstall the required versions,then run the packagemanager again.NoDoes systemctl status mdatpshow the service running?FIXFix the service accountor unit fileThen check SELinux, a /optsymlink and noexecmounts.NoIs licensed true, with your owntenant's org_id?FIXRun your tenant'sonboarding scriptInstalling the package alonedoesn't onboard the server.NoFIXRun mdatp connectivitytestIf a line isn't [OK], removeTLS inspection; use a staticor transparent proxy.YesYesYesFinding the failed check in Defender for Endpoint on LinuxDoes the install log show a postinstall end line? if No: Fix the package dependencies (Install the required versions, then run the package manager again.); if Yes: Does systemctl status mdatp show the service running? if No: Fix the service account or unit file (Then check SELinux, a /opt symlink and noexec mounts.); if Yes: Is licensed true, with your own tenant's org_id? if No: Run your tenant's onboarding script (Installing the package alone doesn't onboard the server.); if Yes: Run mdatp connectivity test (If a line isn't [OK], remove TLS inspection; use a static or transparent proxy.)Does the install log show a postinstall end line?NoFIXFix the package dependenciesInstall the required versions, then run the packagemanager again.YesDoes systemctl status mdatp show theservice running?NoFIXFix the service account or unit fileThen check SELinux, a /opt symlink and noexecmounts.YesIs licensed true, with your own tenant'sorg_id?NoFIXRun your tenant's onboarding scriptInstalling the package alone doesn't onboardthe server.YesFIXRun mdatp connectivity testIf a line isn't [OK], remove TLS inspection;use a static or transparent proxy.
Figure 1 · Decision tree Finding the failed check in Defender for Endpoint on Linux. Work down in the same order as the fixes: package, service, onboarding, then cloud connectivity. Stop at the first No.
  • Package or dependency problems. The package must match the distribution and version. The RPM package needs glibc 2.17 or later and the DEB package needs libc6 2.23 or later; versions before 101.25032.0000 also needed mde-netfilter and the PCRE library.
  • The daemon can't start. The mdatp service account or unit file is missing, SELinux is enforcing, /opt is a symbolic link, or wdavdaemon isn't executable or sits on a noexec mount.
  • Onboarding didn't happen. Installing the package isn't enough: until the onboarding script runs, licensed is false and org_id is unavailable.
  • Cloud connectivity. Only static or transparent proxies are supported. PAC, WPAD and authenticated proxies aren't, and TLS inspection breaks the connection.
  • Real-time protection. Files on unsupported file systems aren't scanned on access, and other security tools or very busy paths can cause conflicts and high CPU.

How to fix it#

1. Confirm the installation finished#

Bash
sudo journalctl --no-pager | grep 'microsoft-mdatp' > installation.log
grep 'postinstall end' installation.log

A postinstall end line with the time of your installation means the package installed. If the package manager reported missing dependencies, install the required versions and run it again. For new deployments, Microsoft's installer script mde_installer.sh picks the right repository and package and can onboard in the same run:

Bash
sudo ./mde_installer.sh --install --channel prod --onboard ./MicrosoftDefenderATPOnboardingLinuxServer.py

2. Get the service running#

Bash
sudo systemctl status mdatp
id mdatp
sudo useradd --system --no-create-home --user-group --shell /usr/sbin/nologin mdatp   # only if id returned nothing
sudo service mdatp restart

If the unit isn't found, copy /opt/microsoft/mdatp/conf/mdatp.service to /lib/systemd/system (Ubuntu, Debian) or /usr/lib/systemd/system (RHEL, Oracle, SLES), run sudo systemctl daemon-reload and start it again. Still failing? Check that ls -l /opt/microsoft/mdatp/sbin/wdavdaemon shows -rwxr-xr-x, that the file system isn't mounted noexec, and use a bind mount for /opt/microsoft if /opt is a symlink. Microsoft suggests testing with SELinux in permissive mode only briefly, then reverting immediately. For mdatp: command not found, recreate the link:

Bash
sudo ln -sf /opt/microsoft/mdatp/sbin/wdavdaemonclient /usr/bin/mdatp

3. Onboard and confirm the tenant#

Download the Linux onboarding package from Settings › Endpoints › Device management › Onboarding in the Microsoft Defender portal and run it:

Bash
sudo python3 MicrosoftDefenderATPOnboardingLinuxServer.py
mdatp health --field licensed
mdatp health --field org_id

You want true and your own tenant's organization ID. A different ID means the server was onboarded with another tenant's package.

4. Test cloud connectivity#

Bash
mdatp connectivity test

Every line should end in [OK]. If one doesn't, check whether TLS inspection is in the path: the certificate issuer for a Defender URL must be Microsoft, not your proxy's CA.

Bash
openssl s_client -connect x.cp.wd.microsoft.com:443 -servername x.cp.wd.microsoft.com </dev/null 2>/dev/null | openssl x509 -noout -issuer

Exempt the Defender for Endpoint domains from inspection, use a static or transparent proxy, then run sudo systemctl restart mdatp and test again. The URL list and proxy options are in moving to streamlined connectivity.

5. Read the health fields#

FieldGood valueIf not
healthy / health_issuestrue / empty listWork through the issues listed
licensed, org_idtrue, your tenantStep 3
definitions_statusup_to_dateStep 4; check definitions_updated_minutes_ago
engine_load_statusEngine load succeededStep 2, then collect diagnostics
real_time_protection_enabled, real_time_protection_subsystemtrue, a subsystem nameCheck policy, then step 6
supplementary_events_subsystemebpf (default from 101.2408.0000) or auditdCheck mdatp health --details edr
conflicting_applicationsEmptyRemove or coordinate the other security tool

mdatp health --details edr and mdatp health --details definitions show more detail per component; passive_mode_enabled tells you whether the antivirus runs in passive mode, as described in passive mode and EDR in block mode.

6. Fix detection and performance problems#

If the service is healthy but the EICAR test file isn't detected, run findmnt -T <path> on the file's folder: files on file systems that on-access scanning doesn't support aren't scanned. For high CPU, confirm the cause by turning real-time protection off for a short test (sudo mdatp config real-time-protection --value disabled, then --value enabled again), and review the scan statistics:

Bash
mdatp diagnostic real-time-protection-statistics --output json > rtp-stats.json
mdatp exclusion folder add --path /var/lib/myapp/data/
mdatp exclusion list

Keep exclusions narrow (a busy data folder of a trusted application, not / or /tmp), and if the server gets its settings from policy, add them there instead of locally.

7. Collect diagnostics#

If none of this helps, run sudo mdatp diagnostic create. It prints Diagnostic file created: followed by the path of a zip file to attach to a support case.

Verify the fix#

  • mdatp health --field healthy returns true and health_issues is empty.
  • mdatp connectivity test shows [OK] for every URL.
  • An EICAR test file is detected and appears in mdatp threat list.
  • The server appears in the Defender portal's device inventory, and its device ID matches mdatp health --field edr_machine_id.

Prevent it next time#

  • Check Microsoft's supported distributions and kernel versions before rollout, and deploy with the installer script or your configuration management tool rather than by hand.
  • After agent upgrades and reboots, re-run mdatp health and read the Linux release notes for known issues in your build.
  • Watch the sensor health state in the device inventory; Inactive and No sensor data explains each state.
  • For Macs, the same mdatp commands apply; see onboarding macOS with Intune.

References#

TagsDefender for EndpointLinuxmdatpOnboarding

Written and checked against current Microsoft Learn documentation. Test changes with a pilot group before rolling them out to everyone, and if an admin center path has moved since, search for the setting name instead.

Spotted a mistake, or did this fix work differently for you? Email me or message me on LinkedIn — corrections are credited in the article.

Written by

Omer Eltayeb

M365 Subject Matter Expert, former Microsoft Cloud Solutions Architect, Microsoft Certified Trainer and Microsoft Innovative Educator Expert (2024–26) and Microsoft Elevate Educator Expert (2026–27). I share practical, step-by-step guides, study plans, scripts and toolkits for Microsoft Intune, Configuration Manager, Microsoft Entra ID, Microsoft Defender, Exchange and Microsoft 365 with the community.

Microsoft Certified Trainer (MCT) 2026Microsoft Innovative Educator Expert 2025–2026Microsoft Elevate Educator Expert 2026–2027ISC2 Certified Information Systems Security Professional (CISSP)Microsoft 365 Certified: Enterprise Administrator Expert (MS-102)
Connect on LinkedIn My community contributions More about me
Keep reading

More Defender articles

All Defender articles