https://github.com/packetstream-llc/ouroboros
ouroboros is a tool to manage and chain multiple eBPF programs together, simplifying complex program flows with `bpf_tail_call`
https://github.com/packetstream-llc/ouroboros
ebpf ebpf-tail xdp
Last synced: 7 months ago
JSON representation
ouroboros is a tool to manage and chain multiple eBPF programs together, simplifying complex program flows with `bpf_tail_call`
- Host: GitHub
- URL: https://github.com/packetstream-llc/ouroboros
- Owner: PacketStream-LLC
- License: mit
- Created: 2025-09-19T10:55:30.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-12T06:09:01.000Z (7 months ago)
- Last Synced: 2025-11-12T08:12:19.855Z (7 months ago)
- Topics: ebpf, ebpf-tail, xdp
- Language: Go
- Homepage:
- Size: 196 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
> [!WARNING]
> This is not an official PacketStream LLC service or product.
`ouroboros` helps you manage and chain multiple eBPF programs together via managing central `PROGRAM_MAPS` and shared `PINNED` eBPF maps/ringbufs,
making it easier to `bpf_tail_call` and build complex chain of eBPF program flow structure for complext programs
## What is it?
Running a single eBPF program is straightforward. But what if you need to run many of them in a specific order? `ouroboros` simplifies this by letting you:
- **Organize** your eBPF programs into a single project with metadata provided with `ouroboros.json`.
- **Share** and **Allocate** eBPF maps and ring buffers on initialization via `ouroboros.json` configuration.
- **Create** program maps for centralized tail call management and easy chaining in your C code.
- **Machine Generated** constants for program IDs and jump targets, so you don't have to manually manage them.
- **Chain** them together using eBPF tail calls with generated `JUMP_TO_PROGRAM` and `PROG_*` constants, easily implement tailing to next program.
- **Build and load** everything with simple commands, without finding pinned path when you use `bpftool` directly.
## Installation
Make sure you have Go, Clang, and LLVM installed.
```bash
go install github.com/PacketStream-LLC/ouroboros@latest
```
## Getting Started
1. **Create a project:**
```bash
mkdir my_firewall
cd my_firewall
ouroboros create
```
This will create `ouroboros.json`, `src/` and `target/` directories.
2. **Add your first program:**
```bash
ouroboros add block_list
```
Now, edit the C code in `src/block_list/main.c`.
3. **Build and load it:**
```bash
ouroboros load
```
This will compile your programs and load them into the kernel.
4. **Attach to an interface:**
```bash
ouroboros attach eth0
```
5. **See the logs:**
```bash
ouroboros log
```
## Usage
See [USAGE.md](USAGE.md) for detailed usage instructions.