Module xdp

eXpress Data Path (XDP) integration.

This library allows Lua scripts to interact with the kernel's XDP subsystem. It enables XDP/eBPF programs to call Lua functions for packet processing, providing a flexible way to implement custom packet handling logic in Lua at a very early stage in the network stack.

The primary mechanism involves an XDP program calling the bpf_luaxdp_run kfunc, which in turn invokes a Lua callback function previously registered using xdp.attach.

Class xdp_ctx

xdp_ctx:action (action) Sets the XDP verdict action for this packet.
xdp_ctx:argument () Returns the argument data buffer passed from eBPF.
xdp_ctx:packet () Returns the packet data buffer for the current XDP context.

xdp

attach (callback) Registers a Lua callback function to be invoked by an XDP/eBPF program.
detach () Unregisters the Lua callback function associated with the current Lunatik runtime.


Class xdp_ctx

XDP callback context, valid only while the callback runs. It is handed to the callback registered with xdp.attach; its methods raise once the callback returns.
xdp_ctx:action (action)
Sets the XDP verdict action for this packet.

Parameters:

  • action integer XDP action constant (e.g. XDP_PASS, XDP_DROP, ...)
xdp_ctx:argument ()
Returns the argument data buffer passed from eBPF.

Returns:

    data argument buffer
xdp_ctx:packet ()
Returns the packet data buffer for the current XDP context.

Returns:

    data packet buffer

xdp

attach (callback)

Registers a Lua callback function to be invoked by an XDP/eBPF program. When an XDP program calls the bpf_luaxdp_run kfunc, Lunatik will execute the registered Lua callback associated with the current Lunatik runtime. The runtime invoking this function must be non-sleepable.

The bpf_luaxdp_run kfunc is called from an eBPF program with the following signature: int bpf_luaxdp_run(char *key, size_t key_sz, struct xdp_md *xdp_md, void *arg, size_t arg_sz)

  • key: A string identifying the Lunatik runtime (e.g., the script name like "examples/filter/sni"). This key is used to look up the runtime in Lunatik's internal table of active runtimes.
  • key_sz: Length of the key string (including the null terminator).
  • xdp_md: The XDP metadata context (struct xdp_md *).
  • arg: A pointer to arbitrary data passed from eBPF to Lua.
  • arg_sz: The size of the arg data.

Parameters:

  • callback function Lua function to call. It receives one argument:

    ctx: An xdp_ctx context object used to inspect the packet and control the XDP verdict via xdp_ctx:action.

    The callback need not return a value. If it sets no action, bpf_luaxdp_run returns -1 and the verdict is left to the eBPF program.

Returns:

    nil

Raises:

Error if the current runtime is sleepable or if internal setup fails.

See also:

Usage:

    -- Lua script (e.g., "my_xdp_handler.lua" which is run via lunatik run my_xdp_handler.lua softirq)
local xdp = require("xdp")
local action = require("linux.xdp")

local function my_packet_processor(ctx)
  local pkt = ctx:packet()
  print("Packet received, size:", #pkt)
  ctx:action(action.PASS)
end
xdp.attach(my_packet_processor)

-- In eBPF C code, to call the above Lua function:
-- char rt_key[] = "my_xdp_handler.lua"; // Key matches the script name
-- int verdict = bpf_luaxdp_run(rt_key, sizeof(rt_key), ctx, NULL, 0);
detach ()
Unregisters the Lua callback function associated with the current Lunatik runtime. After calling this, bpf_luaxdp_run calls targeting this runtime will no longer invoke a Lua function (they will likely return an error or default action).

Returns:

    nil

Usage:

    xdp.detach()
generated by LDoc 1.5.0 Last updated 2026-09-05 12:27:44