Lunatik 快速上手:3 条命令安装构建,写出你的第一个内核 Lua 脚本(Linux 6.6+)
Lunatik 快速上手:3 条命令安装构建,写出你的第一个内核 Lua 脚本(Linux 6.6+)
Lunatik 是一个用 Lua 脚本化 Linux 内核的开源框架,让内核 Lua 脚本运行在内核空间,直接驱动字符设备、Netfilter、XDP、kprobe 等内核设施。本文带你用 3 条命令完成 Lunatik 安装构建,并写出你的第一个内核 Lua 脚本,支持 Linux 6.6 及以上版本。
为什么要在内核里跑 Lua 脚本?
传统内核开发用 C 写驱动、编译、插拔模块,周期长、门槛高。Lunatik 把 Lua 解释器(以及设备、网络、探测等一整套 Lua API)放进内核,脚本通过命令行工具从用户空间加载管理——改脚本即改内核行为,无需重新编译 C 代码。
它能做什么?根据 README.md 的说明:
- 📱 字符设备驱动:用几十行 Lua 实现
/dev/xxx设备 - 🌐 包过滤与分类:Netfilter 钩子、XDP/TC eBPF 程序
- 🔍 kprobe 系统调用跟踪、fsnotify 文件系统守护
- 🧵 内核线程、socket、netlink、crypto、sched_ext 等
Lunatik 内核 Lua 脚本框架
安装前:确认系统与依赖
核心要求:Linux 6.6 或更新的内核(uname -r 确认),且内核需要 BTF 支持(检查 /sys/kernel/btf/vmlinux 是否存在)。
以 Debian/Ubuntu 为例,一键安装依赖(详见 doc/guide/01-getting-started.md):
sudo apt install git build-essential lua5.5 dwarves clang llvm libelf-dev \
libbpf-dev linux-headers-$(uname -r) linux-tools-common \
linux-tools-$(uname -r) pkg-config libpcap-dev m4
Arch Linux 用户可用:
sudo pacman -S git lua clang llvm m4 libbpf libpcap pkg-config base-devel pahole libelf linux-tools linux-headers
💡 如果发行版还没有 lua5.5 包,可以从源码编译安装到
/usr/bin/lua5.5,步骤见官方 Getting started 文档。lua-readline包可选,装上后 REPL 支持行编辑和历史记录。
3 条命令:克隆、构建、安装
打开终端,依次执行:
# 1. 克隆仓库(含子模块)
git clone --depth 1 --recurse-submodules https://gitcode.com/gh_mirrors/lu/lunatik.git
cd lunatik
# 2. 拷贝 BTF 并构建内核模块
sudo make btf_install
make
# 3. 安装模块、CLI 工具与 Lua 脚本
sudo make install
这 3 条命令各做了什么?
| 命令 | 作用 |
|---|---|
sudo make btf_install |
把当前运行内核的 BTF(/sys/kernel/btf/vmlinux)拷入模块构建头文件目录。它只服务当前内核版本;不做这一步,xdp、tc、scx 模块仍能加载,但内核日志会报 missing module BTF |
make |
编译内核模块、CLI 配套的 lunatic 编译器及 eBPF 加载器 |
sudo make install |
模块装到 /lib/modules/$(uname -r)/kernel/lunatik/,Lua 脚本装到 /lib/modules/lua/,lunatik 命令行装到 /usr/local/sbin/ |
模块划分(DEVICE、SOCKET、NETLINK、XDP、KPROBE 等约 26 个)都在 Makefile 中定义,可通过 CONFIG_LUNATIK_XXX := n 关闭不需要的模块。
验证安装:确认内核模块已加载
sudo lunatik load # 加载 Lunatik 内核模块
sudo lunatik status # 逐行显示各模块加载状态
sudo lunatik -V # 打印已加载的 Lunatik 版本
如果输出类似 device is loaded、linux is loaded 等,说明构建成功。
快速体验:REPL 与一行命令
不带参数运行 sudo lunatik 会进入 REPL,你敲的每一行 Lua 都直接在内核里执行:
sudo lunatik
> return _VERSION
5.5
也可以只执行一段代码(-e 参数,注意表达式需要 return):
sudo lunatik -e 'return _VERSION'
第一个内核 Lua 脚本:随机口令字符设备
Lunatik 官方示例是一个生成随机可打印 ASCII 字符的字符设备 /dev/passwd。把它保存为 /lib/modules/lua/passwd.lua(需要 root):
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) 回调
-- 生成随机 ASCII 可打印字符
return string.char(linux.random(32, 126))
end
-- 创建新的字符设备
device.new(driver)
然后运行并验证:
sudo lunatik run passwd # 创建 /dev/passwd
head -c 16 /dev/passwd # 读出 16 个随机口令字符
sudo lunatik stop passwd # 移除设备
短短十几行 Lua,就在内核里挂了一个真实可用的字符设备——这就是 Lunatik 的魅力。
跑一个官方示例:内核版 echo 服务器
make install 会把 examples/ 下全部示例装到 /lib/modules/lua/examples/。以 echod 为例——一个监听 127.0.0.1:1337 的回显服务器,每条连接由内核线程处理:
sudo lunatik spawn examples/echod/daemon # 启动内核回显服务
nc 127.0.0.1 1337
hello kernel!
hello kernel!
sudo lunatik stop examples/echod/daemon # 停止服务
更多示例(包过滤、DNS 黑名单、系统调用计数器等)及运行方式见 doc/guide/05-examples.md。
lunatik 命令速查
日常操作主要用到以下子命令(完整用法见 doc/guide/02-running-scripts.md):
| 命令 | 说明 |
|---|---|
lunatik |
进入 REPL,每行在内核执行 |
lunatik run <脚本> |
为 /lib/modules/lua/<脚本>.lua 创建运行时并执行 |
lunatik spawn <脚本> |
在内核线程中运行脚本(脚本需返回线程函数) |
lunatik stop <脚本> |
停止对应运行时 |
lunatik list |
查看当前运行中的所有脚本 |
lunatik load / status / unload |
管理内核模块 |
脚本执行上下文可选 process(默认)、softirq(Netfilter/XDP 钩子)、hardirq(kprobe 等中断上下文),通过 run --context=<上下文> 指定。
常见问题与注意事项
Q1:内核升级后 sudo lunatik 报 couldn't create /dev/lunatik 怎么办?
模块是针对单一内核版本安装在 /lib/modules/$(uname -r)/ 下的,升级内核后需安装新内核头文件,然后:
make clean
sudo make btf_install
make
sudo make install
Debian/Ubuntu 还可用 tools/debian_kernel_postinst_lunatik.sh 挂内核升级钩子自动重建。
Q2:卸载 Lunatik?
sudo lunatik unload
sudo make uninstall
Q3:构建依赖版本问题?
eBPF 加载器需要 libbpf 1.0+(Ubuntu 23.04+ 的包满足);CLI 运行在 /usr/bin/lua5.5 下,构建脚本也会调用 lua5.5。
总结与下一步
本文用 3 条命令完成了 Lunatik 的安装构建,并写出了第一个内核 Lua 字符设备脚本。接下来推荐:
- 📖 doc/guide/02-running-scripts.md:命令行工具、执行上下文与内核线程
- 📖 doc/guide/03-percpu.md:Per-CPU 脚本,每个 CPU 一个运行时
- 📖 doc/guide/08-luaebpf.md:实验性特性——把 Lua 函数编译成 eBPF,写成 XDP/TC 程序
- 🧪 tests/:覆盖 bpf、netfilter、socket、crypto 等的完整测试套件,是最好的 API 参考
用 Lua 写内核,从今天的第一段脚本开始吧!