luaebpf

luaebpfModule

Compiles a Lua program file into a BPF ELF object.

A program file’s body is compile-time Lua: lunatic compiles the file, and the body runs once, on the host, from that bytecode in the CLI’s Lua, and hands the functions it declares to a program constructor. Those functions are the program: compile reads their bytecode, lowers it, and returns an object bpftool prog load accepts. Anything the subset refuses is an error naming the Lua file and line. lunatik bpf calls compile and writes the object, which lunatik run --dev loads and attaches; the guide page Compiling Lua to eBPF says what a program file may hold, what a program returns and when it stops.

The compiler compiles for the kernel lunatik.config describes, which make writes from the tree Lunatik is built against: that kernel’s version and byte order. It reads that kernel’s types from the BTF file it is handed, or from /sys/kernel/btf/vmlinux, the running kernel’s, and the kernel scripts the body requires from the directory it is handed, or from /lib/modules/lua, so a build host compiles for the kernel an image ships when make was handed that kernel’s tree and the compiler its BTF and the image’s kernel scripts.

Experimental: the compiler, lunatik bpf, lunatik run --dev and the modules a program file’s body requires may change in a minor release.

Usage

local luaebpf = require("luaebpf")

local object = luaebpf.compile("filter.bpf.lua")
local image = luaebpf.compile("filter.bpf.lua", "build/vmlinux.btf", "staging/lib/modules/lua")

Functions

compile (path[, btffile[, scripts]]) Compiles the program file at path.
errors (root) Reads back the errors of a compiled program lunatik run attached, from the maps it pinned under the script’s root: how many times the program stopped at each place, a line a stop logs.

Functions in detail

compile (path[, btffile[, scripts]])
Compiles the program file at path. A module an earlier call’s body loaded is loaded again, so this call’s body reads the kernel scripts it names.

Parameters

  • path string the program file, usually named <something>.bpf.lua
  • btffile string the kernel’s BTF as a raw BTF file, the bytes /sys/kernel/btf/vmlinux serves, read once a layout is asked for; that file when absent (optional)
  • scripts string the directory the body’s require reads the kernel scripts from, laid out as /lib/modules/lua is; that directory when absent (optional)

Returns

  1. string the BPF ELF object
  2. table a line per call into the kernel Lua runtime the compiler met, in that order, <file>:<line>: calls the runtime '<name>'

Raises

<file>:<line>: <reason> for every construct the subset refuses, <path>: no program declared when the body hands nothing to a constructor, <btffile>: <reason>, <btffile> carries no BTF header and <btffile> is shorter than its BTF header says when a layout is asked of a file that cannot be read, holds no BTF or is cut short, and <btffile> is a <order>-endian BTF, for a <order>-endian object when the BTF a layout was read from is not in the object’s byte order
errors (root)
Reads back the errors of a compiled program lunatik run attached, from the maps it pinned under the script’s root: how many times the program stopped at each place, a line a stop logs.

Parameters

  • root string the script’s root, /sys/fs/bpf/lunatik/<script>

Returns

  1. table or nil a table per place, {file, line, reason, count}, in the order the compiler met the places, the count summed over the CPUs; an empty array where the root pins no luaebpf_errors, as a program that stops nowhere declares none
  2. string the message, where a pin cannot be read

Usage

local places = assert(luaebpf.errors("/sys/fs/bpf/lunatik/noudp"))
for _, place in ipairs(places) do
	print(place.count, place.file, place.line, place.reason) --> 3  noudp.bpf.lua  8  out of bounds
end