UINET (User INET)
=============================================================================

This is a user-space port of the FreeBSD TCP/IP stack, begun with the
FreeBSD 9.1-RELEASE sources and many pieces of Kip Macy's user-space
port of an earlier version of the FreeBSD stack, libplebnet.

Unlike the stock FreeBSD TCP/IP stack, this stack can initiate and
terminate arbitrary TCP/IP connections, including those on
arbitrarily-nested VLANs.  Listen sockets can be bound to a wildcard
IP address (across everything on the wire, not just local interfaces),
wildcard port, and specific VLAN tag stacks.  L2 information for
accepted connections is available to the application.  Outbound
connections can be bound to any IP and port, as well as any MAC
address and VLAN tag stack.

This stack can also passively reconstruct TCP streams using a copy of
those streams' bidirectional packet flow.  Reconstruction can continue
even in the face of packet loss (in which case zero-filled holes in
the affected streams are reported to the application).

Packet I/O is currently accomplished via netmap or libpcap (although
the latter interface is relatively new and untested).


Branches
=============================================================================

The most up-to-date sources are on master.

A large merge to master was performed on 24 March 2016, which includes
API churn.  The pre-merge point was tagged as master_20160324.


Building libuinet and the sample programs
=============================================================================

GNU make is used to build libuinet and its sample programs.  Under
Linux, this is simply 'make', while under FreeBSD, this is available
as gmake.  The instructions that follow refer to 'gmake'.

To build everything after a clean checkout:

gmake 

To rebuild everything from scratch at any point:

gmake clean config all

If your netmap includes are not in the system include path,

gmake NETMAP_INCLUDES=<path to netmap includes> [targets...]

The make variable DEBUG_FLAGS provides a quick way to adjust the
optimization level and debug symbol generation.  For example:

gmake DEBUG_FLAGS="-O2 -ggdb" clean config all

The core of the demo programs are implemented in lib/libuinet_demo.
They can be run via the single front-end bin/multitool.

The currently functioning demo programs are:

connscale       A TCP connection generator/terminator
echo            A loopback server
passive         A passive reconstructor
passive_extract A passive reconstructor that extracts file from HTTP streams

Still waiting to be updated is:

echo++	        A C++ loopback server
tproxy          A transparent proxy


Notes
=============================================================================

The sysctl code (and likely more over time) uses libnv from
FreeBSD-HEAD to serialise data between processes.

Currently, the sysctl and vmstat tools that interact with a libuinet
instance are only buildable on FreeBSD hosts.