Lunatik

• Index

Contents

• xdp

Modules

• completion
• data
• device
• fib
• fifo
• linux
• lunatik
• lunatik.runner
• mailbox
• net
• netfilter
• notifier
• probe
• rcu
• socket
• socket.inet
• syscall
• syscall.table
• thread
• xdp
• xtable

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

action	Table of XDP action verdicts.
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

action

Table of XDP action verdicts. These constants define the possible return values from an XDP program (and thus from the Lua callback attached via xdp.attach) to indicate how the packet should be handled. (Constants from <uapi/linux/bpf.h>)

Fields:

• ABORTED integer Indicates an error; packet is dropped. (XDP_ABORTED)
• DROP integer Drop the packet silently. (XDP_DROP)
• PASS integer Pass the packet to the normal network stack. (XDP_PASS)
• TX integer Transmit the packet back out the same interface it arrived on. (XDP_TX)
• REDIRECT integer Redirect the packet to another interface or BPF map. (XDP_REDIRECT)

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 The Lua function to be called. This function 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 the xdp.action table (e.g., xdp.action.PASS, xdp.action.DROP).

Returns:

nil

Raises:

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

See also:

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