Lunatik

• Index

Contents

• xdp

Modules

• byteorder
• completion
• cpu
• crypto
• darken
• data
• device
• fib
• fifo
• hid
• lighten
• linux
• linux.eth
• linux.kbd
• linux.netdev
• linux.nf
• linux.notify
• linux.signal
• linux.socket
• linux.stat
• linux.syscall
• linux.task
• linux.vt
• linux.xdp
• lunatik
• lunatik.runner
• mailbox
• net
• netfilter
• notifier
• probe
• rcu
• signal
• skb
• socket
• socket.inet
• socket.raw
• socket.unix
• syscall
• syscall.table
• thread
• xdp

Classes

• crypto.hkdf
• crypto_aead
• crypto_comp
• crypto_rng
• crypto_shash
• crypto_skcipher

Topics

• README

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().

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.

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_ctx, 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_ctx: 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 two arguments:
  1. buffer (data): A data object representing the network packet buffer (xdp_md). The data object points to xdp_ctx->data and its size is xdp_ctx->data_end - xdp_ctx->data.
  2. argument (data): A data object representing the arg passed from the eBPF program. Its size is arg_sz.

  The callback function should return an integer verdict, typically one of the values from linux.xdp (e.g., action.PASS, action.DROP).

Returns:

nil

Raises:

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

See also:

data

Usage:

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

local function my_packet_processor(packet_buffer, custom_arg)
  print("Packet received, size:", #packet_buffer)
  return 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()