From 9883c885136a3e12252c4874438155ff83ec2ec5 Mon Sep 17 00:00:00 2001 From: Joseph Henry Date: Wed, 15 Jun 2016 14:31:11 -0700 Subject: [PATCH] broke readmes into finer-grained categories --- ...ocker_zt_sdk.md => docker_linux_zt_sdk.md} | 0 docs/linux_zt_sdk.md | 71 ++++++++++++++++ docs/unity3d_android_zt_sdk.md | 0 ...nity3d_zt_sdk.md => unity3d_ios_zt_sdk.md} | 0 docs/unity3d_osx_zt_sdk copy.md | 84 +++++++++++++++++++ integrations/README.md | 20 +++++ 6 files changed, 175 insertions(+) rename docs/{docker_zt_sdk.md => docker_linux_zt_sdk.md} (100%) create mode 100644 docs/linux_zt_sdk.md create mode 100644 docs/unity3d_android_zt_sdk.md rename docs/{unity3d_zt_sdk.md => unity3d_ios_zt_sdk.md} (100%) create mode 100644 docs/unity3d_osx_zt_sdk copy.md diff --git a/docs/docker_zt_sdk.md b/docs/docker_linux_zt_sdk.md similarity index 100% rename from docs/docker_zt_sdk.md rename to docs/docker_linux_zt_sdk.md diff --git a/docs/linux_zt_sdk.md b/docs/linux_zt_sdk.md new file mode 100644 index 0000000..d7a4e4b --- /dev/null +++ b/docs/linux_zt_sdk.md @@ -0,0 +1,71 @@ +Docker + ZeroTier SDK +==== + +Welcome! + +Imagine a flat, encrypted, no-configuration LAN for all of your Docker containers. + +This short tutorial will show you how to enable ZeroTier functionality for your Docker software container with little to no configuration. In this example we aim to build a Docker container with ZeroTier’s Network Container service bundled right in so that it’s effortless to hook any number of your services in the container up to your virtual network. + +**Step 1: Build the ZeroTier service binaries** + +From the ZeroTier source directory, `make netcon` Optionally, if you'd like to see some debug output during execution, use `make netcon NETCON_DEBUG=1` + +**Step 2: Build your Docker image** + +`docker build --tag=redis_test .` + +The example dockerfile below incorperates a few important elements: + +1) The ZeroTier service binaries +2) Whatever ZeroTier identity keys you plan on using (if you don't already have keys you wish to use, fret not! A new identity will be generated automatically). +3) The service we've chosen to use. In this case, redis. +``` +FROM fedora:23 +# Install apps +RUN yum -y update +RUN yum -y install redis-3.0.4-1.fc23.x86_64 +RUN yum clean all +# Add ZT files +RUN mkdir -p /var/lib/zerotier-one/networks.d +ADD netcon_identity.public /var/lib/zerotier-one/identity.public +ADD netcon_identity.secret /var/lib/zerotier-one/identity.secret +ADD *.conf /var/lib/zerotier-one/networks.d/ +ADD *.conf / +ADD *.name / +EXPOSE 9993/udp 6379/udp +# Install LWIP library used by service +ADD liblwip.so /var/lib/zerotier-one/liblwip.so +# Install syscall intercept library +ADD libztintercept.so / +RUN cp libztintercept.so lib/libztintercept.so +RUN ln -sf /lib/libztintercept.so /lib/libztintercept +ADD zerotier-cli / +Add zerotier-netcon-service / +# Install test scripts +ADD netcon_entrypoint.sh /netcon_entrypoint.sh +RUN chmod -v +x /netcon_entrypoint.sh +# Start ZeroTier-One +CMD ["./netcon_entrypoint.sh"] +``` + +**Step 3: Start your container** + +`docker run -d -it redis_test /bin/bash` + +**Step 4: From your container, set up environment variables** + +Set our application pre-load with `export LD_PRELOAD=./libztintercept.so`. This dynamically loads our intercept library into your application which allows us to re-direct its network calls to our virtual network. + +Tell the ZeroTier Network Containers service which network to connect to with `export ZT_NC_NETWORK=/var/lib/zerotier-one/nc_XXXXXXXXXXXXXXXX`. + +**Step 5: Run your new ZeroTier-enabled service** + +At this point, simply run your application as you normally would. It will be automatically intercepted and linked to the ZeroTier service (and hence your virtual networks!) + +`/usr/bin/redis-server --port 6379` + +*** +**Additional info** +If you'd like to know the IP address your service can be reached at on this particular virtual network, use the following: +`zerotier-cli -D/var/lib/zerotier-one/nc_XXXXXXXXXXXXXXXX listnetworks` diff --git a/docs/unity3d_android_zt_sdk.md b/docs/unity3d_android_zt_sdk.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/unity3d_zt_sdk.md b/docs/unity3d_ios_zt_sdk.md similarity index 100% rename from docs/unity3d_zt_sdk.md rename to docs/unity3d_ios_zt_sdk.md diff --git a/docs/unity3d_osx_zt_sdk copy.md b/docs/unity3d_osx_zt_sdk copy.md new file mode 100644 index 0000000..ee2e772 --- /dev/null +++ b/docs/unity3d_osx_zt_sdk copy.md @@ -0,0 +1,84 @@ +Unity3D + ZeroTier SDK +==== + +Welcome! + +We want your Unity apps to talk *directly* over a flat, secure, no-config virtual network without sending everything into the "cloud". Thus, we introduce the ZeroTier-Unity3D integration! + +Our implementation currently intends to be the bare minimum required to get your Unity application to talk over ZeroTier virtual networks. As a result, we've created an API that is very similar to the built-in Unity LLAPI. It's possible that higher-level functionality could be added in the future. + +*** +## Adding ZeroTier to your Unity app + +**Step 1: Create virtual ZeroTier [virtual network](https://my.zerotier.com/)** + +**Step 2: Add plugin** + - Create a folder called `Plugins` in `Assets` + - Place `ZeroTierUnity.bundle` in that folder + +**Step 3: Add script to some `GameObject`** + - Drag our `ZeroTier.cs` native plugin wrapper onto any `GameObject` + + +*** +## Examples + +Calling `ZeroTier.Init()` will start the network service in a separate thread. You can check if the service is running by checking `ZeroTier.IsRunning()`. Then, connecting and sending data to another endpoint would look something like the following: + +``` +public void zt_sample_network_test_thread() +{ + // Prepare sample data buffer + byte[] buffer = new byte[1024]; + Stream stream = new MemoryStream(buffer); + BinaryFormatter f = new BinaryFormatter(); + f.Serialize ( stream , "Welcome to the machine! (from Unity3D)" ); + + // Connect and send + int error; + Connect (0, "192.168.0.6", 8887, out error); + Send(connfd,buffer,0, out error); +} +``` + +Finally, when you're done running the service you can call `ZeroTier.Terminate()` + +*** +## API + +The API is designed to resemble the Unity LLAPI, so you'll see a few familiar functions but with a slight twist. + +- `Join(nwid)`: Joins a ZeroTier virtual network +- `Leave(nwid)`: Leaves a ZeroTier virtual network +- `AddHost(port)`: Creates a socket, and binds to that socket on the address and port given +- `Connect(fd, ip_address, port, out error)`: Connects to an endpoint associated with the given `fd` +- `Send(fd, buf, pos, out error)`: Sends data to the endpoint associated with the given `fd` +- `Recv(fd, buf, out error)`: Receives data from an endpoint associated with the given `fd` +- `Disconnect(fd)`: Closes a connection with an endpoint + +*** +## Design and structure of the ZeroTier Unity OSX Bundle + +XCode: +New XCode project +Select Cocoa bundle as target +Add C linkages to external functions +Build as 64bit (not universal) + +Unity: +Select x86_64 build target in `Build Settings` +In new C# script asset: + +``` +[DllImport ("ZeroTierUnity")] +private static extern int unity_start_service (); +``` + +Add asset to GameObject +Start ZT service + +*** +## Future Roadmap +With the ZeroTier sockets API in place, higher-level functionality such as lobbies, chat, and object synchronization could easily be built on top. + + diff --git a/integrations/README.md b/integrations/README.md index e9903a9..4853897 100644 --- a/integrations/README.md +++ b/integrations/README.md @@ -5,3 +5,23 @@ This is a collection of example projects demonstrating how you can embed or inte 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! + +*** +## Current Integrations + +### iOS + - [Embedding within an app](../docs/ios_zt_sdk.md) + - [Unity3D plugin](../docs/unity3d_ios_zt_sdk.md) + +### OSX + - [Embedding within an app](../docs/osx_zt_sdk.md) + - [Dynamic-linking into an app/service at runtime](../docs/osx_zt_sdk.md) + - [Unity3D plugin](../docs/unity3d_osx_zt_sdk.md) + +### Linux + - [Dynamic-linking into an app/service at runtime](../docs/linux_zt_sdk.md) + - [Using the SDK with Docker](../docs/docker_linux_zt_sdk.md) + +### Android + - [Embedding within an app](../docs/android_zt_sdk.md) + - [Unity 3D plugin](../docs/unity3d_android_zt_sdk.md)