Fix systemd CAP_NET_ADMIN Not Set Error (2026)

The systemd-networkd service failed to start because it couldn’t acquire the CAP_NET_ADMIN capability, which it needs to manage network interfaces and configurations.

Common Causes and Fixes

1. Incorrect CAP_NET_ADMIN Configuration in systemd-networkd Unit File:

   • Diagnosis: Inspect the systemd-networkd service unit file, typically located at /usr/lib/systemd/system/systemd-networkd.service or /etc/systemd/system/systemd-networkd.service. Look for lines related to capabilities. If you see CapabilityBoundingSet=CAP_NET_RAW or similar, it’s missing CAP_NET_ADMIN.
   • Fix: Add CAP_NET_ADMIN to the CapabilityBoundingSet= directive. If the line doesn’t exist, create it. In /etc/systemd/system/systemd-networkd.service.d/override.conf (or directly in the main unit file if you prefer), add:

     [Service]
     CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_SETUID CAP_SETGID CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_KILL CAP_SYS_CHROOT CAP_AUDIT_WRITE CAP_GROUP_SU_ID CAP_NET_BIND_SERVICE CAP_NET_BROADCAST CAP_NET_RAW CAP_SETFCAP CAP_SETUID CAP_SYS_CHROOT CAP_SYS_MODULE CAP_SYS_PTRACE CAP_SYS_RAWIO CAP_SYS_TIME CAP_SYS_TTY_CONFIG
     

     (Note: The exact list of capabilities might vary slightly based on your systemd version and distribution, but CAP_NET_ADMIN is the critical one here. The provided list is a common, comprehensive set for network-related services. You can also explicitly add CAP_NET_ADMIN to AmbientCapabilities= if you want it to be effective even after dropping privileges.)
   • Why it works: CapabilityBoundingSet restricts the capabilities a service can ever gain. By explicitly including CAP_NET_ADMIN in this set, you allow systemd-networkd to request and use this specific privilege, which is essential for its network management tasks.

2. Security Module (SELinux/AppArmor) Restrictions:

   • Diagnosis: Check system logs for SELinux or AppArmor denials related to systemd-networkd. For SELinux, use sudo ausearch -m avc -ts recent. For AppArmor, check sudo dmesg | grep -i apparmor or /var/log/audit/audit.log. Look for messages indicating systemd-networkd is denied setcap or cap_net_admin operations.
   • Fix (SELinux): If SELinux is the culprit, you might need to adjust its policy. A common workaround (though not always ideal for production) is to set permissive mode temporarily: sudo setenforce 0. For a more permanent fix, you’d need to create or modify an SELinux policy module. A simpler approach might be to ensure the networkd_manage_etc_files boolean is enabled if applicable, or to explicitly grant the capability:

     sudo semanage fcap -a -t cap_net_admin_t -f /usr/lib/systemd/systemd-networkd
     

     (This command associates the cap_net_admin capability with the systemd-networkd executable. You might need to install policycoreutils-python-utils for semanage.)
   • Fix (AppArmor): If AppArmor is blocking it, you might find a profile for systemd-networkd in /etc/apparmor.d/. You can edit the profile to allow the necessary operations. For example, you might need to add a line like:

     capability net_admin,
     

     Then reload AppArmor: sudo systemctl reload apparmor.
   • Why it works: Security modules enforce granular access controls. If SELinux or AppArmor incorrectly assumes systemd-networkd shouldn’t have CAP_NET_ADMIN, they will block it. Adjusting the security policy or temporarily relaxing it allows systemd-networkd to obtain the capability.

3. Container/Virtualization Environment Limitations:

   • Diagnosis: If systemd-networkd is running inside a container (e.g., Docker, LXC) or a heavily sandboxed environment, the container runtime or hypervisor might be preventing the process from acquiring elevated capabilities. Check the container’s runtime configuration or documentation.
   • Fix: When running the container, ensure it has sufficient privileges. For Docker, this might involve using the --cap-add=NET_ADMIN flag:

     docker run --cap-add=NET_ADMIN ... your_image ...
     

     For LXC, you might need to adjust the lxc.cap.keep or lxc.cap.effective settings in the container’s configuration file.
   • Why it works: Container runtimes and virtualization platforms often isolate processes by default. Explicitly granting NET_ADMIN capability to the container process allows systemd-networkd within the container to perform its network operations.

4. Systemd Version or Distribution-Specific Defaults:

   • Diagnosis: Older versions of systemd or specific Linux distributions might have different default capability settings or security hardening applied to systemd-networkd. Consult the release notes or documentation for your specific systemd version and distribution.
   • Fix: This often ties back to Cause 1. You might need to manually add CAP_NET_ADMIN to the CapabilityBoundingSet or AmbientCapabilities in the systemd-networkd.service unit file, as newer versions might have tightened defaults, or older ones might not have had it enabled by default.
   • Why it works: Explicitly defining the required capabilities in the service unit file overrides any potentially restrictive or missing defaults from the systemd version or distribution configuration.

5. Filesystem Mount Options (noexec, nosuid, nodev):

   • Diagnosis: While less common for the executable itself, if the filesystem where systemd-networkd resides (or where it needs to write temporary files or socket files) is mounted with restrictive options like noexec (prevents execution), it could theoretically interfere, though CAP_NET_ADMIN is more about process privileges than filesystem execution. More relevantly, if /proc or /sys are mounted with unusual options that restrict access to kernel interfaces, this could be an issue. Check mount output for / and /proc, /sys.
   • Fix: Ensure that critical system filesystems, especially /proc and /sys, are mounted with standard options that allow kernel interface access. /proc should typically not have hidepid or read-only, and /sys should not be ro if systemd-networkd needs to write to it (which it does for network configuration). Edit /etc/fstab and remount if necessary (e.g., sudo mount -o remount,rw /sys).
   • Why it works: CAP_NET_ADMIN operations often involve direct interaction with the kernel via /proc and /sys interfaces. Restrictive mount options on these virtual filesystems can prevent systemd-networkd from successfully communicating with the kernel to perform network configuration, even if it technically has the capability.

6. External Tools Interfering with Capabilities:

   • Diagnosis: If you have other tools that manage network capabilities or security contexts (e.g., custom init scripts, other network managers) that might be running concurrently or have modified system defaults, they could be stripping capabilities or interfering. Check ps auxZ | grep systemd-networkd for SELinux contexts or aa-status for AppArmor.
   • Fix: Ensure that no other process is actively trying to manage systemd-networkd’s capabilities. If you are using multiple network management tools, disable all but one. If custom scripts are involved, review them for any setcap or capability manipulation commands that might affect systemd-networkd.
   • Why it works: Capabilities are a fine-grained privilege system. If another process or configuration is actively removing or overriding the capabilities assigned to systemd-networkd, it will lose the necessary permissions.

After fixing the CAP_NET_ADMIN issue, you might encounter a "Failed to read network configuration" error if your .network files in /etc/systemd/network/ are malformed or missing.