broke readmes into finer-grained categories

This commit is contained in:
Joseph Henry
2016-06-15 14:31:11 -07:00
parent c46bc402e0
commit 9883c88513
6 changed files with 175 additions and 0 deletions

71
docs/linux_zt_sdk.md Normal file
View File

@@ -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 ZeroTiers Network Container service bundled right in so that its 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`

View File

View File

@@ -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.

View File

@@ -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)