libuinet: a library version of FreeBSD's TCP/IP stack

Developed for WANProxy by Patrick Kelsey, libuinet is a library version of FreeBSD's TCP/IP stack. It is meant to be usable by userland programs on top of a host operating system, with a BSD sockets-like interface that can be used instead of or alongside kernel-provided sockets facilities.

Being developed for WANProxy, it includes features appropriate to the needs of a transparent proxy, such as the ability to terminate and reinitiate arbitrary TCP/IP connections, including retention of all Layer 2 information, such as nested VLAN tags. Applications only need to provide some way for packets to be received and transmitted by libuinet, if using the POSIX host interface.

libuinet was developed for userland use on FreeBSD, but every effort has been made to keep it as portable and flexible as possible. It comes with a host interface library appropriate for using libuinet on a POSIX-like system, but it would also be very easy to port it to run on another operating system kernel or as a server in a microkernel operating system. The set of APIs which need to be implemented for the host or application is minimal and well-defined. On FreeBSD, a packet driver is provided using the netmap facility by default; other packet drivers may be provided in the future, e.g. for packet transfer over Unix domain sockets, or a record-oriented protocol over TCP, UDP or other medium.

In addition to the abstraction changes required to use libuinet in userland applications, the aforementioned features for transparent proxying and others needed by WANProxy have been implemented. Again, care has been taken to keep those changes isolated and well-defined. The upshot of this is that it should be easy to keep libuinet up-to-date with newer versions of the FreeBSD TCP/IP stack, and it may be possible in time for the changes to become a part of FreeBSD itself.

Future Work

Passive Receive

Future work includes allowing the TCP/IP stack to be used in a passive mode, in which data can be read from both halves of a third-party connection for monitoring and security purposes. It may also be possible for these connections to become active connections at an arbitrary point if the application is inline. This allows, for instance, for a proxy to be able to watch initial protocol behaviour before deciding to cut in on a connection, so that connections which will be passed through need not be interrupted if, for example, it is determined that an incompatible or unsupported protocol is in-use.


At present, libuinet only supports IPv4, but the approach taken with that codebase should be easily-applicable to the IPv6 code as well.


Ongoing libuinet development is happening on GitHub.

Patrick Kelsey is giving a talk on libuinet at BSDCan 2014 in Ottawa, Ontario.

Copyright © 2008-2015