Quick Start

This guide will walk you through creating your first BPF program with PythonBPF.

Your First BPF Program

Let’s create a simple “Hello World” program that prints a message every time a process is executed on your system.

Step 1: Create the Program

Create a new file called hello_world.py:

from pythonbpf import bpf, section, bpfglobal, BPF, trace_pipe
from ctypes import c_void_p, c_int64

@bpf
@section("tracepoint/syscalls/sys_enter_execve")
def hello_world(ctx: c_void_p) -> c_int64:
    print("Hello, World!")
    return 0

@bpf
@bpfglobal
def LICENSE() -> str:
    return "GPL"

b = BPF()
b.load()
b.attach_all()
trace_pipe()

Step 2: Run the Program

Run the program with sudo (required for BPF operations):

sudo python3 hello_world.py

Step 3: See it in Action

Open another terminal and run any command:

ls
echo "test"
date

You should see “Hello, World!” printed in the first terminal for each command executed!

Press Ctrl+C to stop the program.

Understanding the Code

Let’s break down what each part does:

Imports

from pythonbpf import bpf, section, bpfglobal, BPF, trace_pipe
from ctypes import c_void_p, c_int64

  • bpf - Decorator to mark functions for BPF compilation

  • section - Decorator to specify which kernel event to attach to

  • bpfglobal - Decorator for BPF global variables

  • BPF - Class to compile, load, and attach BPF programs

  • trace_pipe - Utility to read kernel trace output (similar to BCC)

  • c_void_p, c_int64 - C types for function signatures

The BPF Function

@bpf
@section("tracepoint/syscalls/sys_enter_execve")
def hello_world(ctx: c_void_p) -> c_int64:
    print("Hello, World!")
    return 0

  • @bpf - Marks this function to be compiled to BPF bytecode

  • @section("tracepoint/syscalls/sys_enter_execve") - Attaches to the execve syscall tracepoint (called when processes start)

  • ctx: c_void_p - Context parameter (required for all BPF functions)

  • print() - the PythonBPF API for bpf_printk helper function

  • return 0 - BPF functions must return an integer

License Declaration

@bpf
@bpfglobal
def LICENSE() -> str:
    return "GPL"

  • The Linux kernel requires BPF programs to declare a license

  • Most kernel features require GPL-compatible licenses

  • This is defined as a BPF global variable

Compilation and Execution

b = BPF()
b.load()
b.attach_all()
trace_pipe()

  • BPF() - Creates a BPF object and compiles the current file

  • b.load() - Loads the compiled BPF program into the kernel

  • b.attach_all() - Attaches all BPF programs to their specified hooks

  • trace_pipe() - Reads and displays output from the kernel trace buffer

Alternatively, you can also use the compile() function to compile the BPF code to an object file:

from pythonbpf import compile

This object file can then be loaded using any other userspace library in any language.

Next Example: Tracking Process IDs

Let’s make a more interesting program that tracks which processes are being created:

from pythonbpf import bpf, section, bpfglobal, BPF, trace_pipe
from pythonbpf.helper import pid
from ctypes import c_void_p, c_int64

@bpf
@section("tracepoint/syscalls/sys_enter_execve")
def track_exec(ctx: c_void_p) -> c_int64:
    process_id = pid()
    print(f"Process with PID: {process_id} is starting")
    return 0

@bpf
@bpfglobal
def LICENSE() -> str:
    return "GPL"

b = BPF()
b.load()
b.attach_all()
trace_pipe()

This program uses BPF helper functions:

  • pid() - Gets the current process ID

Run it with sudo python3 track_exec.py and watch processes being created!

Common Patterns

Tracepoints

Tracepoints are predefined hooks in the kernel. Common ones include:

# System calls
@section("tracepoint/syscalls/sys_enter_execve")
@section("tracepoint/syscalls/sys_enter_clone")
@section("tracepoint/syscalls/sys_enter_open")

# Scheduler events
@section("tracepoint/sched/sched_process_fork")
@section("tracepoint/sched/sched_switch")

Kprobes

Kprobes allow you to attach to any kernel function:

@section("kprobe/do_sys_open")
def trace_open(ctx: c_void_p) -> c_int64:
    print("File is being opened")
    return 0

XDP (eXpress Data Path)

For network packet processing:

from pythonbpf.helper import XDP_PASS

@section("xdp")
def xdp_pass(ctx: c_void_p) -> c_int64:
    return XDP_PASS

Best Practices

  1. Always include a LICENSE - Required by the kernel

  2. Use type hints - Required by PythonBPF to generate correct code

  3. Return the correct type - Match the expected return type for your program type

  4. Test incrementally - Start simple and add complexity gradually

  5. Check kernel logs - Use dmesg to see BPF verifier messages if loading fails

Common Issues

Program Won’t Load

If your BPF program fails to load:

  • Check dmesg for verifier error messages

  • Ensure your LICENSE is GPL-compatible

  • Verify you’re using supported BPF features

  • Make sure return types match function signatures

No Output

If you don’t see output:

  • Verify the tracepoint/kprobe is being triggered

  • Check that you’re running with sudo

  • Ensure /sys/kernel/tracing/trace_pipe is accessible

Compilation Errors

If compilation fails:

  • Check that llc is installed and in your PATH

  • Verify your Python syntax is correct

  • Ensure all imported types are from ctypes

  • In the worst case, compile object files manually using compile_to_ir() and llc to get detailed errors

Verification Failure

If verification fails:

  • Compile the object files using compile() function instead of loading directly

  • Run sudo check.sh check <bpf>.o to get detailed verification output

Next Steps

Now that you understand the basics, explore: