gfwleak/zhangyang-libzt
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moved unit test section to its own file

Browse Source
This commit is contained in:
Joseph Henry
2016-06-15 10:42:46 -07:00
parent c1cdeeb478
commit 7216a83eb3
3 changed files with 60 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@@ -18,11 +18,11 @@ The SDK works on Linux and has been lightly tested on OSX. To build the service
This will build a binary called `zerotier-sdk-service` and a library called `libztintercept.so`. It will also build the IP stack as `src/liblwip.so`.
To enable debug trace statements for Network Containers, use `-D\_SDK\_DEBUG`
To enable debug trace statements for Network Containers, use `-D_SDK_DEBUG`
The `zerotier-sdk-service` binary is almost the same as a regular ZeroTier One build except instead of creating virtual network ports using Linux's `/dev/net/tun` interface, it creates instances of a user-space TCP/IP stack for each virtual network and provides RPC access to this stack via a Unix domain socket. The latter is a library that can be loaded with the Linux `LD\_PRELOAD` environment variable or by placement into `/etc/ld.so.preload` on a Linux system or container. Additional magic involving nameless Unix domain socket pairs and interprocess socket handoff is used to emulate TCP sockets with extremely low overhead and in a way that's compatible with select, poll, epoll, and other I/O event mechanisms.
The `zerotier-sdk-service` binary is almost the same as a regular ZeroTier One build except instead of creating virtual network ports using Linux's `/dev/net/tun` interface, it creates instances of a user-space TCP/IP stack for each virtual network and provides RPC access to this stack via a Unix domain socket. The latter is a library that can be loaded with the Linux `LD_PRELOAD` environment variable or by placement into `/etc/ld.so.preload` on a Linux system or container. Additional magic involving nameless Unix domain socket pairs and interprocess socket handoff is used to emulate TCP sockets with extremely low overhead and in a way that's compatible with select, poll, epoll, and other I/O event mechanisms.
The intercept library does nothing unless the `ZT\_NC\_NETWORK` environment variable is set. If on program launch (or fork) it detects the presence of this environment variable, it will attempt to connect to a running `zerotier-sdk-service` at the specified Unix domain socket path.
The intercept library does nothing unless the `ZT_NC_NETWORK` environment variable is set. If on program launch (or fork) it detects the presence of this environment variable, it will attempt to connect to a running `zerotier-sdk-service` at the specified Unix domain socket path.
Unlike `zerotier-one`, `zerotier-sdk-service` does not need to be run with root privileges and will not modify the host's network configuration in any way. It can be run alongside `zerotier-one` on the same host with no ill effect, though this can be confusing since you'll have to remember the difference between "real" host interfaces (tun/tap) and network containerized endpoints. The latter are completely unknown to the kernel and will not show up in `ifconfig`.
@@ -126,56 +126,9 @@ Replace 8056c2e21c000001 with the network ID of the network you want your contai
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
# Tests
Each unit test will temporarily copy all required ZeroTier binaries into its local directory, then build the `netcon_dockerfile` and `monitor_dockerfile`. Once built, each container will be run and perform tests and monitoring specified in `netcon_entrypoint.sh` and `monitor_entrypoint.sh`
Results will be written to the `tests/docker-test/_results/` directory which is a common shared volume between all containers involved in the test and will be a combination of raw and formatted dumps to files whose names reflect the test performed. In the event of failure, `FAIL.` will be prepended to the result file's name (e.g. `FAIL.my_application_1.0.2.x86_64`), likewise in the event of success, `OK.` will be prepended.
To run unit tests:
1) Disable SELinux. This is so the containers can use a shared volume to exchange MD5 sums and address information.
2) Set up your own network at [https://my.zerotier.com/](https://my.zerotier.com/). For our example we'll just use the Earth network (8056c2e21c000001). Use its network id as follows:
3) Generate two pairs of identity keys. Each public/private pair will be used by the *netcon* and *monitor* containers:
mkdir -p /tmp/netcon_first
cp -f ./netcon/liblwip.so /tmp/netcon_first
./zerotier-netcon-service -d -p8100 /tmp/netcon_first
while [ ! -f /tmp/netcon_first/identity.secret ]; do
sleep 0.1
done
./zerotier-cli -D/tmp/netcon_first join 8056c2e21c000001
kill `cat /tmp/netcon_first/zerotier-one.pid`
mkdir -p /tmp/netcon_second
cp -f ./netcon/liblwip.so /tmp/netcon_second
./zerotier-netcon-service -d -p8101 /tmp/netcon_second
while [ ! -f /tmp/netcon_second/identity.secret ]; do
sleep 0.1
done
./zerotier-cli -D/tmp/netcon_second join 8056c2e21c000001
kill `cat /tmp/netcon_second/zerotier-one.pid`
4) Copy the identity files to your *docker-test* directory. Names will be altered during copy step so the dockerfiles know which identities to use for each image/container:
cp /tmp/netcon_first/identity.public ./netcon/docker-test/netcon_identity.public
cp /tmp/netcon_first/identity.secret ./netcon/docker-test/netcon_identity.secret
cp /tmp/netcon_second/identity.public ./netcon/docker-test/monitor_identity.public
cp /tmp/netcon_second/identity.secret ./netcon/docker-test/monitor_identity.secret
5) Place a blank network config file in the `netcon/docker-test` directory (e.g. "8056c2e21c000001.conf")
- This will be used to inform test-specific scripts what network to use for testing
After you've created your network and placed its blank config file in `tests/docker-test` run the following to perform unit tests for httpd:
./build.sh httpd
./test.sh httpd
It's useful to note that the keyword *httpd* in this example is merely a substring for a test name, this means that if we replaced it with *x86_64* or *fc23*, it would run all unit tests for *x86_64* systems or *Fedora 23* respectively.
For info on testing the SDK, take a look at [docs/testing.md](docs/testing.md)
# Mobile App Embedding

54
docs/testing.md Normal file
View File

@@ -0,0 +1,54 @@
Testing
====
# Docker Unit Tests
Each unit test will temporarily copy all required ZeroTier binaries into its local directory, then build the `netcon_dockerfile` and `monitor_dockerfile`. Once built, each container will be run and perform tests and monitoring specified in `netcon_entrypoint.sh` and `monitor_entrypoint.sh`
Results will be written to the `tests/docker-test/_results/` directory which is a common shared volume between all containers involved in the test and will be a combination of raw and formatted dumps to files whose names reflect the test performed. In the event of failure, `FAIL.` will be prepended to the result file's name (e.g. `FAIL.my_application_1.0.2.x86_64`), likewise in the event of success, `OK.` will be prepended.
To run unit tests:
1) Disable SELinux. This is so the containers can use a shared volume to exchange MD5 sums and address information.
2) Set up your own network at [https://my.zerotier.com/](https://my.zerotier.com/). For our example we'll just use the Earth network (8056c2e21c000001). Use its network id as follows:
3) Generate two pairs of identity keys. Each public/private pair will be used by the *netcon* and *monitor* containers:
mkdir -p /tmp/netcon_first
cp -f ./netcon/liblwip.so /tmp/netcon_first
./zerotier-netcon-service -d -p8100 /tmp/netcon_first
while [ ! -f /tmp/netcon_first/identity.secret ]; do
sleep 0.1
done
./zerotier-cli -D/tmp/netcon_first join 8056c2e21c000001
kill `cat /tmp/netcon_first/zerotier-one.pid`
mkdir -p /tmp/netcon_second
cp -f ./netcon/liblwip.so /tmp/netcon_second
./zerotier-netcon-service -d -p8101 /tmp/netcon_second
while [ ! -f /tmp/netcon_second/identity.secret ]; do
sleep 0.1
done
./zerotier-cli -D/tmp/netcon_second join 8056c2e21c000001
kill `cat /tmp/netcon_second/zerotier-one.pid`
4) Copy the identity files to your *docker-test* directory. Names will be altered during copy step so the dockerfiles know which identities to use for each image/container:
cp /tmp/netcon_first/identity.public ./netcon/docker-test/netcon_identity.public
cp /tmp/netcon_first/identity.secret ./netcon/docker-test/netcon_identity.secret
cp /tmp/netcon_second/identity.public ./netcon/docker-test/monitor_identity.public
cp /tmp/netcon_second/identity.secret ./netcon/docker-test/monitor_identity.secret
5) Place a blank network config file in the `netcon/docker-test` directory (e.g. "8056c2e21c000001.conf")
- This will be used to inform test-specific scripts what network to use for testing
After you've created your network and placed its blank config file in `tests/docker-test` run the following to perform unit tests for httpd:
./build.sh httpd
./test.sh httpd
It's useful to note that the keyword *httpd* in this example is merely a substring for a test name, this means that if we replaced it with *x86_64* or *fc23*, it would run all unit tests for *x86_64* systems or *Fedora 23* respectively.

2
integrations/README.md
View File

@@ -3,5 +3,5 @@ ZeroTier Integrations
This is a collection of example projects demonstrating how you can embed or integrate ZeroTier functionality directly into your applications and games with *little to no change to your code*.
For more support on these integrations take a look at the [docs/](http://10.6.6.2/ZeroTier/ZeroTierSDK/src/master/docs) folder. Specifically the [Shims](../docs/shims_zt_sdk.md) and [SDK API](../docs/zt_sdk.md) overviews.
For more support on these integrations take a look at the [docs/](../docs) folder. Specifically the [Shims](../docs/shims_zt_sdk.md) and [SDK API](../docs/zt_sdk.md) overviews.
Also stop by our [community section](https://www.zerotier.com/community/) for more in-depth discussion!