Lunatik 快速上手:3 条命令安装构建,写出你的第一个内核 Lua 脚本(Linux 6.6+)

原创2026-11-15 13:21:311,954 阅读

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 字符设备脚本。接下来推荐:

用 Lua 写内核,从今天的第一段脚本开始吧!

登录后查看全文
lunatik