docs

7 files changed, 59 insertions, 11 deletions

diff --git a/attic/README.md b/attic/README.md
index 83b6947c..768bccd4 100644
--- a/attic/README.md
+++ b/attic/README.md
@@ -1,7 +1,4 @@
-This directory is for old code that isn't used but we don't want to lose track of, and for anything else random like debug scripts.
-
-#### Some stuff other than shelved code:
+Retired Code and Miscellaneous Junk
+======
 
-multicast-trace-receiver.rb: receives multicast trace UDP packets from ZT_TRACE_MULTICAST
-
-encrypt, decrypt: useful shell scripts for AES-encrypting and decrypting files
+This directory is for old code that isn't used but we don't want to lose track of, and for anything else random like debug scripts.
diff --git a/control/README.md b/control/README.md
index 110bb3b8..c1c69a90 100644
--- a/control/README.md
+++ b/control/README.md
@@ -1 +1,4 @@
+ZeroTier Control Plane
+======
+
 This code is responsible for the local command bus used to control the ZeroTier One service on a local machine via zerotier-cli or the Qt GUI. It's not part of the core node implementation. It uses Unix domain sockets on unix-like OSes and named pipes on Windows. Authentication is via a simple token mechanism. (Eventually this part of the software is getting a rework.)
\ No newline at end of file
diff --git a/include/README.md b/include/README.md
new file mode 100644
index 00000000..80e2db5e
--- /dev/null
+++ b/include/README.md
@@ -0,0 +1,6 @@
+ZeroTier Node API
+======
+
+Not much to see here yet. In the future this will be the API for embedding ZeroTier One into another application.
+
+(Oh darn, I gave away some of our product road map. Shhhhhh!)
diff --git a/osnet/README.md b/osnet/README.md
new file mode 100644
index 00000000..114e26f2
--- /dev/null
+++ b/osnet/README.md
@@ -0,0 +1,6 @@
+Network and Virtual Network Port Interfaces for Real OSes
+======
+
+This folder contains implementations of EthernetTap, EthernetTapFactory, and RoutingTable that bind to operating system level interfaces and drivers on Linux, Mac, Windows, and other platforms.
+
+It also contains NativeSocketManager which implements SocketManager using standard sockets (or WinSock2) and select() for multiplexing.
diff --git a/osnet/README.txt b/osnet/README.txt
deleted file mode 100644
index 3101f3be..00000000
--- a/osnet/README.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-This folder contains implementations of EthernetTap, EthernetTapFactory, and
-RoutingTable that bind to operating system level interfaces and drivers on
-Linux, Mac, Windows, and other platforms.
diff --git a/testnet.cpp b/testnet.cpp
index 8af203ac..e2f04c67 100644
--- a/testnet.cpp
+++ b/testnet.cpp
@@ -25,6 +25,8 @@
  * LLC. Start here: http://www.zerotier.com/
  */
 
+/* SEE: testnet/README.md */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdint.h>
@@ -224,9 +226,10 @@ static void doHelp(const std::vector<std::string> &cmd)
 	printf("---------- listnetworks <address/*/**>"ZT_EOL_S);
 	printf("---------- listpeers <address/*/**>"ZT_EOL_S);
 	printf("---------- unicast <address/*/**> <address/*/**> <network ID> <frame length, min: 16> [<timeout (sec)>]"ZT_EOL_S);
-	printf("---------- multicast <address/*/**> <MAC/*> <network ID> <frame length, min: 16> [<timeout (sec)>]"ZT_EOL_S);
+	printf("---------- multicast <address/*/**> <MAC/* for bcast> <network ID> <frame length, min: 16> [<timeout (sec)>]"ZT_EOL_S);
 	printf("---------- quit"ZT_EOL_S);
-	printf("---------- . runs previous command again"ZT_EOL_S);
+	printf("---------- ( * means all regular nodes, ** means including supernodes )"ZT_EOL_S);
+	printf("---------- ( . runs previous command again )"ZT_EOL_S);
 }
 
 static void doMKSN(const std::vector<std::string> &cmd)
diff --git a/testnet/README.md b/testnet/README.md
new file mode 100644
index 00000000..6e128932
--- /dev/null
+++ b/testnet/README.md
@@ -0,0 +1,36 @@
+Headless Test Network
+======
+
+The code in testnet.cpp (in base) and here in testnet/ is for running headless ZeroTier One test networks.
+
+To build, type (from base) "make testnet". This will build the *zerotier-testnet* binary. Then run it with a directory to use for temporary node home directory storage as a parameter, e.g. "./zerotier-testnet /tmp/zttestnet".
+
+Type **help** for help.
+
+Right now the testnet simulates a perfect IP network and allows you to perform unicast and multicast tests. This is useful for verifying the basic correctness of everything under ideal conditions, and for smoke testing. In the future support for NAT emulation, packet loss, and other test features will be added to make this a more full-blown test suite.
+
+When you start the testnet for the first time, no nodes will exist. You have to create some. First, create supernodes with **mksn**. Create as many as you want. Once you've created supernodes (you can only do this once per testnet) you can create regular nodes with **mkn**.
+
+Once everything is created use **list** to check the status.
+
+Each node will create a couple threads, so if your OS imposes a limit this might cause some of your virtual nodes to stick in *INITIALIZING* status as shown in the **list** command. If this happens you might want to blow away the contents of your temp directory and try again with fewer nodes.
+
+Each node will get a home at the test path you specified, so quitting with **quit** and re-entering will reload the same test network.
+
+Next you'll need to join your nodes to a virtual ZeroTier network. ZeroTier supports a built-in "fake" public network with the ID **ffffffffffffffff**. This network is for testing and is convenient to use here. It's also possible to set up the netconf-master within one of your test nodes, but doing so is beyond the scope of this doc (for now, but if your clever you can probably figure it out). Verify by doing **listnetworks**.
+
+Now you can send some packets. Try:
+
+    unicast * * ffffffffffffffff 24 60
+
+That will do a unicast all-to-all test and report results. At first latencies might seem high, especially for a headless fake IP network. If you try it again you'll see them drop to zero or nearly so, since everyone will have executed a peer to peer connection.
+
+    multicast <some node's 10-digit ZT address> * ffffffffffffffff 24 60
+
+This will send a multicast packet to ff:ff:ff:ff:ff:ff (broadcast) and report back who receives it. You should see multicast propagation limited to 64 nodes, since this is the setting for multicast limit on the fake test network (and the default if not overridden in netconf). Multicast will show the same "warm up" behavior as unicast.
+
+Typing just "." will execute the same testnet command again.
+
+The first 10-digit field of each response is the ZeroTier node doing the sending or receiving. A prefix of "----------" is used for general responses to make everything line up neatly on the screen. We recommend using a wide terminal emulator.
+
+Enjoy!