luaebpf

bpf.xdpModule

Declares an XDP program in a program file.

The body of a program file runs on the host under lunatik bpf; the function it hands to program is compiled to eBPF and runs in the kernel on each packet the device receives. It takes one argument, the context, and returns a verdict, a value of linux.xdp.action, as a kernel script’s xdp callback does. Where it computes a verdict that is no action, and where Lua would raise, at a read past the packet or a division by 0, the program stops and returns XDP_ABORTED, the kernel’s verdict for a program error, which drops the packet, and logs the error Lua raises there, <file>:<line>: <reason>, to the kernel’s trace ring through bpf_trace_printk, ten lines every five seconds at most, and counts every stop at that line, which lunatik bpf --errors reports; where it returns no value, it returns the default verdict its constructor names. A verdict the compiler holds that is no action, and a boolean, are refused, “the verdict 11 is not an XDP action” and “the verdict may be a boolean here; return an action”.

The context has the methods of the kernel’s XDP ctx object: ctx:packet(), the packet, read with getbyte, getint16 and the other reads of the kernel’s data object, in the kernel’s byte order, or a field at a time through the view a struct codec makes of it, iphdr:view(p, eth.HLEN).protocol<code>, as </code>codec:view<code> reads a </code>data<code> object; </code>ctx:ingress(), the index of the device the packet arrived on; and ctx:queue(), the receive queue it arrived in, neither writable. Any other method is refused, “the context has no method ‘’”. ctx.data and ctx.data_end are the bounds of the packet, not numbers; #p is its length.

A call into a kernel Lua runtime lunatik.runtime names, r:run(a, b), lowers to bpf_luaxdp_run: it answers the verdict the callback xdp.attach registered returns, or nil, and the program tests the answer before it reads it. The kernel loads a program that calls it, or that may stop, only under a license it counts as GPL-compatible.

Usage

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"))

return xdp.program(function(ctx)
    local p = ctx:packet()
    if ethhdr:view(p, 0).h_proto == eth.proto.IP then
        return action.DROP
    end
    return action.PASS
end, {default = action.PASS})

Functions

bpf.xdp.program (fn, opts) Declares fn as an XDP program.

Functions in detail

bpf.xdp.program (fn, opts)
Declares fn as an XDP program.

Parameters

  • fn function the program; it takes the context and returns a verdict.
  • opts table default, required, the verdict the program returns where its function returns no value, an action, name, what the program is called in the object, cut to the fifteen characters BPF_OBJ_NAME_LEN leaves and made unique against the names already taken, and license, a string, the license the object declares for every program of the file, Dual MIT/GPL where it names none.

Returns

    table the declared program

Raises

xdp.program takes a Lua function, or <file>:<line>: xdp.program's default verdict is not an integer, which a missing default raises too, or is not an XDP action, or <file>:<line>: xdp.program's license is not a string or '<license>' is not '<before>', the license of the programs before it, the line where fn is defined