> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/requirements/kernel-requirements-for-ebpf-sensor.md).

# Kernel requirements for eBPF sensor

### Intro

groundcover’s eBPF sensor uses state-of-the-art kernel features to provide full coverage at low overhead. In order to do so it requires certain kernel features which are listed below.

{% hint style="info" %}
groundcover may work on many other linux kernels, but we might just didn't get a chance to test it yet. Can't find yours in the list? [let us know over Slack.](https://www.groundcover.com/join-slack)
{% endhint %}

### Kernel Version

Version v5.3 or higher (anything since 2020).

### Linux Distributions

| Name                    | Supported Versions     |
| ----------------------- | ---------------------- |
| Debian                  | 11+                    |
| RedHat Enterprise Linux | 8.2+                   |
| Ubuntu                  | 20.10+                 |
| CentOS                  | 7.3+                   |
| Fedora                  | 31+                    |
| BottlerocketOS          | 1.10+                  |
| Amazon Linux            | All off the shelf AMIs |
| Google COS              | All off the shelf AMIs |
| Azure Linux             | All off the shelf AMIs |
| Talos                   | 1.7.3+                 |

### Permissions

Loading eBPF code requires running privileged containers. While this might seem unusual, there's nothing to worry about - eBPF is [safe by design!](https://www.groundcover.com/ebpf#ebpf-security-how-to-maximize-ebpf-safety)

### CO:RE support

Our sensor uses eBPF’s [CO:RE](https://nakryiko.com/posts/bpf-portability-and-co-re/) feature in order to support the vast variety of linux kernels and distributions detailed above. This feature requires the kernel to be compiled with BTF information (enabled using the CONFIG\_BTF\_ENABLE=Y kernel compilation flag). This is the case for most common [distributions](https://github.com/libbpf/libbpf#bpf-co-re-compile-once--run-everywhere) nowadays.

You can check if your kernel has CO:RE support by manually looking for the BTF file:

```c
$ ls -la /sys/kernel/btf/vmlinux

- r--r--r--. 1 root root 3541561 Jun 2 18:16 /sys/kernel/btf/vmlinux
```

If the file exists, congratulations! Your kernel supported CO:RE.

### What happens if my kernel is not supported?

If your system does not fit into any of the above - unfortunately, our eBPF sensor will not be able to run on your environment. However, this does not mean groundcover won’t collect any data. You will still be able to inspect your [k8s environment](https://docs.groundcover.com/investigate/metrics/infrastructure-monitoring.md), see all [collected logs](https://docs.groundcover.com/investigate/logs/log-management.md) and use [integrations ](https://docs.groundcover.com/integrations/overview.md)with outer data sources.

In this case, [disable eBPF](#disabling-ebpf) in the sensor, or use [automatic fallback](#ebpf-modes-and-automatic-fallback) from groundcover version 1.13.289.

### eBPF modes and automatic fallback

Starting with groundcover version **1.13.289**, configure `agent.sensor.ebpfMode` in your Helm values to choose how the sensor handles eBPF availability:

| `ebpfMode`     | Behavior                                                                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `""` (default) | Follow `agent.sensor.ebpfEnabled`, which defaults to `true`.                                                                                  |
| `"enabled"`    | Require eBPF. Startup errors do not trigger automatic fallback.                                                                               |
| `"disabled"`   | Start without eBPF.                                                                                                                           |
| `"auto"`       | Try eBPF at startup and fall back to resource metrics if the kernel is unsupported or eBPF initialization or module loading returns an error. |

The defaults preserve the existing behavior:

```yaml
agent:
  sensor:
    ebpfEnabled: true
    ebpfMode: ""
```

An explicit `ebpfMode` overrides `ebpfEnabled`. For example, `ebpfMode: disabled` disables eBPF even when `ebpfEnabled: true`; `ebpfMode: auto` attempts eBPF even when `ebpfEnabled: false`. Use `disabled`, not `off`.

To enable automatic fallback:

```yaml
agent:
  sensor:
    ebpfMode: auto
```

Apply the values with `helm upgrade`. To enable automatic fallback only on selected nodes, set `ebpfMode: auto` under `sensor` in an `agent.extraSensorProfiles` entry, just as you would for `ebpfEnabled`.

In fallback mode, the sensor continues collecting host and container resource metrics, including CPU and memory, but stops collecting eBPF protocol traces and their derived APM metrics. Other data collection that does not depend on eBPF, such as logs and integrations, is unaffected.

Automatic fallback only handles startup failures. It does not switch a running sensor to resource-only mode after a later failure, and panics retain the existing failure behavior. The sensor tries eBPF again on its next restart.

On Linux hosts running version 1.13.289 or later, set `FLORA_EBPFMODE=auto` in `/etc/opt/groundcover/env.conf` and restart `groundcover-sensor`. An explicit `FLORA_EBPFMODE` overrides `FLORA_EBPFENABLED` in the same way. The install script rewrites `env.conf`, so reapply custom settings after an upgrade.

### Disabling eBPF

Disabling eBPF runs the sensor without loading any eBPF programs. When `ebpfMode` is unset or empty, the sensor follows `ebpfEnabled`, supplied through the `FLORA_EBPFENABLED` environment variable.

{% hint style="warning" %}
Traces, APM metrics and everything else built on eBPF data stop being collected. Logs, infrastructure metrics and integrations keep working.
{% endhint %}

#### Kubernetes

From Helm chart version 1.13.243, set `agent.sensor.ebpfEnabled` to `false`:

```yaml
agent:
  sensor:
    ebpfEnabled: false
```

The value must be a boolean. A quoted `"false"` fails the install. To disable eBPF only on some nodes, set `ebpfEnabled: false` under `sensor` in an `agent.extraSensorProfiles` entry instead.

On version 1.13.289 or later, if you have set an explicit `ebpfMode`, change it to `disabled` instead. Setting `ebpfEnabled: false` alone does not override an explicit mode.

On chart versions before 1.13.243, add the variable to the sensor directly:

```yaml
agent:
  sensor:
    env:
      - name: FLORA_EBPFENABLED
        value: "false"
```

`agent.sensor.env` is a list, so a new value replaces the whole list. If you already set other sensor environment variables, keep them in the same list.

Then apply the values:

```bash
helm upgrade groundcover groundcover/groundcover \
  -n groundcover \
  --reuse-values \
  -f values.yaml
```

#### Linux hosts

Add the variable to the sensor's environment file and restart the service:

```bash
echo "FLORA_EBPFENABLED=false" | sudo tee -a /etc/opt/groundcover/env.conf > /dev/null
sudo systemctl restart groundcover-sensor
```

The install script adds this line by itself on hosts without `/sys/kernel/btf/vmlinux`. Running the install script again rewrites `env.conf`, so add the line again after an upgrade on hosts that have BTF.

If `FLORA_EBPFMODE` is already set to `enabled` or `auto`, change it to `disabled` or remove it for `FLORA_EBPFENABLED=false` to take effect.

#### Docker Compose

The sensor's Docker Compose deployment runs without eBPF, and its `compose.yaml` already sets `FLORA_EBPFENABLED: "false"`.

#### Re-enabling eBPF

On Kubernetes, set `agent.sensor.ebpfEnabled` back to `true` and ensure `agent.sensor.ebpfMode` is unset or empty. Alternatively, on version 1.13.289 or later, set `agent.sensor.ebpfMode: enabled`. Remove or update any `FLORA_EBPFMODE` or `FLORA_EBPFENABLED` entries in `agent.sensor.env` that would override these values, then run `helm upgrade`.

On Linux hosts, remove `FLORA_EBPFENABLED=false` from `env.conf` or set it to `true`, and remove any `FLORA_EBPFMODE=disabled` line. Alternatively, on version 1.13.289 or later, set `FLORA_EBPFMODE=enabled`. Then restart `groundcover-sensor`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/requirements/kernel-requirements-for-ebpf-sensor.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
