Some final README revs.

netcon/README.md

@@ -3,19 +3,19 @@ Network Containers (beta)
 
 ZeroTier Network Containers offers a microkernel-like networking paradigm for containerized applications and application-specific virtual networking.
 
-Network Containers couples the ZeroTier core Ethernet virtualization engine with a user-space TCP/IP stack and a library that intercepts calls to the Posix network API. This allows servers and applications to be used without modification or recompilation. It can be used to run services on virtual networks without elevated privileges, special configuration of the physical host, kernel support, or any other application specific configuration. It's ideal for use with [Docker](http://http://www.docker.com), [LXC](https://linuxcontainers.org), or [Rkt](https://coreos.com/rkt/docs/latest/) to build container images that automatically connect to a virtual network when deployed. It can also be used on a plain un-containerized Linux system to run applications on virtual networks without elevated privileges or system modification.
+Network Containers couples the ZeroTier core Ethernet virtualization engine with a user-space TCP/IP stack and a library that intercepts calls to the Posix network API. This allows servers and applications to be used without modification or recompilation. It can be used to run services on virtual networks without elevated privileges, special configuration of the physical host, kernel support, or any other application specific configuration. It's ideal for use with [Docker](http://http://www.docker.com), [LXC](https://linuxcontainers.org), or [Rkt](https://coreos.com/rkt/docs/latest/) to build containerized microservices that automatically connect to a virtual network when deployed. It can also be used on a plain un-containerized Linux system to run applications on virtual networks without elevated privileges or system modification.
 
 [More discussion can be found in our original blog announcement.](https://www.zerotier.com/blog/?p=490)
 
-Network Containers is currently in **beta** and is suitable for testing, experimentation, and prototyping. There are still some issues with compatibility with some applications as documented in the compatibility matrix below. There's also some remaining work to be done on performance and overall stability before this will be ready for production use.
+Network Containers is currently in **beta** and is suitable for testing and experimentation. Only Linux is supported. Future updates will focus on compatibility, full stack support, and improved performance, and may also port to other OSes.
 
 # Limitations and Compatibility
 
-The current version of Network Containers **only supports TCP over IPv4**. There is no IPv6 support and no support for UDP or ICMP (or RAW sockets). That means network-containerizing *ping* won't work, nor will UDP-based apps like VoIP servers, DNS servers, or P2P apps. IPv6 and other socket type support is coming in future releases.
+The beta version of Network Containers **only supports TCP over IPv4**. There is no IPv6 support and no support for UDP or ICMP (or RAW sockets). That means network-containerizing *ping* won't work, nor will UDP-based apps like VoIP servers, DNS servers, or P2P apps.
 
 The virtual TCP/IP stack will respond to *incoming* ICMP ECHO requests, which means that you can ping it from another host on the same ZeroTier virtual network. This is useful for testing.
 
-**Network Containers are currently all or nothing.** If engaged, the intercept library intercepts all network I/O calls and redirects them through the new path. A network-containerized application cannot communicate over the regular network connection of its host or container or with anything else except other hosts on its ZeroTier virtual LAN. Support for optional "fall-through" to the host IP stack for outgoing connections outside the virtual network and for gateway routes within the virtual network is planned. (It will be optional since in some cases this isolation might be considered a nice security feature.)
+**Network Containers are currently all or nothing.** If engaged, the intercept library intercepts all network I/O calls and redirects them through the new path. A network-containerized application cannot communicate over the regular network connection of its host or container or with anything else except other hosts on its ZeroTier virtual LAN. Support for optional "fall-through" to the host IP stack for outgoing connections outside the virtual network and for gateway routes within the virtual network is planned. (It will be optional since in some cases total network isolation might be considered a nice security feature.)
 
 #### Compatibility Test Results
 
@@ -46,9 +46,9 @@ Unlike *zerotier-one*, *zerotier-netcon-service* does not need to be run with ro
 
 # Starting the Network Containers Service
 
-You don't need Docker or any other container engine to try Network Containers. A simple test can be performed in user space in your own home directory.
+You don't need Docker or any other container engine to try Network Containers. A simple test can be performed in user space (no root) in your own home directory.
 
-First, build the netcon service and intercept library as described above. Then create a directory to act as a temporary ZeroTier home for your test netcon service instance. You'll need to move the liblwip.so binary that was built with *make netcon* into there, since the service must be able to find it there and load it.
+First, build the netcon service and intercept library as described above. Then create a directory to act as a temporary ZeroTier home for your test netcon service instance. You'll need to move the *liblwip.so* binary that was built with *make netcon* into there, since the service must be able to find it there and load it.
 
     mkdir /tmp/netcon-test-home
     cp -f ./netcon/liblwip.so /tmp/netcon-test-home
@@ -57,7 +57,7 @@ Now you can run the service (no sudo needed, and *-d* tells it to run in the bac
 
     ./zerotier-netcon-service -d -p8000 /tmp/netcon-test-home
 
-As with ZeroTier One in its normal incarnation, you'll need to join a network:
+As with ZeroTier One in its normal incarnation, you'll need to join a network for anything interesting to happen:
 
     ./zerotier-cli -D/tmp/netcon-test-home join 8056c2e21c000001
 
@@ -83,33 +83,36 @@ Now you can run an application inside your network container.
 
     export LD_PRELOAD=`pwd`/libzerotierintercept.so
     export ZT_NC_NETWORK=/tmp/netcon-test-home/nc_8056c2e21c000001
-    python -m SimpleHTTPServer 80
+    python -m SimpleHTTPServer
 
-(If you are using Python 3, use "-m http.server".)
+If you are running Python 3, use "-m http.server". Also note that the "pwd" in LD_PRELOAD assumes you are in the ZeroTier source root and have built netcon there. If not, substitute the full path to *libzerotierintercept.so*. If you want to remove those environment variables later, use "unset LD_PRELOAD" and "unset ZT_NC_NETWORK".
 
-Note the lack of sudo, even to bind to port 8080. That's because you're not binding to port 80, at least not as far as the Linux kernel is concerned. If all went well the HTTP server is now listening, but only inside the network container. Going to port 80 on your machine won't work. To reach it, go to the other system where you joined the same network with a conventional ZeroTier instance and try:
+If all went well a small static HTTP server is now serving up the current directory, but only inside the network container. Going to port 80 on your machine won't work. To reach it, go to the other system where you joined the same network with a conventional ZeroTier instance and try:
 
     curl http://NETCON.INSTANCE.IP/
 
 Replace *NETCON.INSTANCE.IP* with the IP address that *zerotier-netcon-service* was assigned on the virtual network. (This is the same IP you pinged in your first test.) If everything works, you should get back a copy of ZeroTier One's main README.md file.
 
-In the original shell where you ran *python -m SimpleHTTPServer* you can type CTRL+C to kill it. To turn off network containers you can clear the environment variables:
+# Installing in a Docker container (or any other container engine)
 
-    unset LD_PRELOAD
+If it's not immediately obvious, installation into a Docker container is easy. Just install *zerotier-netcon-service*, *libzerotierintercept.so*, and *liblwip.so* into the container at an appropriate locations. We suggest putting it all in */var/lib/zerotier-one* since this is the default ZeroTier home and will eliminate the need to supply a path to any of ZeroTier's services or utilities. Then, in your Docker container entry point script launch the service with *-d* to run it in the background, set the appropriate environment variables as described above, and launch your container's main application.
-    unset ZT_NC_NWID
-
-# Installing in a Docker Container (or any other container engine)
-
-If it's not immediately obvious, installation into a Docker container is easy. Just install *zerotier-netcon-service*, *libzerotierintercept.so*, and *liblwip.so* into the container at an appropriate location. We suggest putting it all in */var/lib/zerotier-one* since this is the default ZeroTier home and will eliminate the need to supply a path to any of ZeroTier's services or utilities. Then, in your Docker container entry point script launch the service with *-d* to run it in the background, set the appropriate environment variables as described above, and launch your container's main application.
 
 The only bit of complexity is configuring which virtual network to join. ZeroTier's service automatically joins networks that have *.conf* files in *ZTHOME/networks.d* even if the *.conf* file is empty. So one way of doing this very easily is to add the following commands to your Dockerfile or container entry point script:
 
     mkdir -p /var/lib/zerotier-one/networks.d
     touch /var/lib/zerotier-one/networks.d/8056c2e21c000001.conf
 
-Replace 8056c2e21c000001 with the network ID of the network you want your container to join.
+Replace 8056c2e21c000001 with the network ID of the network you want your container to automatically join. It's also a good idea in your container's entry point script to add a small loop to wait until the container's instance of ZeroTier generates an identity and comes online. This could be something like:
 
-Now your container will automatically join the specified network on startup. Authorizing the container on a private network still requires a manual authorization step either via the ZeroTier Central web UI or the API. We're working on some ideas to automate this via bearer token auth or similar since doing this manually or with scripts for large deployments is tedious. We'll have something in this area by the time Network Containers itself is ready to be pronounced no-longer-beta.
+    /var/lib/zerotier-one/zerotier-netcon-service -d
+    while [ ! -f /var/lib/zerotier-one/identity.secret ]; do
+      sleep 0.1
+    done
+    # zerotier-netcon-service is now running and has generated an identity
+
+(Be sure you don't bundle the identity into the container, otherwise every container will try to be the same device and they will "fight" over the device's address.)
+
+Now each new instance of your container will automatically join the specified network on startup. Authorizing the container on a private network still requires a manual authorization step either via the ZeroTier Central web UI or the API. We're working on some ideas to automate this via bearer token auth or similar since doing this manually or with scripts for large deployments is tedious.
 
 # Docker-based Unit Tests