luaebpf

XDP and TC programs written in Lua

luaebpf compiles Lua to eBPF for Lunatik. A program file is a Lua file whose functions become XDP or TC programs, which the kernel runs natively on each packet a device receives or sends; they read the packet, keep state in maps the kernel’s Lua scripts share, and hand a packet to a kernel script when Lua is what it needs.

  • 6 Lua modules
local xdp    = require("bpf.xdp")
local action = require("linux.xdp").action

return xdp.program(function(ctx)
    local p = ctx:packet()
    if #p < 14 then
        return action.DROP
    end
    return action.PASS
end, {default = action.PASS})
sudo lunatik bpf -o /usr/local/lib/bpf/luaebpf/runt.bpf.o runt.bpf.lua
sudo lunatik run --dev=eth0 runt

Experimental. The compiler, the modules a program file’s body requires and the part of Lua it compiles may change in a minor release.

luaebpf builds and runs inside Lunatik, which mounts it at luaebpf/; lunatik bpf compiles a program file and lunatik run --dev attaches it. Compiling Lua to eBPF is the guide for the author of a program file, Lua to eBPF by example lists what each construct compiles to, and the design notes say how the compiler is built. AGENTS.md holds the conventions for contributors.

luaebpf is dual-licensed under MIT or GPL-2.0-only.

API reference

Compiler

luaebpf Compiles a Lua program file into a BPF ELF object.

Program file

bpf.map Declares a map in a program file.
bpf.tc Declares a TC program in a program file.
bpf.vmlinux The kernel’s own type information, read from a raw BTF file: /sys/kernel/btf/vmlinux, the running kernel’s, unless luaebpf.compile is handed the BTF of the kernel it compiles for.
bpf.xdp Declares an XDP program in a program file.
lunatik Names a kernel Lua runtime in a program file.