Module tc

Linux Traffic Control (TC) integration.

This library allows Lua scripts to interact with the kernel's TC subsystem. It enables TC/eBPF programs to call Lua functions for packet processing, traffic shaping, filtering, and policy enforcement, providing a flexible way to implement custom networking logic in Lua at the ingress and egress layers of network stack.

The primary mechanism involves a TC program calling the bpf_luatc_run kfunc, which in turn invokes a Lua callback function previously registered using tc.attach().

Class tc_ctx

tc_ctx:action (action) Sets the TC verdict action for this packet.
tc_ctx:argument () Returns the argument data buffer passed from eBPF.
tc_ctx:skb () Returns the packet object for the current TC context.

tc

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


Class tc_ctx

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

Parameters:

  • action integer TC action constant (e.g. TC_ACT_OK, TC_ACT_SHOT, ...)
tc_ctx:argument ()
Returns the argument data buffer passed from eBPF.

Returns:

    data argument buffer
tc_ctx:skb ()
Returns the packet object for the current TC context.

Returns:

    skb

tc

attach (callback)

Registers a Lua callback function to be invoked by a TC/eBPF program. When a TC program calls the bpf_luatc_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_luatc_run kfunc is called from an eBPF program with the following signature: int bpf_luatc_run(char *key, size_t key__sz, struct __sk_buff *sk_buff, void *arg, size_t arg__sz)

  • key: A string identifying the Lunatik runtime (e.g., the script name like "examples/sniclassify/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).
  • sk_buff: The TC metadata context (struct __sk_buff *).
  • 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: A tc_ctx context object used to inspect the packet and control the TC verdict via tc_ctx:action.

    The callback need not return a value. If it sets no action, bpf_luatc_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_tc_handler.lua" which is run via lunatik run my_tc_handler.lua softirq)
local tc = require("tc")
local action = require("linux.tc")

local function my_traffic_shaper(ctx)
  local skb = ctx:skb()
  print("Packet received, size:", #skb)
  ctx:action(action.ACT_OK)
  return
end
tc.attach(my_traffic_shaper)

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

Returns:

    nil

Usage:

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