eBPF

Linux Kernel Capabilities for eBPF: Requirements and Safe Deployment

November 22, 2026
7
min read
eBPF

Every eBPF agent you evaluate raises the same question: what kernel access does it need, and can you grant less? In Kubernetes, the answer can determine whether a DaemonSet passes admission checks or gets rejected. Granting CAP_SYS_ADMIN simply to make an agent run may solve a permissions problem, but it also gives the agent far more access to the host than it needs.

The challenge is that eBPF programs don’t all require the same privileges. Tracing, networking, and security workloads have different permission requirements, and loading a program isn’t always the same as attaching it. This guide explains how to identify the capabilities each workload needs, check the permissions available to a process, and configure those grants in Kubernetes while accounting for the security risks that remain.

What Is CAP_BPF and Why Does eBPF Need It?

Linux capabilities divide the privileges traditionally held by the root user into separate permissions that can be granted independently. CAP_BPF is one such capability, introduced in Linux 5.8 to authorize privileged eBPF operations without granting the broader system administration permissions covered by CAP_SYS_ADMIN. It permits operations such as loading privileged eBPF programs and BTF data, but it isn’t sufficient for every workload. Tracing programs, including BPF LSM security programs, generally also require CAP_PERFMON, while networking programs commonly require CAP_NET_ADMIN. Certain operations still require CAP_SYS_ADMIN.

eBPF allows applications to execute programs at supported kernel hooks without loading kernel modules. For privileged operations, the kernel checks the calling process’s effective capability set rather than relying solely on whether it runs as root. A non-root process can hold the necessary capabilities, while root inside a container may lack permission over the host kernel. Without the required capabilities, processes are limited to the BPF operations permitted to unprivileged users.

How eBPF Program Loading Works

Before an eBPF program runs, the kernel checks the loader’s permissions and verifies the program’s instructions. The required permissions depend on the program type, helper functions, and attachment point.

Loading and Verifying eBPF Programs

A userspace loader submits compiled bytecode through the bpf() system call using BPF_PROG_LOAD. The kernel verifier checks control flow, memory bounds, and helper calls, rejecting programs that violate its safety rules.

The loader’s privileges affect program limits. Unprivileged programs are limited to 4,096 instructions, while programs loaded with the required capabilities can contain up to 1,000,000 instructions. The verifier also has a separate 1,000,000-instruction analysis budget, so a program can satisfy the size limit and still fail verification. Bugs in the verifier or kernel helpers can compromise these protections.

JIT Compilation and Bytecode

After verification, the kernel can interpret eBPF bytecode or use a just-in-time (JIT) compiler to translate it into native machine instructions. JIT compilation improves execution performance, but it doesn’t bypass verification. Defects in the JIT can still introduce security vulnerabilities.

The bpf_jit_harden setting enables constant blinding to reduce the risk of JIT-spraying attacks. Setting it to 1 protects programs loaded without CAP_BPF or CAP_SYS_ADMIN in the initial user namespace, while 2 enables hardening for all programs. These protections apply when JIT compilation is enabled.

Program Types and Attachment Points

Kprobes and uprobes trace kernel and userspace functions, tracepoints capture predefined events, XDP processes network packets, and BPF LSM programs can enforce security policies.

Loading and attaching are separate operations. A program may pass verification but still fail to attach because the process lacks permission to access the target hook or resource. Some tracing attachments use perf_event_open(), which has its own access checks involving CAP_PERFMON and the perf_event_paranoid setting.

Maps and Helper Functions

eBPF maps store data shared between eBPF programs and userspace applications. Creating maps through BPF_MAP_CREATE requires permissions that depend on the map type. Basic maps can be created without CAP_BPF when unprivileged BPF access is enabled, while some networking maps also require CAP_NET_ADMIN.

Helper functions let programs access kernel functionality they cannot implement directly. The available helpers depend on the program type and privileges. For example, CAP_PERFMON permits tracing helpers that read kernel memory and relaxes certain verifier restrictions, while bpf_probe_write_user() requires CAP_SYS_ADMIN.

Linux Capabilities Required to Load eBPF Programs

Before granting capabilities to an eBPF agent, identify the program types it loads and compare their requirements with the permissions available to its loader process. You can then configure the necessary capabilities through executable file permissions, systemd, or the container’s security context.

Capability Requirements by Hook and Program Type

On Linux 5.8 and newer, common eBPF program families have the following capability requirements:

Program FamilyProgram Types or OperationsRequired Capabilities
Tracing and securityKPROBE, TRACEPOINT, PERF_EVENT, RAW_TRACEPOINT, TRACING, LSMCAP_BPF + CAP_PERFMON
NetworkingXDP, SCHED_CLS, SCHED_ACT, SK_SKB, SK_MSG, SOCK_OPS, NETFILTER, selected cgroup program typesCAP_BPF + CAP_NET_ADMIN
Limited exceptionsSOCKET_FILTER, CGROUP_SKB, SK_REUSEPORTSOCKET_FILTER and CGROUP_SKB can load without capabilities when unprivileged BPF is enabled. SK_REUSEPORT requires CAP_BPF.
Restricted operationsbpf_probe_write_user(), hardware offload, BPF_F_ZERO_SEED, system-wide BPF object enumerationCAP_SYS_ADMIN

Some operations require additional permissions beyond the program type’s requirements. Creating networking maps such as SOCKMAP, SOCKHASH, and DEVMAP requires CAP_NET_ADMIN, while a networking program calling bpf_trace_printk() also needs CAP_PERFMON. The CGROUP_SKB program type has a separate attachment requirement: it can load without capabilities when unprivileged BPF is enabled, but attaching it to a cgroup requires CAP_NET_ADMIN and access to the target cgroup.

Effective, Permitted, and Inheritable Capability Sets

Linux maintains separate capability sets for each process thread. Three determine which privileges it can exercise or retain:

  • Effective (CapEff): Capabilities the kernel checks when the thread performs a privileged operation.
  • Permitted (CapPrm): Capabilities the thread can make effective without gaining new privileges.
  • Inheritable (CapInh): Capabilities preserved across program execution that can contribute to the new permitted set when combined with matching executable file capabilities.

The bounding set (CapBnd) limits capabilities gained through file permissions, while the ambient set (CapAmb) allows selected capabilities to survive execution of ordinary, non-privileged programs.

Inspect these sets for a running process by replacing 12345 with its PID:

grep '^Cap' /proc/12345/status

The output contains hexadecimal masks. Decode the effective set using capsh:

capsh --decode="$(awk '/^CapEff:/ {print "0x"$2}' /proc/12345/status)"

Alternatively, inspect the process’s capabilities directly:

getpcaps 12345

For an eBPF tracing loader, check that its effective set contains cap_bpf and cap_perfmon. Capabilities present only in CapPrm or CapInh do not authorize the current operation. The Linux capabilities manual describes how these sets change when a process executes another program.

Granting CAP_BPF to Executables and systemd Services

Linux file capabilities allow a native executable to receive specific privileges when launched, without requiring the user to run it as root.

For a trusted tracing loader installed at /usr/local/bin/ebpf-loader, grant CAP_BPF and CAP_PERFMON:

sudo setcap cap_bpf,cap_perfmon+ep /usr/local/bin/ebpf-loader

getcap /usr/local/bin/ebpf-loader

The expected getcap output is:

/usr/local/bin/ebpf-loader cap_perfmon,cap_bpf=ep

The +ep flags place these capabilities in the executable’s permitted set and enable them in the process’s effective set when it starts. The order of capability names in the output may differ.

File capabilities apply to executable files, not ordinary shell scripts. They also cannot override the process’s bounding set or no_new_privs restrictions. If the execution environment prevents the binary from obtaining capabilities marked effective in its file metadata, execution can fail with EPERM.

For a systemd-managed service, use ambient capabilities instead of modifying the executable. If the binary already has file capabilities from the previous example, remove them first:

sudo setcap -r /usr/local/bin/ebpf-loader

getcap /usr/local/bin/ebpf-loader

The second command should produce no capability listing. Then configure the service:

[Service]
User=ebpf-agent
ExecStart=/usr/local/bin/ebpf-loader
CapabilityBoundingSet=CAP_BPF CAP_PERFMON
AmbientCapabilities=CAP_BPF CAP_PERFMON
NoNewPrivileges=yes

The User and ExecStart values must refer to an existing service account and executable. AmbientCapabilities supplies the capabilities to the service process, while CapabilityBoundingSet prevents it from acquiring capabilities outside the specified set. NoNewPrivileges=yes blocks additional privilege gains through executable file permissions.

After applying the configuration and restarting the service, use systemctl show to inspect its main PID and getpcaps to verify the capabilities of the running process. If the loader performs additional host operations, those operations may require permissions beyond CAP_BPF and CAP_PERFMON.

Granting CAP_BPF to Containers and Kubernetes Pods

Docker supports individual capability grants through --cap-add, without enabling privileged mode. To check the capability masks inside a container, run:

docker run --rm \
  --cap-drop=ALL \
  --cap-add=BPF \
  --cap-add=PERFMON \
  ubuntu:24.04 \
  sh -c "grep '^Cap' /proc/1/status"

The command removes Docker’s default capability grants, adds CAP_BPF and CAP_PERFMON, and prints the container process’s capability masks. It verifies the grants, not whether a particular eBPF program can load.

Modern Docker seccomp rules conditionally allow bpf() when CAP_BPF is granted and perf_event_open() when CAP_PERFMON is granted. Older runtimes or custom security profiles may still block those calls, and user-namespace isolation can restrict access to host-level BPF operations.

In Kubernetes, grant the same capabilities through the container’s securityContext:

securityContext:
  privileged: false
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
    add:
      - BPF
      - PERFMON

Apply this configuration to the container running the eBPF loader, using the agent’s supported manifest or Helm values. It removes the container’s default capability grants and adds the two required for basic privileged tracing.

The allowPrivilegeEscalation: false setting activates no_new_privs, preventing subsequent privilege gains through setuid executables or file capabilities. It does not remove the capabilities already granted to the container process.

Kubernetes’ Baseline and Restricted Pod Security Standards reject Pods that add BPF or PERFMON, so the workload requires an approved namespace policy or admission exemption. Depending on the agent and runtime, access to host tracing resources and an appropriate seccomp profile may also be necessary.

Networking workloads may require NET_ADMIN, and some agents require additional host permissions. These examples apply to agents that explicitly support scoped Linux capabilities. They should not replace the supported configuration of agents that require privileged containers.

Unprivileged eBPF Restrictions

Linux controls access to the bpf() system call for unprivileged processes through unprivileged_bpf_disabled. Check the current value:

cat /proc/sys/kernel/unprivileged_bpf_disabled

The setting accepts three values:

  • 0: Unprivileged BPF access is enabled.
  • 1: Unprivileged BPF access is disabled and cannot be re-enabled until reboot.
  • 2: Unprivileged BPF access is disabled, but an administrator can re-enable it.

Enabling unprivileged BPF does not remove the capability requirements for tracing, XDP, or BPF LSM programs. A process running as root inside a container’s user namespace also cannot ordinarily load these privileged programs using namespace-local capabilities alone because BPF capability checks generally use the host’s initial user namespace.

BPF Tokens and Delegated Loading

Linux 6.9 introduced BPF tokens, which allow administrators to delegate selected BPF operations to processes in user namespaces. A token is created from a BPF filesystem mount configured with delegation permissions. The mount options specify which commands (delegate_cmds), map types (delegate_maps), program types (delegate_progs), and attachment types (delegate_attachs) the workload can use.

When a workload supplies a valid token, the relevant BPF capability checks use the user namespace associated with that token instead of the host’s initial namespace. This allows a container to load the BPF programs explicitly permitted by the administrator without receiving unrestricted host-level BPF privileges. Other kernel access checks still apply, and token-based delegation requires kernel support and explicit configuration. On kernels older than 6.9, workloads must rely on the appropriate host-level capabilities.

Deploying eBPF Agents Safely in Containers and Kubernetes

An eBPF agent runs inside a container, but its programs execute in the host kernel. The container therefore needs permission to load and attach those programs, along with access to the host resources they monitor. Kubernetes can restrict that access through Pod Security Admission, seccomp profiles, and volume-mount policies.

Agents that support scoped capabilities can use the securityContext grants covered earlier. Others require privileged containers because they access additional host resources. The following example uses groundcover’s eBPF sensor, which runs as a privileged DaemonSet to collect telemetry across Kubernetes nodes. Its supported deployment requires privileged access rather than a configuration limited to CAP_BPF and CAP_PERFMON.

Step 1: Check Kernel Support and Kubernetes Policies

An eBPF agent depends on the worker node’s kernel, not the Linux distribution inside its container image. Check which kernels your cluster runs:

kubectl get nodes \
  -o custom-columns=NODE:.metadata.name,OS:.status.nodeInfo.operatingSystem,KERNEL:.status.nodeInfo.kernelVersion

groundcover supports Linux 5.3 and newer on supported distributions and Kubernetes 1.21 or newer. Its sensor also uses Compile Once, Run Everywhere (CO-RE), which relies on BPF Type Format (BTF) data to handle differences between kernel versions.

Check whether BTF is available on each node. If you have permission to create node-debugging Pods, open a shell on the target node:

kubectl debug node/<NODE_NAME> -it \
  --image=busybox:1.36 -- sh

Inside the debugging container, inspect the node’s BTF file through the mounted host filesystem:

test -r /host/sys/kernel/btf/vmlinux \
  && echo "BTF available" \
  || echo "BTF unavailable"

BTF available confirms that the required file is readable. If it’s unavailable, verify the node’s kernel configuration or select a supported node image. Exit the shell and delete the debugging Pod created by kubectl debug. Node debugging also requires appropriate Kubernetes permissions and may be blocked by admission policies.

Next, create a dedicated namespace for the sensor:

kubectl create namespace groundcover \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl get namespace groundcover --show-labels

Kubernetes’ Baseline and Restricted Pod Security Standards prohibit privileged containers, host PID access, and hostPath mounts. Groundcover’s sensor uses these features to inspect processes and reach kernel tracing resources.

After approval from your cluster administrator, configure the dedicated namespace to admit privileged workloads:

kubectl label namespace groundcover \
  pod-security.kubernetes.io/enforce=privileged \
  --overwrite

This changes admission requirements for the entire namespace, not just the sensor. Restrict who can create or modify workloads there using Kubernetes RBAC. Other admission controllers may still enforce additional policies.

Step 2: Configure the Groundcover Sensor

A node-level agent needs access to kernel resources, but it also needs credentials to send the collected telemetry to its backend. Keep those credentials separate from the Helm values file.

After installing and authenticating the groundcover CLI, retrieve the sensor ingestion key:

groundcover auth get-ingestion-key sensor

Save the key in a protected file named sensor-ingestion-key.txt, then create the Kubernetes Secret:

kubectl -n groundcover create secret generic groundcover-api-key \
  --from-file=API_KEY=./sensor-ingestion-key.txt

Delete the local key file after creating the Secret. A Kubernetes secret manager can provision the same Secret for production deployments.

Create values.yaml with the Secret reference, your Groundcover ingestion endpoint, and the cluster identifiers:

global:
  groundcoverPredefinedTokenSecret:
    secretName: groundcover-api-key
    secretKey: API_KEY
  backend:
    enabled: false
  ingress:
    site: "<BYOC-endpoint>"

clusterId: "production-cluster"
env: "production"

agent:
  sensor:
    ebpfMode: enabled

Replace <BYOC-endpoint> with your workspace’s ingestion endpoint. The Secret reference allows the sensor to authenticate without embedding the key in the Helm configuration.

The ebpfMode: enabled setting requires successful eBPF initialization on sensor versions 1.13.289 and newer. If the kernel or permissions prevent initialization, the sensor won’t silently switch to resource-only collection. This makes initialization failures visible instead of leaving you with a running sensor that isn’t collecting the expected traces.

Step 3: Review and Install the Helm Chart

Before installing an eBPF agent, inspect the Kubernetes resources it will create. A DaemonSet gives the sensor coverage across eligible nodes, while its security context determines what host access each sensor Pod receives.

Add the Groundcover Helm repository and render the manifests:

helm repo add groundcover https://helm.groundcover.com
helm repo update groundcover

helm template groundcover groundcover/groundcover \
  --namespace groundcover \
  --values values.yaml > rendered.yaml

Inspect the sensor DaemonSet in rendered.yaml. Its container should have securityContext.privileged: true, and the Pod should have hostPID: true. The sensor deployment template also mounts host resources, including tracing filesystems and the host root filesystem.

These settings are part of the sensor’s supported deployment. Removing them to enforce a generic two-capability configuration can prevent the sensor from accessing the kernel resources it needs. For production, review the permissions during deployment approval and use a tested chart version.

Install the chart:

helm upgrade --install groundcover groundcover/groundcover \
  --namespace groundcover \
  --values values.yaml \
  --wait \
  --timeout 10m

Helm waits for the deployed resources to become ready, but a successful installation alone doesn’t establish that eBPF telemetry is being collected.

Step 4: Verify Permissions and eBPF Collection

Verification needs to answer three questions: did Kubernetes admit the sensor with its required privileges, is it running on the intended nodes, and is it collecting telemetry?

First, inspect the sensor DaemonSets:

kubectl -n groundcover get daemonsets \
  -l app.kubernetes.io/name=sensor \
  -o custom-columns='NAME:.metadata.name,PRIVILEGED:.spec.template.spec.containers[0].securityContext.privileged,HOST_PID:.spec.template.spec.hostPID,DESIRED:.status.desiredNumberScheduled,READY:.status.numberReady'

PRIVILEGED and HOST_PID should both be true. READY should equal DESIRED for each DaemonSet. Check that the desired count matches the eligible nodes you intend to monitor; a ready DaemonSet with no scheduled sensors doesn’t provide node coverage.

If any sensor is missing or fails to become ready, identify the affected Pods:

kubectl -n groundcover get pods \
  -l app.kubernetes.io/name=sensor -o wide

Check the Pod events with kubectl describe pod and inspect initialization logs:

kubectl -n groundcover logs \
  -l app.kubernetes.io/name=sensor \
  -c sensor \
  --tail=100 \
  --prefix \
  --max-log-requests=20

An admission rejection points to a Kubernetes policy problem. An Operation not permitted error may indicate a denied system call or inaccessible host resource, while a verifier rejection concerns the eBPF program itself. Adding more capabilities won’t resolve every initialization failure.

Finally, send requests to a supported application service and open Traces in groundcover. Filter by the relevant cluster and service, then confirm that traces from those requests appear.

A healthy Pod confirms the container is running. New application traces confirm that the sensor has initialized and is collecting the expected eBPF telemetry.

FAQs

Yes, if the agent supports scoped capabilities. On Linux 5.8 and newer, tracing workloads commonly use CAP_BPF and CAP_PERFMON, while networking workloads may also require CAP_NET_ADMIN. Additional permissions depend on the agent’s attachments and host access requirements. Some agents require privileged containers, so follow their supported deployment configuration.

CAP_BPF alone may not authorize the requested operation. Check the process’s effective capabilities, seccomp restrictions, user namespace, and additional permissions required by the program type or attachment point. Tracing programs commonly need CAP_PERFMON. If the kernel verifier rejects the program, inspect its verifier logs rather than granting more capabilities.

Not by itself. CAP_BPF authorizes privileged BPF operations, but tracing programs that access kernel memory generally also require CAP_PERFMON. Because tracing agents can observe sensitive application and kernel data, grant these capabilities only to trusted workloads.

Yes. An eBPF program can remain loaded if an attachment, pinned BPF object, or another kernel reference keeps it alive. Otherwise, the kernel releases it when its remaining references are closed. Removing capabilities from the loader does not automatically unload programs that remain attached.

Rootless containers cannot use namespace-local CAP_BPF to perform ordinary privileged BPF operations against the host kernel. Adding --cap-add=BPF does not bypass this restriction. Linux 6.9 and newer support BPF tokens for explicitly delegated operations, but their use requires appropriate kernel support and configuration.

Sign up for Updates

Keep up with all things cloud-native observability.

We care about data. Check out our privacy policy.