Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(docs): specify distros and versions support #3808

Merged
merged 1 commit into from
Jan 16, 2024
Merged

chore(docs): specify distros and versions support #3808

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 50 additions & 11 deletions docs/docs/install/prerequisites.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,59 @@ every section should roughly cover:
4. link for details and help
-->

## Distributions and Linux Flavors

- List of supported environments:
- With BTFHUB (check BTF session below):
- Centos 8 (kernel < 4.18.0-193.el8)
- Debian 10 (buster) with v5.10 kernels
- Oracle Linux 7 and 8 with v5.4 kernels
- Red Hat 8 (kernel <= 4.18.0-147.57.1)
- SuSe 15.3 (kernel < 5.3.18-150300.59.90)
- Regular Build:
- Amazon Linux 2
- Centos 8 and newer
- Debian 11 (bullseye) and newer
- Fedora 38 and newer
- Oracle Linux 7, 8 (v5.4 kernels, some might need btfhub) and newer
- Red Hat 8 (newer v4.18 kernels) and newer
- SuSe 15.3 (newer kernels) and newer
- Possibly other distributions with recent kernels.
- Cloud Environments:
- Amazon EKS
- Azure AKS
- GKE (Google Kubernetes Engine): 5.4, 5.10, 5.15 and newer
- Minikube, Microk8s and other development environments

> This list is based on capabilities those versions provide and not necessarily
in tracee having all its features tested on each of them. Please provide
feedback if you face any issues in one of those environments.

## Kernel version

To run Tracee a modern longterm supported kernel is needed: 5.4, 5.10, 5.15, 5.18, 6.1, 6.2.
To run Tracee a modern longterm supported kernel is needed: 5.4, 5.10, 5.15, 6.2, 6.5

You can check [kernel.org](https://kernel.org) for current supported kernels.
In addition to upstream kernels, most distributions long-term supported kernels are supported as well, including CentOS8 4.18 kernel.
You can check [kernel.org](https://kernel.org) for current supported kernels. In
addition to upstream kernels, most distributions long-term supported kernels are
supported as well, including CentOS8 4.18 kernel.

## BTF

Tracee needs low-level type information about the running kernel. Most modern Linux distributions ship with the [BTF](https://www.kernel.org/doc/html/latest/bpf/btf.html) feature that exposes this information.
Tracee needs low-level type information about the running kernel. Most modern
Linux distributions ship with the [BTF](https://www.kernel.org/doc/html/latest/bpf/btf.html)
feature that exposes this information.

To test if this feature is enabled in your environment, check if `/sys/kernel/btf/vmlinux` exists. If absent, you might need to upgrade to a newer OS version, or contact your OS provider.
To test if this feature is enabled in your environment, check if
`/sys/kernel/btf/vmlinux` exists. If absent, you might need to upgrade to a
newer OS version, or contact your OS provider.

## Kernel symbols

Certain Tracee events require access to the Kernel Symbols Table, a feature present in many Linux distributions.
Certain Tracee events require access to the Kernel Symbols Table, a feature
present in many Linux distributions.

To test if this feature is enabled in your environment, check if `/proc/kallsyms` exists. If absent, contact your OS provider.
To test if this feature is enabled in your environment, check if
`/proc/kallsyms` exists. If absent, contact your OS provider.

Alternatively, you can disable the following events which depends on kallsyms:

Expand All @@ -43,7 +78,8 @@ For more information and help about kernel symbols, please see [here](../advance

## OS information

Tracee will try to probe the running OS and kernel to detect available capabilities. For this, it needs access to some standard informative files:
Tracee will try to probe the running OS and kernel to detect available
capabilities. For this, it needs access to some standard informative files:

- For OS information please make sure the file `/etc/os-release` is available.
- For Kernel information please make sure on of the files `/boot/config-$(uname-r)` OR `/proc/config.gz` is available.
Expand All @@ -52,9 +88,11 @@ For more information and help about OS info files, please see [here](../advanced

## Process capabilities

Tracee needs non-trivial capabilities to instrument the kernel. The easiest way is run Tracee as "privileged" or "root".
Tracee needs non-trivial capabilities to instrument the kernel. The easiest way
is run Tracee as "privileged" or "root".

If you want to run Tracee with "least privileges", here are the required capabilities and justifications:
If you want to run Tracee with "least privileges", here are the required
capabilities and justifications:

- Manage eBPF maps limits (`CAP_SYS_RESOURCE`)
- Load and Attach eBPF programs:
Expand All @@ -67,7 +105,8 @@ If you want to run Tracee with "least privileges", here are the required capabil
- On some environments (e.g. Ubuntu) `CAP_IPC_LOCK` might be required as well.
- On cgroup v1 environments, `CAP_SYS_ADMIN` is recommended if running from a container in order to allow tracee to mount the cpuset cgroup controller.

For more information and help about process capabilities, please see [here](../advanced/dropping-capabilities.md).
For more information and help about process capabilities, please see
[here](../advanced/dropping-capabilities.md).

## Processor architecture

Expand Down