Script the Linux kernel with Lua

luainkernel.github.io · 2026-10-05 · by Long Nguyen ·generic
Lunatik is a framework for scripting the Linux kernel with Lua.

Script the Linux kernel with Lua

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 +4 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 +19

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

  • Getting started: install, build, first script
  • Running scripts: the command line tool, execution contexts, `lunatic`
  • Per-CPU scripts: one runtime per CPU, and where state belongs
  • Lua in the kernel: what differs from userspace Lua
  • Examples: device drivers, packet filters, probes, filesystem guards
  • Lua API reference and C API
  • Development and Resources: tests, contributing, talks and papers

    • Support

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

  • Bitcoin: `bc1qx2quy25nx7g2akkxur2p3lyujager7zt2p6whu`
  • USDT on Solana: `Ci8sWwmCHhHYspaEiBUG7X25Ba94tXKxh3cfuycXBUu1`
  • USDT on Ethereum: `0x16c028E873A6E2aD87e81b4782D455AB470C09b4`

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\_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.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.pkttype | Linux kernel constants exposed under linux.pkttype. | | 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

| util | Utility functions. | | --------------------------------------------------------------- | ------------------ |

luainkernel.github.io · 137 links

Comments (0)

No comments yet