Skip to main content

Onboarding Linux servers

Microsoft documentedDefender for Servers · Source checked 2026-10-22 · Not yet verified in tenant · Sources: [1][2][3][4][5][6][7][8][9][10][11][12][13][14][15][16][17][18][19][20][21][22][23]

What it is​

Defender for Endpoint on Linux is one package, mdatp, that carries the AV engine, the EDR sensor, vulnerability management and the mdatp CLI. You install it from Microsoft's package repo (packages.microsoft.com), then onboard it to your tenant with a Python script or a JSON file from the Defender portal. Once onboarded, the server shows up in the Defender device inventory like any other endpoint and is covered by whatever Defender for Servers plan the subscription has. See the overview for how the plans split.

There are five ways to get it on a box. The installer script mde_installer.sh and the newer Defender deployment tool wrap the repo setup, install and onboarding into one run. Manual repo setup is the same steps by hand. Defender for Cloud pushes the MDE.Linux VM extension to Azure VMs and Arc servers, which is covered in onboarding through Defender for Cloud. Ansible, Puppet and Chef just orchestrate one of the first two.

It is not a kernel module. Since agent 101.23082.0006 the supplementary event data comes from an eBPF sensor, and auditd is gone as a provider from 101.2408.0000. It is also not a full MDM. Policy comes from a JSON file you own, or from security settings management if you want the Intune policy model.

Licensing and prerequisites​

  • Servers: Defender for Servers Plan 1 or Plan 2, Defender for Endpoint for servers, or Defender for Business servers. Linux desktops (public preview) need MDE P2, which is in M365 E5 and E7.
  • Hardware minimums: 1 core, 1 GB RAM, 2 GB disk. Learn says more for high-throughput workloads.
  • systemd on the host. Device isolation needs iptables and ip6tables, or the -nft pair.
  • Root on the box, and an MDE RBAC role that can download onboarding packages.
  • Package dependencies: glibc >= 2.17 on RPM, libc6 >= 2.23 on DEB. Mariner needs attr, diffutils, libacl, libattr, libselinux-utils, selinux-policy, policycoreutils. uuid-runtime stopped being a dependency at 101.25042.0003.
  • Python 3 for the onboarding script. Defender for Cloud calls it out for RHEL 8.x and Ubuntu 20.04 or later.
  • Network: the streamlined connectivity URL set. Static and transparent proxies work. PAC, WPAD, authenticated proxies and TLS inspection do not. The deployment tool also needs msdefender.download.prss.microsoft.com on 443.

Supported distros from the prerequisites page, as of 2026-10-22:

Distrox64ARM64
RHEL7.2+, 8.x, 9.x, 10.x8.x, 9.x, 10.x
CentOS7.2+, 8.xnone
CentOS Stream8.x, 9.x, 10.x8.x, 9.x, 10.x
Ubuntu LTS16.04 to 26.0420.04 to 26.04
Ubuntu Pro22.04, 24.0422.04, 24.04
Debian9 to 1311, 12, 13
SLES12.x, 15.x, 16.x15 SP5, SP6, 16.x
openSUSE Leap15.6, 16.x15.6, 16.x
Oracle Linux7.2+, 8.x, 9.x, 10.x8.x, 9.x, 10.x
Amazon Linux2, 20232 (ends 2026-10-31, last build 101.25122.0004), 2023
Fedora33 to 4440 to 44
Rocky8.7+, 9.2+, 10.xsame
Alma8.4+, 9.2+, 10.xsame
Mariner22

Kernel: Learn calls the agent kernel-version agnostic on listed distros. Anything unlisted needs 3.10.0-327 or later and is unsupported anyway. Custom builds derived from a supported vendor distro are treated as custom configurations; support needs a repro on a clean image. The eBPF sensor has its own per-distro minimum kernels, listed under How it works.

Filesystems: real-time protection covers btrfs, ecryptfs, ext2/3/4, fuseblk, jfs, overlay, ramfs, reiserfs, tmpfs, udf, vfat, xfs. Custom scans add network and FUSE types including nfs, cifs, smb, glusterfs, lustre, s3fs, blobfuse. NFS v3 exports need no_root_squash or scans fail on permissions. Another fanotify-blocking product on the same host is unsupported and can hang the box; the exception is fapolicyd on RHEL and Fedora.

How it works​

Install drops the binaries under /opt/microsoft/mdatp, creates the mdatp system user and the mdatp systemd unit. Create the user yourself before install if you need a fixed UID and GID. The onboarding script or mdatp_onboard.json writes the tenant binding under /etc/opt/microsoft/mdatp/. On first start the daemon pulls definitions, then reports licensed true and an org_id. healthy stays false until definitions finish. The device appears in the portal in 5 to 20 minutes.

Two sensors matter. Real-time protection hooks file access through fanotify; that is why two fanotify-blocking products on one host is a hard no. Supplementary events (process, file, socket) come from the eBPF provider since 101.23082.0006, on by default. mdatp health shows supplementary_events_subsystem: ebpf. If eBPF is disabled or the kernel cannot run it, the agent drops to Netlink: process events keep flowing, file rename or unlink and socket events are lost. Auditd stopped being an option at 101.2408.0000, and 101.24072.0000 was the last build that carried it.

mdatp health output with the supplementary_events_subsystem field reading ebpf. Source: Microsoft Learn, CC BY 4.0.
mdatp health output with the supplementary_events_subsystem field reading ebpf. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22

eBPF minimum kernels from Learn: Ubuntu 16.04 4.15.0, Fedora 33 5.8.15, CentOS and RHEL 7.6 3.10.0-957.10, SLES 15 5.3.18-18.47, Debian 9 4.19.0, Oracle RHCK 7.9 3.10.0-1160, Oracle UEK 7.9 5.4, Amazon Linux 2 5.4.261-174.360, Rocky and Alma 8 4.18.0-425 and 4.18.0-305, Rocky and Alma 9 5.14.0-284. Check with uname -a.

Policy precedence is simple. Anything in mdatp_managed.json is [managed] and wins over local mdatp config values. Exclusions set in the managed file can only be removed there. The exclusionSettings.mergePolicy key set to admin_only throws away local exclusions in every scope; merge keeps both. The default enforcement level in the managed file schema is passive, so a file that sets nothing else silently leaves you in passive mode. Set enforcementLevel to real_time on purpose.

Updates are plain package updates from the same repo. Each build expires nine months after release; an expired build still gets definitions but reports missing license and healthy false. Channels are prod, insiders-slow and insiders-fast; changing channel means uninstall and reinstall. The MDE.Linux extension auto-updates unless the VM carries tag ExcludeMdeAutoUpdate = true.

Configure​

Onboarding package and deployment tool:

  1. Defender portal > System > Settings > Endpoints > Device management > Onboarding. Operating system: Linux Server. Deployment method: Local Script for the Python onboarding script, or "Your preferred Linux configuration management tool" for mdatp_onboard.json. Download WindowsDefenderATPOnboardingPackage.zip. Do not repackage it; Learn says that trips tamper alerts and breaks updates.
Onboarding page with Linux Server and Local Script selected before downloading the package. Source: Microsoft Learn, CC BY 4.0.
Onboarding page with Linux Server and Local Script selected before downloading the package. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22
  1. Same page, Linux: Defender deployment tool > Download package gives GatewayLinuxDefenderDeploymentTool.zip. The script inside installs and onboards in one run and is tenant-specific. GA since July 2026.
Download package button for the Defender deployment tool on the Linux onboarding page. Source: Microsoft Learn, CC BY 4.0.
Download package button for the Defender deployment tool on the Linux onboarding page. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22
  1. After a deployment tool run, Device inventory > device > Timeline, search DefenderDeployment. Steps are Start, Download, Prerequisite check, Installation, Sensor initialization, Sequence completion.
Device timeline filtered to the deployment tool events after a clean install. Source: Microsoft Learn, CC BY 4.0.
Device timeline filtered to the deployment tool events after a clean install. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22

Defender for Cloud path (details in onboarding through Defender for Cloud):

  1. Azure portal > Microsoft Defender for Cloud > Environment settings > subscription > Settings and monitoring > Endpoint protection > On > Continue > Save. First subscription in a tenant can take up to 12 hours, later ones about an hour. If the agent is already installed, Defender for Cloud detects it and reconfigures it. A device bound to another tenant is not reassigned; offboard it first.
Endpoint protection status toggle in Defender for Cloud environment settings. Source: Microsoft Learn, CC BY 4.0.
Endpoint protection status toggle in Defender for Cloud environment settings. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22
  1. Subscriptions created before summer 2021 show Partial. Select Fix > Missing components > Linux machines > Enable > Save.
Legacy subscription view enabling the Linux component of the Defender for Endpoint integration. Source: Microsoft Learn, CC BY 4.0.
Legacy subscription view enabling the Linux component of the Defender for Endpoint integration. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22

AV policy through security settings management (full setup in security settings management):

  1. Defender portal > Endpoints > Configuration management > Enforcement scope > enable Linux, All devices or On tagged devices with tag MDE-Management. Enrolment can take up to 24 hours. Agent 101.23052.0009 or later.
  2. Entra dynamic device group on Linux OS type.
  3. Intune > Endpoint security > Antivirus > Create policy > Platform Linux. Profiles: Microsoft Defender Antivirus, Microsoft Defender Antivirus exclusions. Global exclusions (AV plus EDR) live under Endpoint detection and response > Microsoft Defender Global Exclusions (AV+EDR) and only work on devices managed through this channel. Exclusions from all three profiles merge into one superset.
Intune antivirus policy overview page, the same report surface used for the Linux profiles. Source: Microsoft Learn, CC BY 4.0.
Intune antivirus policy overview page, the same report surface used for the Linux profiles. Source: Microsoft Learn, CC BY 4.0. · captured 2026-10-22

Settings worth getting right: enforcement level real_time not passive, behaviorMonitoring enabled (only works under real_time), cloudService.enabled true, automaticDefinitionUpdateEnabled true, unmonitoredFilesystems left at the default of cifs, fuse, nfs, nfs4, smb unless you want RTP walking network mounts.

Verify​

  • mdatp health: healthy true, licensed true, org_id matches the tenant, definitions_status up_to_date, real_time_protection_enabled true, supplementary_events_subsystem ebpf, conflicting_applications empty.
  • mdatp connectivity test: every CDN, gateway and events URL reads [OK].
  • EICAR download lands in mdatp threat list and is quarantined. To check an exclusion, drop EICAR inside the excluded folder; no detection means the exclusion works.
  • EDR DIY script raises an alert in the portal within minutes.
  • Defender portal > Device inventory: device present, OS Linux, sensor health Active. 5 to 20 minutes after onboarding.
  • Azure path: VM > Extensions > MDE.Linux shows Provisioning succeeded.
  • Security settings management: device page > MDE Enrollment status Success, Configuration management > Security policies tab lists the Linux AV policy.

eBPF state across the fleet, from the eBPF support page:

DeviceTvmInfoGathering
| where OSPlatform == "Linux"
| extend EbpfStatus = AdditionalFields["EBPF STATUS"]
| project DeviceName, OSPlatform, EbpfStatus, Timestamp

Agent version and expiry across the fleet, so you catch nine-month expiries before licensed flips to false:

DeviceTvmSoftwareInventory
| where SoftwareName == "defender_for_linux"
| project DeviceName, OSDistribution, SoftwareVersion
| order by SoftwareVersion asc

Deployment tool progress fleet-wide:

DeviceEvents
| where ActionType == "DefenderDeploymentToolEvent"
| summarize arg_max(Timestamp, *) by DeviceName
| project DeviceName, Timestamp, AdditionalFields

Troubleshoot​

SymptomLikely causeFix
licensed false, org_id blankOnboarding step skipped, or installer run without --onboardRun sudo python3 MicrosoftDefenderATPOnboardingLinuxServer.py or place mdatp_onboard.json in /etc/opt/microsoft/mdatp/. Re-check org_id.
licensed false, health_issues has missing license, was fine beforeBuild expired after nine months, or the device was offboardedmdatp health --field product_expiration. Update the package. If offboarded on purpose, uninstall.
healthy false right after installDefinitions still downloadingmdatp health --field definitions_status. Wait for up_to_date. If stuck, run mdatp connectivity test.
healthy false, conflicting_applications lists another productSecond fanotify-blocking agent on the hostRemove it, or set enforcementLevel to passive. fapolicyd on RHEL and Fedora is the only supported exception.
supplementary_events_subsystem not ebpf, file and socket events missing in timelineKernel below the eBPF minimum, unlisted distro, or provider disableduname -a against the eBPF kernel table. sudo mdatp config ebpf-supplementary-event-provider --value enabled. Netlink fallback keeps process events only.
Kernel panic or hang after enabling eBPFRHEL 8.1 with SAP, Oracle 8.8 UEK 5.15.0-0.30.20, Oracle 7.9 with kspliceMove to a kernel outside the known-bad list. Learn allows disabling the eBPF provider as a stopgap. For ksplice, stop mdatp around the patch window with cron.
Defender audit rules still present after moving to eBPFauditd in immutable mode froze the rules fileConfirm eBPF mode, delete /etc/audit/rules.d/mdatp.rules, reboot, sudo auditctl -l should show only your rules.
wdavdaemon high CPUOne process or path generating most scan eventsmdatp diagnostic real-time-protection-statistics --sort --top 4, then hot-event-sources and ebpf-statistics. Add a global process exclusion for the top initiator, AV exclusion for the hot path. Check nothing else is running RTP.
apt or dnf cannot find mdatp, or GPG errorWrong [distro]/[version]/[channel] in the repo URL, key in the wrong keyring for the releaseRebuild the repo file for the exact major. Debian 12 and Ubuntu 24.04 want /usr/share/keyrings/microsoft-prod.gpg; Debian 13 wants microsoft-2025.asc.
Dependency failure on installglibc or libc6 too old, Mariner selinux packages missingInstall the listed dependencies by hand, then retry. Older than 101.25032.0000 also wanted mde-netfilter.
mdatp.service not found or daemon will not startUnit file missing, /opt is a symlink, noexec mount, SELinux denial, mdatp user missingCopy /opt/microsoft/mdatp/conf/mdatp.service to the systemd path. Bind-mount /opt/microsoft. findmnt -T /opt. Create the user with useradd --system --no-create-home --user-group --shell /usr/sbin/nologin mdatp.
mdatp: command not foundSymlink missingsudo ln -sf /opt/microsoft/mdatp/sbin/wdavdaemonclient /usr/bin/mdatp
EICAR not detected, service runningFile on a filesystem RTP does not cover, or path is excludedfindmnt -T <file> against the supported list. mdatp exclusion list.
connectivity test fails, curl error 35 or 60, 502TLS inspection on the proxy, or PAC or authenticated proxyExempt the MDE URLs from inspection. `curl -v ...
Installed and licensed, but no telemetry and slow commandsProxy set for the package manager but not for the daemonmdatp config proxy set --value http://proxy:port, or cloudService.proxy in the managed file.
MDE.Linux extension failedPython 3 missing, /opt/microsoft/mdatp on noexec, fanotify conflict, Arc agent unhealthy, device bound to another tenantExtension log under /var/log/azure/Microsoft.Azure.AzureDefenderForServers.MDE.Linux/, /var/log/microsoft/mdatp/install.log, azcmagent show. Offboard from the old tenant first.
Managed settings not appliedInvalid JSON, wrong path, setting needs restartpython3 -m json.tool on the file. Path is /etc/opt/microsoft/mdatp/managed/mdatp_managed.json. cloud-diagnostic and log rotation need a daemon restart.
Linux AV policy from Intune never landsDevice not enrolled on the MDE-attach channel, agent older than 101.23052.0009, profile assigned to a user groupSee security settings management and MDE troubleshooting.

Gotchas and limits​

  • eBPF is the only supplementary provider on current builds. Auditd exclusions do not migrate. If a kernel cannot do eBPF you get Netlink, which drops file and socket events without any error. Check supplementary_events_subsystem on every onboarded box, not just the pilot.
  • The managed file default for enforcementLevel is passive. A file that only sets exclusions leaves AV passive. Set real_time explicitly. behaviorMonitoring and scanAfterDefinitionUpdate do nothing unless the level is real_time.
  • Global exclusions mute events at the sensor, so they remove EDR visibility too. No wildcards, no extensions, path must exist at the time you add it, and process exclusions need the full path. Use them for performance only, and keep AV-only epp exclusions for the rest. Exclusion paths must be hard paths, not symlinks.
  • Managed exclusions can only be removed from the managed file. mergePolicy admin_only wipes local ones silently.
  • Channel switch means uninstall and reinstall. Install path cannot change after install. Major OS version upgrades need uninstall, upgrade, reinstall.
  • Nine-month build expiry. Expired builds keep getting definitions but report missing license. Pin an update cadence, or let the MDE.Linux extension auto-update and tag ExcludeMdeAutoUpdate = true where you must freeze.
  • SELinux: Learn's install troubleshooting says set permissive to get the service started, then revert immediately. Defender for Cloud guidance says do not disable SELinux or mount protections as a first step. Treat permissive as a diagnostic, never a fix. Mariner pulls in the selinux packages as dependencies.
  • noexec on the filesystem holding /opt/microsoft/mdatp blocks wdavdaemon. Check with findmnt before deploying to hardened images. nonExecMountPolicy mute skips scanning noexec mounts; it does not fix this.
  • Container hosts: overlay is a supported RTP filesystem, so every layer write is a scan event. Learn says nothing specific about container hosts beyond that. TODO: lab-test exclusion strategy for a Docker or containerd host and record CPU before and after.
  • Two fanotify-blocking agents on one host can hang it. The installer's --skip_conflict flag exists; using it on a box with another AV is on you.
  • Onboarding and offboarding packages are tenant-specific; the offboarding package expires on the date in its filename. Repackaging either is unsupported and trips tamper alerts.
  • Offboarding leaves the package installed and licensed false. The portal marks the device inactive after 7 days and keeps the profile up to 180 days. Inactive is not proof of offboarding; check health_issues on the box.
  • Defender for Cloud does not auto-provision VMs built from generalized images. Use CLI, REST or Azure Policy for those. Enabling the Linux integration is one-way; disabling the plan does not undo it.
  • Linux desktop support is in public preview and licensed under MDE P2, not Defender for Servers. The agent decides server versus workstation from signals, and defaults to server when unsure. That changes which licence a device consumes.
  • Amazon Linux 2 ARM64 support ends 2026-10-31. Block upgrades past 101.25122.0004 or move the workload.

Further reading​

My notes​

TODO: Sohail's notes after verification.

Changelog​

DateChangeSource
2026-10-22Drafted from Learn, with Learn images and diagrams[1]