Compiling Lua to eBPF
Experimental. The compiler and what a program file reaches through it, lunatik bpf,
lunatik run --dev, the modules a program file’s body requires and the part of Lua it compiles,
may change in a minor release.
A program file is a Lua file whose functions become eBPF programs, which the kernel runs natively
on each packet a device receives or sends. lunatik bpf compiles it on the host,
lunatik run --dev attaches it, and a map it declares is shared with the kernel scripts. This page
is for the author of a program file, who knows Lua: what a program computes, when it stops and when
it is refused. Lua to eBPF by example lists what each construct
compiles to, and how the compiler is built is in its design notes.
A first program
This program counts the IPv4 packets that reach a device, by protocol, in a map a kernel script reads.
protocols.bpf.lua:
local map = require("bpf.map") local xdp = require("bpf.xdp") local struct = require("struct") local vmlinux = require("bpf.vmlinux") local action = require("linux.xdp").action local eth = require("linux.eth") local ethhdr = struct(vmlinux.layout("ethhdr")) local iphdr = struct(vmlinux.layout("iphdr")) local counts = map.array("counts", {key = "I4", value = "I8", entries = 256}) return xdp.program(function(ctx) local p = ctx:packet() local frame = ethhdr:view(p, 0) if frame.h_proto == eth.proto.IP then local ip = iphdr:view(p, eth.HLEN) local protocol = ip.protocol local n = counts[protocol] if n then counts[protocol] = n + 1 end end return action.PASS end, {default = action.PASS})
The file has two parts. Its body, every line outside the function, runs once, on the host, when
the file is compiled: it reads the kernel’s Ethernet and IPv4 headers from its BTF, declares the map
counts and the program, with the verdict a return with no value gives. The function is the
program: it is compiled to eBPF and runs in the kernel on each packet, and reads the headers' fields
by name, each where the kernel’s struct puts it (The packet). It returns XDP_PASS,
so every packet it can read goes on to the network stack.
Compile it into place and attach it to a device:
sudo lunatik bpf -o /usr/local/lib/bpf/luaebpf/protocols.bpf.o protocols.bpf.lua sudo lunatik run --dev=eth0 protocols
lunatik run creates the map and pins it at /sys/fs/bpf/lunatik/protocols/counts, where a
kernel script opens it with the kernel’s bpf.map. lunatik -e runs one such chunk, which prints
the TCP and the UDP packets counted so far:
sudo lunatik -e 'local map = require("bpf.map") local ipproto = require("linux.socket").ipproto local counts <close> = map.array("/sys/fs/bpf/lunatik/protocols/counts", "I4", "I8") return counts[ipproto.TCP], counts[ipproto.UDP]'
A frame that says IPv4 but is too short to hold the IPv4 header’s protocol stops the program at the
read of ip.protocol, which returns XDP_ABORTED, so the frame is dropped and nothing is counted,
logs protocols.bpf.lua:18: out of bounds to the kernel’s trace ring, which
sudo bpftool prog tracelog prints, and counts the stop at that line, which
sudo lunatik bpf --errors protocols reports
(When a program cannot be compiled or computed).
The lookup and the update are two steps, so two CPUs that count the same protocol at once can lose
one of the increments.
sudo lunatik stop protocols
What a program returns
a packet on eth0
|
v
+------------------------------------+ +----------------------------+
| the program, eBPF, in the kernel | | a kernel script, Lua |
| p = ctx:packet() the bytes | | |
| n = counts[k] a lookup | map | counts[k] reads what |
| counts[k] = n + 1 an update ----+-----+-> the program wrote |
| return action.PASS | | |
+-----------------+------------------+ +----------------------------+
|
| the verdict, an action of its program type
v
XDP PASS DROP TX REDIRECT ABORTED act as named
TC OK SHOT REDIRECT act as named; the rest of linux.tc.action
decides nothing, and the packet goes on
where the program computes a value that is no action, and where
Lua would raise, at a read past the packet or x // 0, the
program stops: XDP_ABORTED in XDP, TC_ACT_SHOT in TC, either one
dropping the packet; where it returns no value, its default verdict
A program returns its verdict, which tells the kernel what to do with the packet: a value of
linux.xdp.action in an XDP program, of linux.tc.action in a TC one, the values a kernel script’s
callback returns on the same hook.
- In an XDP program,
PASS,DROP,TX,REDIRECTandABORTEDact as the kernel defines them. - In a TC program,
OKlets the packet go on,SHOTdrops it andREDIRECTredirects it. The rest oflinux.tc.actiondecides nothing:UNSPEChands the packet to the next TC program on the device, and every other action skips those programs; either way the packet then goes on, through the device’s tc filters if it has any. - A value the program computes that is none of these,
return vwherevis a byte past 4 in an XDP program, stops the program, as the kernel’s Lua answers a callback returning it with the hook’s fallback, the answer it gives a callback that raised. One the compiler knows is refused, “the verdict 11 is not an XDP action”, and so is a boolean, which no action is:return ip.protocol == ipproto.TCPgives “the verdict may be a boolean here; return an action”.
A return with no value, or with nil, returns the default verdict. A verdict that may be nil is
refused: “the verdict may be nil here; test it first”. The constructor names the default verdict,
an action, and a constructor that names none is refused at the line of the program’s function:
return xdp.program(filter, {default = action.DROP})
A program that stops, where Lua would raise, where the verdict it computed is no action or where a
for outruns the budget the kernel gives it, does not return its default. An XDP program returns
XDP_ABORTED, the kernel’s verdict for a program error, which drops the packet and, in the generic
path and in most drivers, fires the tracepoint xdp:xdp_exception; a TC program, whose type has no
such verdict, returns TC_ACT_SHOT, which
drops the packet. A packet the program cannot read is dropped, whatever its default: a program that
must let it through tests #p before it reads. A default that is not an action is refused:
“xdp.program’s default verdict is not an XDP action”. A value the program computes reaches a kernel
script through a map, or as the argument of a call into a runtime,
not through the verdict.
When a program cannot be compiled or computed
filter.bpf.lua filter.bpf.o a packet
| | |
| lunatik bpf | lunatik run --dev | on the device
v v v
REFUSED REFUSED AT LOAD STOPS
lunatik: file:line: the verifier log, XDP_ABORTED or
reason; exit 1, no which quotes the Lua TC_ACT_SHOT: the packet
object written line; exit 1, nothing is dropped,
attached file:line: reason goes
to the trace ring, and
the stop is counted at
that line
what the subset does a program past the where Lua would raise:
not compile, and a limits of the verifier, x // 0, a read past
value the compiler most often a loop of the packet, an update
sees is wrong many passes the map refuses; and
a loop past the budget
the kernel gives it
Where Lua would raise an error, and where the part of Lua the compiler takes ends, a program file fails in one of three places.
- Refused.
lunatik bpfprintslunatik: <file>:<line>: <reason>, exits 1 and writes no object. What the subset does not compile is refused, and so is an operation the compiler can see is wrong because it knows the value: aforstep of 0, a map key or value its spec cannot pack, askb:priorityoutside 0 to 4294967295, a verdict that is no action of its program type. - Refused at load. The kernel’s verifier checks the object again when
lunatik runloads it. A program past the verifier’s limits, most often a loop of many passes, is refused there:lunatik runprints the verifier’s log, which quotes the Lua lines, exits 1 and leaves nothing attached. A call into a runtime whose module carries no BTF is refused there too, by libbpf, whose warning names the kfunc (Calls into a kernel Lua runtime), and so are a program that may stop and one that calls into a runtime under a license the kernel does not count as GPL-compatible (The license). - Stops. In the kernel, on a packet, the program returns at once
XDP_ABORTEDin XDP orTC_ACT_SHOTin TC, which drop the packet, logs the error the kernel’s Lua raises there and counts the stop at its line; a tracer reads an XDP program’s stops at the tracepointxdp:xdp_exceptiontoo. A program stops at a read past the packet, a division or a modulo by 0, aforstep of 0 it computed, aforwhose passes outrun the budget the kernel gives it, a map key or value its spec cannot pack, a map update or delete the map refuses, askb:priorityit computed outside 0 to 4294967295, a verdict it computed that is no action of its program type, and in a function it called that stops. A division by a 0 the compiler knows is not refused: the program stops on every packet that reaches it.
A stop logs <file>:<line>: <reason>, the file and the line of the check that stopped it, as a
refusal names them, and the reason the kernel’s Lua raises there: “attempt to divide by zero”,
“attempt to perform ‘n%0’”, “‘for’ step is zero”, “out of bounds” for a read past the packet and
for a skb:priority outside 0 to 4294967295, as the kernel’s data and skb objects raise it,
string.pack’s “unsigned overflow” or “integer overflow” for a map key or value its spec cannot
pack, and “invalid action” for a verdict that is no action, as the kernel logs a callback’s. A map
update or delete the map refuses names the map and the write, “the map ‘flows’ refused the
update”, since only the kernel knows its errno, and a for past the kernel’s budget, which Lua
would run to its end, logs “‘for’ outruns the budget the kernel gives it”. A stop in a function the
program calls is logged at the callee’s line, and its callers log nothing.
$ sudo bpftool prog tracelog
<idle>-0 [002] ..s21 4021.374508: bpf_trace_printk: protocols.bpf.lua:18: out of bounds
The line goes to the kernel’s trace ring through bpf_trace_printk, not to the kernel log a kernel
script’s callback writes its error to: bpftool prog tracelog prints the ring as it fills, as
/sys/kernel/tracing/trace_pipe does, and the file is named as lunatik bpf was given it. The
helper limits nothing, so the program does, as the kernel’s own log does: ten lines every five
seconds at most, DEFAULT_RATELIMIT_BURST lines every DEFAULT_RATELIMIT_INTERVAL jiffies, counted
for all the programs of an object together, so a program that stops on every packet logs the first
ten of each five seconds. The CPUs share the count without a lock, and stops that race on several
of them may each pass it.
A stop is also counted as an error of the program, at its place, the line it logs,
<file>:<line>: <reason>: two checks of one line that stop for one reason are one place, and a
function two programs of the file call is one place for both. lunatik bpf --errors <script>, the
script as lunatik run takes it, prints a line for each place its program stopped at, the count, a
space and the line, as uniq -c counts the lines of the trace ring, in the order the compiler met
the places, and nothing for a program that has not stopped:
$ sudo lunatik bpf --errors protocols
3 protocols.bpf.lua:18: out of bounds
The count takes every stop, those the rate limit keeps out of the trace ring among them, on every
CPU, and lasts while the script runs: each run starts it at zero, and lunatik stop takes it down
with the program. The trace ring says when a stop happened and on which CPU, and laps; the count
says how many there were. The object keeps the counts in a map of its own, luaebpf_errors, an
entry per place and CPU, which lunatik run pins beside the maps the file declares, at
/sys/fs/bpf/lunatik/<script>/luaebpf_errors, and the lines of the places beside it, at
luaebpf_errors-lines, so a map of the file cannot take that name: “‘luaebpf_errors’ is the map a
program’s errors are counted in”. A
program that may stop nowhere declares neither. A stop costs a lookup of its place’s entry and an
add before its line is logged; where the program does not stop, nothing changes.
The Lua a program may use
A compiled function computes what the kernel’s Lua computes, or stops, or is refused. “Stops”
means the program returns XDP_ABORTED or TC_ACT_SHOT, which drop the packet; “refused” means
lunatik bpf refuses the file at that line. Each construct links to its listing.
| You write | The program gives | It stops when | It is refused when |
|---|---|---|---|
a // b, a / b |
the quotient, rounded towards minus infinity: -7 // 2 is -4 |
b is 0 |
an operand is not a number |
a % b |
the remainder, with the sign of b: -7 % 2 is 1 |
b is 0 |
an operand is not a number |
a + b, a - b, a * b, -a |
the result, wrapped around 64 bits: math.maxinteger + 1 is math.mininteger |
never | an operand is not a number |
a & b, a | b, a ~ b, ~a |
the bits, over 64 bits | never | an operand is not a number |
a << n, a >> n |
a logical shift; n of 64 or more gives 0, a negative n shifts the other way: 3 << -1 is 1 |
never | an operand is not a number |
a < b, a <= b, a > b, a >= b |
a signed comparison: -1 < 1 is true |
never | an operand is not a number |
a == b, a ~= b |
false between values of two types |
never | an operand may hold two types, a number on one path and nil on another |
if v then, and, or, not |
0 is true; only nil and false are false |
never | v may be a number on one path and nil or a boolean on another |
t.x, t[1], t a table of the body |
the value the body left there | never | the index is computed; #t; a write to t |
for i = a, b, s do |
the passes Lua makes | s is 0; a bound or a step is computed, and the passes outrun the kernel’s budget (Loops) |
s is a known 0 |
goto continue |
a jump to the label | never | the label is above the goto |
local v = f(x) |
the value f returns |
f stops |
Calls says |
return f(x) |
always: a tail call | ||
local v = limits:run(a, b), limits a runtime the body named |
the verdict the runtime’s callback returns, or nil | never | an argument is not a number; the call is in a function the program calls; limits(a); another method |
if v then, v == nil, v what limits:run answered |
the branch Lua takes: v is the verdict on one, nil on the other |
never | v is used before one of these tests reads it; v is the answer on one path and another value on another |
p:getuint16(n) and the other reads |
the bytes at n, in the kernel’s byte order |
the read passes the end of the packet | The packet says |
#p |
the length of the packet | never | never |
codec:view(p, at) |
the struct the codec lays out, as it lies in p from at |
never | p is not the packet; at is not a number; another method of the codec |
h.field, h a view |
the field at at plus its offset, most significant byte first where the layout marks it bigendian, or the bitfield taken out of its load |
the read passes the end of the packet | the field does not exist; a write; h is passed to a function or returned |
skb:data() |
the whole packet, linear or not | never | a layer is given |
skb:priority(v) |
v, stored as the packet’s priority |
v is outside 0 to 4294967295 |
a known v is outside it |
m[k] |
the value, or nil | k does not fit the key’s spec |
a known k does not fit it; the value is used before if v then tests it |
m[k] = v, m[k] = nil |
the entry inserted or replaced, or deleted | the map refuses; k or v does not fit its spec |
a known k or v does not fit it |
v.field, v a struct value |
the field, or the bitfield taken out of its load | never | the field does not exist; a write |
return v, the verdict |
v, an action of the program’s type |
v is no action of it |
v may be nil or a boolean; a known v is no action |
Besides what the table refuses, these are refused: a table constructor, .., a closure, an
assignment to an upvalue or a global, a write to a table that is not a map, a generic for,
while, repeat, a vararg function and a to-be-closed variable.
Messages lists what each refusal says.
The packet
A program’s argument is its context, which offers the methods of the kernel’s own object for the hook, and opens the packet:
| Program | The context offers |
|---|---|
| XDP | ctx:packet(), the packet; ctx:ingress(), the index of the device it arrived on; ctx:queue(), the receive queue it arrived in |
| TC | skb:data(), the packet; #skb, its length; skb:ifindex(), the index of its device; skb:hash(), its flow hash; skb:priority(), its priority, which skb:priority(v) sets and returns |
Any other method is refused: skb:mark() gives “the context has no method ‘mark’”. The packet
is a read-only view of its bytes, with the reads of the kernel’s data object. An offset counts
from 0, the first byte of the Ethernet header. On TC the packet is the whole skb, the bytes past
its linear head included, as the kernel’s skb:data() reads it in a tc callback: a segment the
host sends carries its payload there, and #p is #skb.
| Method | Reads |
|---|---|
p:getbyte(n), p:getuint8(n) |
1 byte, unsigned |
p:getint8(n) |
1 byte, signed |
p:getuint16(n), p:getint16(n) |
2 bytes, unsigned or signed |
p:getuint32(n), p:getint32(n) |
4 bytes, unsigned or signed |
p:getint64(n) |
8 bytes, signed |
#p |
the length of the packet |
A read wider than a byte is in the byte order of the kernel, as the kernel’s data object reads
it: little-endian on x86 and arm64, where p:getuint16(16) of an IPv4 header whose total length
is 28 gives 7168. A header’s field is read by name, in the order the kernel keeps it, through a
view of the kernel’s own struct:
local struct = require("struct") local vmlinux = require("bpf.vmlinux") local eth = require("linux.eth") local iphdr = struct(vmlinux.layout("iphdr")) -- in the body local ip = iphdr:view(p, eth.HLEN) -- in the function local length = ip.tot_len --> 28
The body builds a struct codec of the struct bpf.vmlinux.layout reads from the kernel’s
BTF, and codec:view(p, at) is that struct as it lies in the packet from at. Each field read
is one read of the packet at at plus the field’s offset, of its width and sign: a field the
layout marks bigendian, as it marks a __be16, reads most significant byte first, so
ip.tot_len is 28 on every kernel, and a bitfield, ip.ihl, is taken out of the load that covers
it. The offset may be one the program computes: the TCP header past the options of an IPv4 one
is tcphdr:view(p, eth.HLEN + ip.ihl * 4). A field read past the end of the packet stops the
program at that field, and on a kernel without efficient unaligned access an XDP field wider than a
byte, or a bitfield whose load is, is refused as a read is. A view is read in the function that
made it: one passed to a function is refused, “argument #1 is a view, and a compiled call passes
numbers and packets”, and so is a field the layout lacks, “a view has no field ‘flags’”.
A read that passes the end of the packet stops the program, and so does an XDP read that starts
past byte 65535 less its width. There is no getuint64, since a Lua integer is signed, and no
write: “the packet has no method ‘setbyte’”. The bounds of the packet are not numbers:
ctx.data_end - ctx.data is refused, “‘data_end’ is a packet bound, not a number; ‘#’ on the
packet is its length”. On a kernel without efficient unaligned access, an XDP read wider than a
byte is refused (#2047): “‘getuint16’ reads more than a byte, and this kernel lacks efficient
unaligned access”; a TC read is not, since it copies its bytes before it reads them.
skb:data(layer) is refused: “‘data’ with a layer is not compiled yet”.
Maps
The body declares a map with bpf.map: map.hash(name, spec), map.array(name, spec) or
map.lru_hash(name, spec). The spec is {key = ..., value = ..., entries = ...}: the key is a
string.pack format of one integer, four bytes wide in an array, the value one of those or a
struct codec, both in the kernel’s byte order but for a field the codec’s layout marks
bigendian, and entries the map’s capacity. lunatik run
creates the map and pins it at /sys/fs/bpf/lunatik/<script>/<name>, where a kernel script opens
it with the constructor of the same name of the kernel’s bpf.map, which takes the path and the
two specs: map.hash(path, "I4", "I8"). A map takes any name but luaebpf_errors, which the
compiler gives the map it counts the errors in
(When a program cannot be compiled or computed).
In a compiled function a map reads as a table.
m[k]is the value, or nil. The value is used only afterif v then, orif not v then, tests it; any other use is refused: “‘flows’ may be nil here; test it first”. A lookup in an array within its entries always finds a value, 0 where nothing was written.m[k] = vinserts or replaces the entry, andm[k] = nildeletes it; deleting a key the map does not hold is not an error.- A key or a value its spec cannot pack stops the program, and so does an update or a delete the map refuses: an update of a full hash map, an index past an array’s entries, a delete from an array. One the compiler knows is refused: “the map key -1 does not fit ‘I4’”.
- A
structvalue is read-only and read by field name,v.ttl, as its codec decodes it: a field the layout marksbigendian, as bpf.vmlinux.layout marks a__be16, reads most significant byte first, sov.tot_lenof an IPv4 header whose total length is 28 is 28, and a bitfield the layout lists,v.ihl, is taken out of the load that covers it, as the codec’s view takes it. A field wider than a byte, or a bitfield whose load is, is refused on a kernel without efficient unaligned access, as a packet read is.
Calls
A compiled function calls a Lua function the program file declares, or one a kernel script it requires declares, installed as source. The callee is compiled once for each program that calls it.
- It takes at most four arguments, each a number or the packet, and returns one value; Lua’s nil fills every other result the caller asks for.
- Its first call fixes the types of its arguments: a later call with other types is refused, “‘f’ is called with a packet and compiled with a number”.
- A callee that stops stops the program.
- A function written in C is refused, print, pcall, ipairs and math.floor among them:
“‘print’ is not a Lua function this program file declares”. So is recursion, “recursion through
‘walk’”, and a call whose arguments include a call,
f(g(x)), which is writtenlocal y = g(x)and thenf(y). return f(x)is a tail call, which is refused: writelocal v = f(x), thenreturn v.
Calls into a kernel Lua runtime
A program hands a packet to Lua by calling a kernel Lua runtime, a kernel script run in softirq
context whose callback decides the packet. The body names the runtime with
lunatik.runtime(script), of lunatik, the compile-time twin of the kernel’s: script is the
script the runtime runs, its path below /lib/modules/lua/ without .lua, as lunatik run takes
it, and nothing else ties the program to the runtime. The program calls the runtime’s run method,
whichever its type. This program file hands Lua the UDP frames, and the kernel script drops one to
port 53 longer than 512 bytes:
ports.bpf.lua:
local xdp = require("bpf.xdp") local lunatik = require("lunatik") local struct = require("struct") local vmlinux = require("bpf.vmlinux") local action = require("linux.xdp").action local eth = require("linux.eth") local ipproto = require("linux.socket").ipproto local WORD <const> = 4 -- bytes in a unit of ihl local ethhdr = struct(vmlinux.layout("ethhdr")) local iphdr = struct(vmlinux.layout("iphdr")) local udphdr = struct(vmlinux.layout("udphdr")) local limits = lunatik.runtime("limits") return xdp.program(function(ctx) local p = ctx:packet() local ip = iphdr:view(p, eth.HLEN) if ethhdr:view(p, 0).h_proto ~= eth.proto.IP or ip.protocol ~= ipproto.UDP then return action.PASS end local port = udphdr:view(p, eth.HLEN + ip.ihl * WORD).dest local verdict = limits:run(port, #p) if verdict then return verdict end return action.PASS end, {default = action.PASS})
limits.lua, the kernel script:
local xdp = require("xdp") local action = require("linux.xdp").action local WORD <const> = 8 local longest = {[53] = 512} -- the longest frame a port takes local function callback(ctx) local argument = ctx:argument() local port, length = argument:getint64(0), argument:getint64(WORD) local limit = longest[port] if limit and length > limit then return action.DROP end end xdp.attach(callback)
sudo install -m 0644 limits.lua /lib/modules/lua/limits.lua sudo lunatik bpf -o /usr/local/lib/bpf/luaebpf/ports.bpf.o ports.bpf.lua sudo lunatik run --context=softirq limits sudo lunatik run --dev=eth0 ports
The first lunatik run starts the runtime and the second attaches the program, which calls
limits whatever its own name. The callback returns nothing for any other frame, so the call
answers nil there, and the program passes the frame.
limits:run(a, b), in the program’s own function, runs the callback with the context of the packet the program runs on,ctx:packet()in an XDP callback andctx:skb()in a TC one, and with the arguments, each a number, as 64-bit integers in order:ctx:argument()holds 8 bytes for each, whichctx:argument():getint64(0),getint64(8)and on read, and is empty forlimits:run(). A call from an XDP program reaches the callbackxdp.attachregistered, and one from a TC program the callback oftc.attach.- The call answers the callback’s verdict, a value of
linux.xdp.actionorlinux.tc.action, or nil where none comes back: no runtime of that name runs in softirq with a callback attached, or the callback raises, returns nil or nothing, or returns what is not one of the hook’s actions,UNSPECincluded in a TC one. A runtime of process context is never called, and the module logs “‘limits’ is a process-context runtime, not dispatched”; a value that is not an action is logged as “invalid action”. The call never stops the program. - The answer is used only after
if v then,if not v then,v == nilorv ~= niltests it, which gives the verdict on one branch and nil on the other, a nil the program may return as its default verdict.v = v or action.PASSis such a test, since Lua compiles it as one. Any other use is refused, “‘limits’ may be nil here; test it first”, and an ordered comparison “attempt to compare a runtime answer with a number”. - A call in a function the program calls is refused, “‘limits’ can only be called from the program’s own function”, since only the program’s own function holds the context, and so is one in a program whose parameter does not hold it, “a call into the runtime passes the context, which the program’s parameter does not hold”. An argument that is not a number is refused, “argument #1 is a boolean, and a call into the runtime passes numbers”, and so is a lunatik.runtime with no script, at its line, “lunatik.runtime takes a script”. A call of the runtime itself is refused, “a runtime is called through its method; write ‘limits:run(…)’”, and so is any other method, “a runtime has no method ‘call’; write ‘limits:run(…)’”.
- The name and the arguments are written on the program’s stack while the call runs, 512 bytes it shares with the function’s own values; a call they do not fit is refused, “the function needs 528 bytes of stack, over the 512 eBPF allows”, one with a name of 480 bytes among them.
- Each call runs the kernel’s Lua interpreter on the packet path, the cost of a Lua call on every
packet that reaches it: a program decides what it can by itself, a map in front, and calls Lua
for the rest.
lunatik bpfprints on stdout a line for each call it compiled,<file>:<line>: calls the runtime '<name>', in the order it met them, and nothing for a file with none; for the file above,ports.bpf.lua:19: calls the runtime 'limits'. - The object loads where the module of its call,
luaxdporluatc, carries BTF, which a module built aftersudo make btf_installdoes. Where it carries none,lunatik runprints libbpf’s “extern (func ksym) ‘bpf_luaxdp_run’: not found in kernel or module BTFs”, exits 1 and leaves nothing attached.
Loops
A numeric for is the only loop compiled. It makes the passes Lua makes.
- With bounds and a step the compiler knows,
for i = 14, 17 do, it compiles for every kernel. The verifier walks it pass by pass whenlunatik runloads it, so a loop of many passes is refused there:for i = 1, 100000 dogives “BPF program is too large”, and one that reads the packet on each pass “The sequence of 8193 jumps is too complex”, at fewer passes. - With a bound or a step the program computes,
for i = 1, n do, it compiles for every kernel. The kernel’s iterator counts its passes, 8,388,609 at most, and a loop that would make more stops the program before its first pass. The iterator is a kfunc, which the kernel lets a program call only under its JIT: withnet.core.bpf_jit_enableat 0 the load is refused, “JIT is required for calling kernel function”, and on an architecture whose JIT calls none, “JIT does not support calling kernel function”. From Linux 6.9 each pass also goes through the kernel’smay_goto, which gives the loops of one call of a function a budget they share, each call starting it in full: about a quarter of a second where the kernel’s JIT times the loops, x86 from 6.15 and arm64 from 6.18 among them, and 8,388,608 passes after the first elsewhere, which one loop alone never spends. The program stops once it runs out, where Lua would make every pass. From 6.17 a kernel that times them writes “ERROR: Timeout detected for may_goto instruction” to the program’s stderr stream when it stops one. Before 6.9 nothing bounds the time, so loops nested in one another make every pass they count. - The verifier walks such a loop until a pass ends as an earlier one did, and a value the body
carries from pass to pass, read by a later test the verifier decides, never ends one so. A count
of the bytes that match,
n = n + 1in the body andif n > 3 thenafter the loop, is such a value, since the verifier knowsnon every pass, and so is a sum of the packet’s bytes returned ass & 3, whose verdict test it decides from the two bits: each is refused at load, “The sequence of 8193 jumps is too complex” or “BPF program is too large”. The same sum tested withif s > 100 thenloads, and so does a flag the body sets,found = true, tested after the loop. - A step of 0 is refused when the compiler knows it, “‘for’ step is zero”, and stops the program when the program computes it.
while, repeat, a goto backwards and a generic for are refused.
The license
The object declares one license for its programs, which the kernel reads when lunatik run loads
them. A program file names it in the options its constructors take, license, a string, and a
file that names none declares Dual MIT/GPL:
return xdp.program(filter, {default = action.DROP, license = "GPL"})
- Every program of a file carries the license the object declares, since libbpf loads each under
the object’s one
licensesection. A constructor whose license is not the one of the programs before it is refused at the line of its function, a program that names none counting asDual MIT/GPL: “tc.program’s license ‘GPL’ is not ‘Dual MIT/GPL’, the license of the programs before it”. So is a license that is not a string, “xdp.program’s license is not a string”. Any string compiles, and libbpf keeps its first 63 bytes. - The kernel reads the string for one thing, whether the program is GPL-compatible, which it is
under
GPL,GPL v2,GPL and additional rights,Dual BSD/GPL,Dual MIT/GPLandDual MPL/GPL(license_is_gpl_compatible,include/linux/license.h) and under no other string. It keeps that alone:bpftool prog showprintsgplfor a GPL-compatible program, and the string is read from the object,readelf -p license protocols.bpf.o. - A program that calls a kernel function loads only under a GPL-compatible license, and a call
into a runtime is such a call. Under any other,
lunatik runprints the verifier’s “cannot call kernel function from non-GPL compatible program”, exits 1 and leaves nothing attached. - A program that may stop logs through
bpf_trace_printk, which the kernel gives only a GPL-compatible program, and only to a loader that holdsCAP_PERFMON, as root does. Under any other licenselunatik runprints “cannot call GPL-restricted function from non-GPL compatible program”, exits 1 and leaves nothing attached; a read of the packet, a division, a map write and a verdict the program computes each may stop it. A program that stops nowhere, which reads its context, looks up its maps and returns verdicts the compiler knows, loads under any license.
Where a compiled function and Lua differ
Lua decides some things only when the line runs, from the type a value has then. A compiled
function cannot, and is refused where its answer could differ from Lua’s. A variable that holds a
number on one path and nil or a boolean on another is refused where == compares it or if tests
it, since the kernel holds nil, false and 0 as the same word:
local v if p:getbyte(14) > 0 then v = 7 end if v == 7 then return action.DROP end -- "a number that may be nil cannot be compared with a number here"
Give the variable one type on every path: local v = 0. These are refused too:
- The value of a map lookup used before
if v then: “‘flows’ may be nil here; test it first”. The kernel lets the program read the value only past that test. - A variable that holds a lookup in one map on one path and in another map on the other: “a map value here comes from more than one map”. Which map it came from decides how its value is read.
- A variable that holds the answer of a call into a runtime on one path and another value on the other, tested where the two paths meet: “a runtime answer joined another value here, whose nil is 0 and not -1; test it before the paths join”. The kernel holds the answer’s nil as -1 and every other nil as 0, and the word does not say which path it came from. Tested on the path of the call, the answer is a verdict or the nil every other path holds, and the paths join as any two do.
- A variable that holds a view of one struct on one path and of another struct on the other: “a view here is of more than one struct”. Which struct it views decides where a field is read.
- A view read in a function that has assigned the parameter its context or its packet came in: “a view is read through the context or a packet, which no parameter of the function holds here”. A view keeps the offset it starts at and no packet, and its fields are read through that parameter.
- A verdict that may be nil: “the verdict may be nil here; test it first”. The kernel would read nil as 0, which is an action.
- A verdict that may be a boolean: “the verdict may be a boolean here; return an action”. The
kernel’s Lua answers a boolean with the hook’s fallback, and the kernel holds
trueandfalseas the words of 1 and 0, which are actions, so a test of the word cannot tell them apart. - Arithmetic on nil or a boolean, and an ordered comparison of a value that is not a number: “attempt to perform arithmetic on a nil value”, “attempt to compare a context with a number”.
Messages
Each refusal reads lunatik: <file>:<line>: <message>.
| Message | You wrote | Write instead |
|---|---|---|
| a tail call cannot be compiled | return f(x), return p:getuint16(12) |
local v = f(x), then return v |
| a call with a variable number of values cannot be compiled | f(g(x)), f(p:getbyte(1)) |
local b = g(x), then f(b) |
| ‘ports’ is indexed by a value the compiler cannot resolve | ports[i], i read from the packet or a loop |
a map, or one comparison per value |
| ‘#’ cannot be applied in a compiled function | #ports, a table of the body |
local N <const> = #ports in the body |
| a table constructor cannot run in the kernel; build it in the file body | {} in the function |
the table in the body |
| ‘..’ cannot be applied in a compiled function | a .. b |
the string in the body |
| ‘print’ is not a Lua function this program file declares | print, pcall, math.floor, ipairs in a generic for |
a Lua function of the file |
| global ‘limit’ is not a compile-time value | a global the body never set | set it in the body |
| a global cannot be assigned in a compiled function | counter = 1 |
a map |
| a table cannot be written in a compiled function | t.x = 1, t[1] = 1, t a table of the body |
a map |
| an upvalue cannot be assigned in a compiled function | n = n + 1, n a local of the body |
a map |
| a closure cannot be created in a compiled function | function () ... end in the function |
a function of the body |
| a compiled function takes at most 4 arguments, not 5 | five arguments | four (#2094) |
| a compiled function returns at most one value | return a, b in a callee |
one value |
| recursion through ‘walk’ | a function that calls itself | a for |
| the packet has no method ‘getuint64’ | getuint64, setbyte |
the reads of The packet |
| the context has no method ‘mark’ | skb:mark(), ctx:argument() |
the methods of The packet |
| ‘data_end’ is a packet bound, not a number; ‘#’ on the packet is its length | ctx.data_end - ctx.data |
#p |
| ‘flows’ may be nil here; test it first | a lookup, or the answer of a call into a runtime, used untested | if v then |
| attempt to compare a runtime answer with a number | limits:run(1) < 5 |
if v then, then v < 5 |
| a runtime answer joined another value here, whose nil is 0 and not -1; test it before the paths join | if v then, v the answer on one path and nil on another |
if v then on the path of the call |
| ‘limits’ can only be called from the program’s own function | a call into a runtime in a function the program calls | the call in the program’s function |
| a call into the runtime passes the context, which the program’s parameter does not hold | xdp.program(function() ... end, opts) calling limits:run(1) |
function(ctx) |
| argument #1 is a boolean, and a call into the runtime passes numbers | limits:run(true), limits:run(p) |
a number |
| lunatik.runtime takes a script | lunatik.runtime() |
lunatik.runtime("limits") |
| a runtime is called through its method; write ‘limits:run(…)’ | limits(1) |
limits:run(1) |
| a runtime has no method ‘call’; write ‘limits:run(…)’ | limits:call(1) |
limits:run(1) |
| the function needs 528 bytes of stack, over the 512 eBPF allows | a call into a runtime named by 480 bytes | a shorter name |
| a number that may be nil cannot be compared with a number here | == on a variable nil on one path |
local v = 0 |
| a number that may be nil has no truth value in a compiled function | if v then, v nil on one path |
local v = 0, then if v ~= 0 then |
| the verdict may be nil here; test it first | return v, v nil on one path |
a verdict on every path |
| the verdict may be a boolean here; return an action | return ip.protocol == ipproto.TCP |
if ip.protocol == ipproto.TCP then return action.DROP end |
| the verdict 11 is not an XDP action | return 11, a value no action of the program’s type |
an action of linux.xdp.action or linux.tc.action |
| xdp.program’s default verdict is not an XDP action | {default = 5} |
{default = action.DROP} |
| ‘luaebpf_errors’ is the map a program’s errors are counted in | map.hash("luaebpf_errors", spec) |
another name |
| xdp.program’s default verdict is not an integer | xdp.program(fn), {default = "drop"} |
xdp.program(fn, {default = action.PASS}), and tc.program alike |
| xdp.program’s license is not a string | {license = 2} |
{license = "GPL"} |
| tc.program’s license ‘GPL’ is not ‘Dual MIT/GPL’, the license of the programs before it | license = "GPL" on one program of a file, and none on another |
the same license on every program |
| ‘half’ is a float, which a compiled function cannot hold | local half = math.sqrt(4) in the body |
an integer |
malformed number near ‘.5’, which lunatic prints before lunatic could not compile it |
2.5 |
an integer: the kernel’s Lua has no float |
| ‘while’, ‘repeat’ and a ‘goto’ backwards are not compiled yet | while, repeat, a goto backwards |
a numeric for |
| ‘for’ step is zero | for i = 1, 10, 0 |
a step that is not 0 |
| the map key -1 does not fit ‘I4’ | a key or a value outside its spec | a value its spec packs |
| module ‘byteorder’ not found | require of a C module | a Lua module under /lib/modules/lua/, or the directory --scripts names |
How a program file becomes a program
lunatik bpf -o filter.bpf.o filter.bpf.lua on the host
filter.bpf.lua
+----------------------------------------------------+
| the body runs once, now, on the host |
| map.array(counts, {...}) --> a map |
| xdp.program(fn, {...}) --> a program |
| the function compiled now, run later, per packet |
+----------------------------------------------------+
|
| 1. lunatic, the Lua compiler of the kernel, compiles the file:
| the bytecode the kernel would run, integers only
v
the chunk of the program file
|
| 2. the Lua of the CLI (lua5.5) runs the body from that chunk;
| require finds bpf.xdp, bpf.tc, bpf.map and lunatik,
| then the kernel scripts under /lib/modules/lua/, or the
| --scripts directory
v
the programs and the maps the body declared
|
| 3. the translator turns each program function, and each Lua
| function it calls, into eBPF instructions; outside the
| subset, lunatik: file:line: reason, exit 1, no object
v
eBPF instructions, each one tagged with its Lua line
|
| 4. the object is written for the kernel lunatik.config names,
| with the offsets of the context fields read from its BTF
v
filter.bpf.o installed as /usr/local/lib/bpf/luaebpf/filter.bpf.o
A program file, <name>.bpf.lua, may declare several programs. Each is named by the name its
constructor takes, or after the file, and lunatik run --dev attaches every one of them, as
Compiled programs describes.
lunatik bpf compiles for the kernel lunatik.config names, which make writes from the kernel
tree Lunatik is built against. Three facts of that kernel change what compiles:
- Linux 6.9 or later compiles a
forwhose bounds the program computes; an earlier kernel refuses it. - A kernel without efficient unaligned access refuses a read wider than a byte, from the packet or from a map value (#2047).
- The object takes the kernel’s byte order.
The offsets of the context fields come from the kernel’s BTF, /sys/kernel/btf/vmlinux unless
--btf names another file, so a program that reads its context, or the packet, compiles only
where that BTF is. Compiling for another kernel is in
Program files. A TC program needs libbpf 1.3.0 or later on
the machine that loads it.