Press "Enter" to skip to content

PacketScript overview: A Lua scripting engine for in-kernel packet processing

Shahriar 0

As I was surfing the net, trying to find a way to prototype network protocols or features in Linux. I stumbled upon PacketScript.

PacketScript is the an implementation of the Lua VM inside Linux kernel. Such implementations aren’t new ,luak and lunatik have been existed for some time. However what makes PacketScript different is the ability to mangle network packets with Lua. Not just running Lua code in kernel. as a matter of fact PacketScript uses lunatik underneath as its Lua in kernel engine.

PacketScript is built on existing technologies, ensuring more future maintainability. It is built on iptables infrastructure and on existing xtable-addons platform. Using xtables-addons makes PacketScript needless of kernel patching and compiling. You simply need to install the kernel module. xtables-addons also provides help for adding features into iptables command line interface.

PacketScript was work of André Graf as his master thesis in University of Basel. Since its original publication of thesis and source code, It has gone unmaintained since. It is currently working and I’m not aware of any bugs but the lack of maintenance may make this project unsuitable for production usage (unless forked and maintained by yourself).

Note that PacketScript compiles on linux kernel 2.x. (unless you apply the patch)

Being very disappointed from the kernel version supported by PacketScript, I found a patch by OpenWrt team who has ported PacketScript to 4.x kernels! The patch is for OpenWrt but you can easily apply it to the source and build on any other distro. (I am using PacketScript on OpenWrt myself).

If you want to use PacketScript on OpenWrt you just need to select it in menuconfig (Network->IPTables->ipt-mod-lua).

We will use Debian stable (jessie) in this guide to learn the patching process. The same process can be used for other distros too. Let’s Start :

Note that despite installing, the module may not be loaded, to do so:

Note: Module may not be installed in a valid location in order to be detected by modprobe. use symlinks or change the Makefile accordingly. See this or this.

Now everything should be ready:


Destination NAT (DNAT)

Create a lua script like this (dnat.lua) :

Then push it into kernel like this:

It is recommended to utilize Netfilter matches and extensions and use PacketScript when they cannot do what you want for performance reasons.

I am prototyping some new features in PacketScript. If my employer agreed upon open sourcing those I will create a GitHub repo and update this post with this links.

No guide is available on the internet for PacketScript. I hope this post would be useful. I am glad to answer questions in comments. Let me know of your network prototyping tools.


Leave a Reply

Your email address will not be published. Required fields are marked *