Lunatik

Script the Linux kernel with Lua

Lunatik is a framework for scripting the Linux kernel with Lua. Scripts run inside the kernel and reach its facilities through Lua modules: character devices, Netfilter, XDP and TC hooks, kprobes, fsnotify, sched_ext, eBPF maps, sockets, netlink, crypto, kernel threads and more. A command line tool loads and manages them from user space, and a C API lets kernel modules do the same.

Get started API reference GitHub
  • 80 Lua modules
  • Linux 6.6 and later
  • Process, softirq and hardirq hooks
examples/systrack/probe.luaAbout this example
local probe  = require("probe")
local systab = require("syscall.table")
local rcu    = require("rcu")

local track = rcu.table()
local names = {}

for symbol, address in pairs(systab) do
	names[address] = names[address] == nil and symbol or false
end

local function count(address)
	local symbol = names[address]
	track[symbol] = (track[symbol] or 0) + 1
end

local handlers = {pre = count}

for address, symbol in pairs(names) do
	if symbol then
		probe.new(address, handlers)
	end
end

return function()
	return track
end

Runtime

Runtimes, kernel threads and the channels between them.

completion fifo lunatik lunatik.runner mailbox +1

Packets and eBPF

Netfilter, XDP and TC hooks, socket buffers and eBPF maps.

bpf bpf.map netfilter skb tc +1

Sockets and netlink

Kernel sockets, and rtnetlink and generic netlink sessions.

net netlink netlink.channel netlink.genl netlink.message +15

Tracing and scheduling

Kprobes, system call addresses and sched_ext.

probe scx syscall syscall.table

Devices and events

Character devices, HID drivers, notifier chains and fsnotify.

device fsnotify hid notifier

Data

Memory buffers, RCU tables, sets, byte order and records.

byteorder class data rcu set +1

Cryptography

The kernel crypto API and encrypted scripts.

crypto darken lighten crypto.hkdf crypto_aead +5

System

The kernel as a whole: time, CPUs, tasks and signals.

cpu linux signal task

Constants

Kernel constants, generated from its headers at build time.

linux.arphrd linux.bpf linux.dropreason linux.errno linux.eth +20

Lunatik supports Linux 6.6 and later. Its documentation is at luainkernel.github.io/lunatik. Join us on Matrix.

Here is an example of a character device driver written in Lua using Lunatik to generate random ASCII printable characters:

-- /lib/modules/lua/passwd.lua
--
-- implements /dev/passwd for generate passwords
-- usage: $ sudo lunatik run passwd
--        $ head -c <width> /dev/passwd

local device = require("device")
local linux  = require("linux")
local stat   = require("linux.stat")

local driver = {name = "passwd", mode = stat.IRUGO}

function driver:read() -- read(2) callback
 -- generate random ASCII printable characters
 return string.char(linux.random(32, 126))
end

-- creates a new character device
device.new(driver)

After sudo make install, save it as /lib/modules/lua/passwd.lua, as root. Then sudo lunatik run passwd creates /dev/passwd, head -c 16 /dev/passwd reads a password from it, and sudo lunatik stop passwd removes it.

Get started

git clone --depth 1 --recurse-submodules https://github.com/luainkernel/lunatik.git
cd lunatik && sudo make btf_install && make && sudo make install
sudo lunatik    # a REPL whose lines run in the kernel

Dependencies, OpenWRT and the first steps are in Getting started.

Documentation

Support

The preferred way to donate to Lunatik is in crypto, to one of these wallets:

Donations can also go through Lua’s account at Software in the Public Interest (SPI): use the PayPal button and write Lunatik in its optional note, so the donation is marked for this project.

Spreading the word about Lunatik is another way to contribute, and so is telling us how you use it: an issue describing what you run on Lunatik, in production or in a lab, helps shape what comes next. Starring the repository on GitHub helps too.

License

Lunatik is dual-licensed under MIT or GPL-2.0-only.

Lua submodule is licensed under MIT. For more details, see its Copyright Notice.

Klibc submodule is dual-licensed under BSD 3-Clause or GPL-2.0-only. For more details, see its LICENCE file.

API reference

Runtime

completion Lua bindings for kernel completion mechanisms.
fifo kfifo (kernel FIFO) implementation.
lunatik Manages Lunatik runtimes — isolated Lua states running in the kernel.
lunatik.runner Manages the execution and lifecycle of Lunatik scripts.
mailbox Inter-runtime communication mechanism using FIFOs and completions.
thread Kernel thread primitives.

Packets and eBPF

bpf Lua interface to eBPF.
bpf.map High-level view over pinned eBPF maps.
netfilter Lua interface to the Linux Netfilter framework.
skb Linux socket buffer interface.
tc Linux Traffic Control (TC) integration.
xdp eXpress Data Path (XDP) integration.

Sockets and netlink

net Network utility functions.
netlink The netlink namespace.
netlink.channel Generic netlink channel: a generic netlink family with one multicast group whose multicast/unicast are safe from softirq (netfilter hooks, XDP), for kernel-to-userspace delivery.
netlink.genl Generic netlink (NETLINK_GENERIC) interface.
netlink.message Netlink wire codec shared by the netlink modules.
netlink.nl80211 The nl80211 (wireless) namespace.
netlink.nl80211.ap Access Point control.
netlink.nl80211.interface Wireless interface management.
netlink.nl80211.station Station management.
netlink.nl80211.wiphy Wireless PHY (wiphy) listing.
netlink.rt The rtnetlink namespace.
netlink.rt.addr Interface address listing.
netlink.rt.link Network interface (link) management.
netlink.rt.route Kernel routing table interface.
netlink.rt.rule FIB rule (policy routing) interface.
netlink.session Netlink request/response session.
socket Low-level Lua interface for kernel networking sockets.
socket.inet Internet (AF_INET) socket operations.
socket.raw RAW AF_PACKET socket operations.
socket.unix UNIX domain socket (AF_UNIX) operations.

Tracing and scheduling

probe Places kprobes on kernel functions and runs Lua handlers when they are hit.
scx Linux Extensible Scheduler (sched_ext) integration.
syscall Accessing kernel system call information.
syscall.table A table mapping system call names to their kernel addresses.

Devices and events

device Low-level Lua interface for creating Linux character device drivers.
fsnotify Filesystem notification.
hid Writes a HID driver in Lua: it matches devices by id_table, and can fix a device’s report descriptor and rewrite its raw reports.
notifier Notifier chain mechanism.

Data

byteorder Converts integers between host, big-endian (network) and little-endian byte order, typically around the data accessors, which read and write in host order.
class Minimal class helper for the OOP-style modules (e.g.
data Direct memory access and manipulation.
rcu RCU-synchronized hash table.
set A set is a compact, immutable set of strings, queried by binary search.
struct Binary codec for fixed C struct layouts.

Cryptography

crypto Lua interface to the Linux Crypto API.
darken Encrypted Lua script execution using AES-256-GCM.
lighten Encrypted Lua script support (AES-256-GCM).
crypto.hkdf HMAC-based Extract-and-Expand Key Derivation Function (HKDF) based on RFC 5869.
crypto_aead Lua interface to AEAD (Authenticated Encryption with Associated Data) ciphers.
crypto_comp Lua interface to synchronous compression algorithms.
crypto_rng Lua interface to synchronous Random Number Generators (RNG).
crypto_shash Lua interface to synchronous message digest (hash) algorithms, including HMAC.
crypto_sig Lua interface to public key signature verification.
crypto_skcipher Lua interface to symmetric-key ciphers (SKCIPHER).

System

cpu Lua interface to Linux CPU abstractions.
linux Various Linux kernel facilities.
signal Sends signals to processes.
task Linux task interface.

Constants

linux.arphrd Linux kernel constants exposed under linux.arphrd.
linux.bpf Linux kernel constants exposed under linux.bpf.
linux.dropreason Linux kernel constants exposed under linux.dropreason.
linux.errno Linux kernel constants exposed under linux.errno.
linux.eth Linux kernel constants exposed under linux.eth.
linux.fsnotify Linux kernel constants exposed under linux.fsnotify.
linux.genl Linux kernel constants exposed under linux.genl.
linux.iff Linux kernel constants exposed under linux.iff.
linux.kbd Linux kernel constants exposed under linux.kbd.
linux.netdev Linux kernel constants exposed under linux.netdev.
linux.netlink Linux kernel constants exposed under linux.netlink.
linux.nf Linux kernel constants exposed under linux.nf.
linux.nl80211 Linux kernel constants exposed under linux.nl80211.
linux.notify Linux kernel constants exposed under linux.notify.
linux.packet Linux kernel constants exposed under linux.packet.
linux.rtnetlink Linux kernel constants exposed under linux.rtnetlink.
linux.scx Linux kernel constants exposed under linux.scx.
linux.signal Linux kernel constants exposed under linux.signal.
linux.socket Linux kernel constants exposed under linux.socket.
linux.stat Linux kernel constants exposed under linux.stat.
linux.syscall Linux kernel constants exposed under linux.syscall.
linux.task Linux kernel constants exposed under linux.task.
linux.tc Linux kernel constants exposed under linux.tc.
linux.vt Linux kernel constants exposed under linux.vt.
linux.xdp Linux kernel constants exposed under linux.xdp.

Other

set.image Builds a set from a set image, a file a tool writes in userspace.
util Utility functions.