Updated README.md

netcon/README.md

@@ -1,3 +1,97 @@
+ZeroTier Network Containers 'service' and 'intercept'
+======
+ZeroTier Network Containers is a blisteringly-fast and easy-to-use networking integration for Docker containers.
+
+
+### Functional Overview:
+
+This system exists as a dynamically-linked library, and a stand-alone background service.
+
+The intercept is compiled as a shared library and installed in some user-accessible directory. When you want to intercept
+a user application you dynamically link the shared library to the application during runtime. When the application starts, the 
+intercept's global constructor is called which sets up a hidden pipe which is used to communicate remote procedure calls (RPC) to the host Netcon service running in the background.
+
+When an RPC for a socket() is received by the Netcon service from the harnessed application, the Netcon service will ask the lwIP stack for a new PCB structure (used to represent a connection), if the system permits its allocation, it will be passed to Netcon where a PCB/socket table entry will be created. The table is used for mapping [callbacks from lwIP] and [RPCs from the intercept] to the correct connections.
+
+Upon the first call to a intercept-overriden system call, a Unix-domain socket is opened between the Netcon service and the application's intercept. This socket provides us the ability to pass file descriptors of newly-created socketpairs to the intercept (used as the read/write buffer). More specifically, after the socketpair creation, one end is kept in a table entry in Netcon and one end is sent to the intercept.
+
+### Reading and Writing from application
+When the application reads or writes data to a socket, the intercept will override the call and read/write from one end of the socketpair created for that specific connection. The Netcon service is continually polling the file descriptors for the opposite end of the socketpair. When an available event is detected (such as the presence of data on the buffer), Netcon will consult the routing table and determine which PCB should receive this new data. A call is then made to lwIP's tcp_write(). 
+
+### How Netcon receives data
+When data is received by lwIP, a callback in the Netcon service is called which then consults the internal routing table and maps the data to the correct socketpair. From here, it's up to the harnessed application to either poll() the opposite end of the socketpair, or read from it. No notification is sent to the intercept.
+
+
+
+### Building from Source (and Installing)
+
+Build library:
+
+    make lib
+
+Build service:
+
+    make service
+
+Build test applications (linked with library):
+
+    make tests
+
+Install:
+
+    make install
+
+
+
+### Running
+
+To start a service and automatically intercept an application:
+
+    ./service my_app
+
+Alternatively, to intercept a specific application (requires an already running service):
+
+    intercept ./my_app
+
+To start the Network Containers service:
+
+    ./service
+
+To monitor lwIP network I/O:
+
+    tcpdump -l -n -i tap0
+
+Show what dynamic libraries are set for inclusion:
+
+    intercept show
+
+Start example server (with harness):
+
+    intercept ./test_tx.o 
+
+Start example client (with intercept) to communicate with server:
+
+    intercept ./test_rx.o 127.0.0.1
+
+
+
+### Testing
+
+To run a simple RX/TX test:
+
+    make service
+    make lib
+    make install
+    make tests
+    
+    ./service
+    ./multitransfer.sh
+
+
+
+
+### Compatibility
+
 Network Containers have been tested with the following:
 
 sshd			[ WORKS as of 20151022] Long ~15-20s delay for client during connect
@@ -29,6 +123,8 @@ To Test:
 
 
 
+### Extended Version Notes
+
 20151027 Added Redis-server support
 Notes:
  - Added extra logic to detect socket re-issuing and consequent service-side double mapping.