mirror of
https://github.com/varun-r-mallya/Python-BPF.git
synced 2026-02-08 06:00:56 +00:00
160 lines
3.4 KiB
Markdown
160 lines
3.4 KiB
Markdown
# Installation
|
|
|
|
This guide will walk you through installing PythonBPF and its dependencies.
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
|
|
PythonBPF requires:
|
|
|
|
* **Linux** - eBPF is a Linux kernel feature (kernel 4.15 or higher recommended)
|
|
* **Python 3.10+** - Python 3.10 or higher is required
|
|
* **Root/sudo access** - Loading BPF programs into the kernel requires elevated privileges
|
|
|
|
### Required System Packages
|
|
|
|
Before installing PythonBPF, you need to install the following system packages:
|
|
|
|
#### On Ubuntu/Debian:
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install -y bpftool clang llvm
|
|
```
|
|
|
|
#### On Fedora/RHEL/CentOS:
|
|
|
|
```bash
|
|
sudo dnf install -y bpftool clang llvm
|
|
```
|
|
|
|
#### On Arch Linux:
|
|
|
|
```bash
|
|
sudo pacman -S bpf clang llvm
|
|
```
|
|
|
|
```{note}
|
|
The `llvm` package provides `llc`, the LLVM compiler that is used to compile LLVM IR to BPF bytecode.
|
|
```
|
|
|
|
## Installing PythonBPF
|
|
|
|
### From PyPI (Recommended)
|
|
|
|
The easiest way to install PythonBPF is using pip:
|
|
|
|
```bash
|
|
pip install pythonbpf pylibbpf
|
|
```
|
|
|
|
This will install:
|
|
* `pythonbpf` - The main package for writing and compiling BPF programs
|
|
* `pylibbpf` - Python bindings for libbpf, used to load and attach BPF programs
|
|
|
|
### Development Installation
|
|
|
|
If you want to contribute to PythonBPF or work with the latest development version:
|
|
|
|
1. Clone the repository:
|
|
|
|
```bash
|
|
git clone https://github.com/pythonbpf/Python-BPF.git
|
|
cd Python-BPF
|
|
```
|
|
|
|
2. Create and activate a virtual environment:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
```
|
|
|
|
3. Install in development mode:
|
|
|
|
```bash
|
|
pip install -e .
|
|
pip install pylibbpf
|
|
```
|
|
|
|
4. Install development dependencies:
|
|
|
|
```bash
|
|
make install
|
|
```
|
|
|
|
### Installing Documentation Dependencies
|
|
|
|
If you want to build the documentation locally:
|
|
|
|
```bash
|
|
pip install pythonbpf[docs]
|
|
# Or from the repository root:
|
|
pip install -e .[docs]
|
|
```
|
|
|
|
## Generating vmlinux.py
|
|
|
|
Some examples require access to kernel data structures. To use these features, you need to generate a `vmlinux.py` file:
|
|
|
|
1. Install additional dependencies:
|
|
|
|
```bash
|
|
pip install ctypeslib2
|
|
```
|
|
|
|
2. Generate the vmlinux.py file:
|
|
|
|
```bash
|
|
sudo tools/vmlinux-gen.py
|
|
```
|
|
|
|
3. Copy the generated file to your working directory or the examples directory as needed.
|
|
|
|
```{warning}
|
|
The `vmlinux.py` file is kernel-specific. If you upgrade your kernel, you may need to regenerate this file.
|
|
```
|
|
|
|
## Verifying Installation
|
|
|
|
To verify that PythonBPF is installed correctly, run:
|
|
|
|
```bash
|
|
python3 -c "import pythonbpf; print(pythonbpf.__all__)"
|
|
```
|
|
|
|
You should see output similar to:
|
|
|
|
```
|
|
['bpf', 'map', 'section', 'bpfglobal', 'struct', 'compile_to_ir', 'compile', 'BPF', 'trace_pipe', 'trace_fields']
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Permission Errors
|
|
|
|
If you encounter permission errors when running BPF programs:
|
|
|
|
* Make sure you're running with `sudo` or as root
|
|
* Check that `/sys/kernel/tracing/` is accessible
|
|
|
|
### LLVM/Clang Not Found
|
|
|
|
If you get errors about `llc` or `clang` not being found:
|
|
|
|
* Verify they're installed: `which llc` and `which clang`
|
|
* Check your PATH environment variable includes the LLVM bin directory
|
|
|
|
### Import Errors
|
|
|
|
If Python can't find the `pythonbpf` module:
|
|
|
|
* Make sure you've activated your virtual environment
|
|
* Verify installation with `pip list | grep pythonbpf`
|
|
* Try reinstalling: `pip install --force-reinstall pythonbpf`
|
|
|
|
## Next Steps
|
|
|
|
Now that you have PythonBPF installed, continue to the {doc}`quickstart` guide to write your first BPF program!
|